Get Endpoint

post /public_api/v1/endpoints/get_endpoint

Gets a list of filtered endpoints.

The response is concatenated using AND condition (OR is not supported).
The maximum result set size is 100.
Offset is the zero-based number of endpoints from the start of the result set.

Required license: Cortex XDR Prevent or Cortex XDR Pro per Endpoint

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

Accept-Encoding String

For retrieving a compressed gzipped response

Example: acceptEncoding_example

Default: gzip

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: authorization_example'
          -H
          'x-xdr-auth-id: xXdrAuthId_example'
          -H
          'Accept-Encoding: acceptEncoding_example'
      
      'https://api-yourfqdn/public_api/v1/endpoints/get_endpoint'
    
      -d
      ''

import http.client

conn = http.client.HTTPSConnection("api-yourfqdn")

payload = "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}"

headers = {
    'Authorization': "SOME_STRING_VALUE",
    'x-xdr-auth-id': "SOME_STRING_VALUE",
    'Accept-Encoding': "SOME_STRING_VALUE",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/endpoints/get_endpoint", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-yourfqdn/public_api/v1/endpoints/get_endpoint")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'SOME_STRING_VALUE'
request["x-xdr-auth-id"] = 'SOME_STRING_VALUE'
request["Accept-Encoding"] = 'SOME_STRING_VALUE'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "request_data": {
    "filters": [
      {
        "field": "endpoint_id_list",
        "operator": "in",
        "value": "string"
      }
    ],
    "search_from": 0,
    "search_to": 0,
    "sort": {
      "field": "endpoint_id",
      "keyword": "ASC"
    }
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api-yourfqdn/public_api/v1/endpoints/get_endpoint");
xhr.setRequestHeader("Authorization", "SOME_STRING_VALUE");
xhr.setRequestHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
xhr.setRequestHeader("Accept-Encoding", "SOME_STRING_VALUE");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/endpoints/get_endpoint")
  .header("Authorization", "SOME_STRING_VALUE")
  .header("x-xdr-auth-id", "SOME_STRING_VALUE")
  .header("Accept-Encoding", "SOME_STRING_VALUE")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "SOME_STRING_VALUE",
  "x-xdr-auth-id": "SOME_STRING_VALUE",
  "Accept-Encoding": "SOME_STRING_VALUE",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "filters": [
      [
        "field": "endpoint_id_list",
        "operator": "in",
        "value": "string"
      ]
    ],
    "search_from": 0,
    "search_to": 0,
    "sort": [
      "field": "endpoint_id",
      "keyword": "ASC"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/endpoints/get_endpoint")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-yourfqdn/public_api/v1/endpoints/get_endpoint",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}",
  CURLOPT_HTTPHEADER => [
    "Accept-Encoding: SOME_STRING_VALUE",
    "Authorization: SOME_STRING_VALUE",
    "content-type: application/json",
    "x-xdr-auth-id: SOME_STRING_VALUE"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "POST");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-yourfqdn/public_api/v1/endpoints/get_endpoint");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "x-xdr-auth-id: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "Accept-Encoding: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/endpoints/get_endpoint");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "SOME_STRING_VALUE");
request.AddHeader("x-xdr-auth-id", "SOME_STRING_VALUE");
request.AddHeader("Accept-Encoding", "SOME_STRING_VALUE");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"filters\":[{\"field\":\"endpoint_id_list\",\"operator\":\"in\",\"value\":\"string\"}],\"search_from\":0,\"search_to\":0,\"sort\":{\"field\":\"endpoint_id\",\"keyword\":\"ASC\"}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

application/json

request_dataobject

A dictionary containing the API request fields.

An empty dictionary returns all results.

filtersarray

Array of filter fields.

[

fieldstring (Enum)

Identifies the field the filter is matching. Filters are based on the following keywords:

endpoint_id_list: List of endpoint IDs.
endpoint_status: Status of the endpoint ID.
dist_name: Distribution / Installation Package name.
first_seen: When the agent was first seen.
last_seen: When the agent was last seen.
ip_list: List of IP addresses.
group_name: Group name the agent belongs to.
platform: Platform name.
alias: Alias name.
isolate: If the endpoint was isolated.
hostname: Host name.
public_ip_list: Public IP addresses that correlate to the last IPv4 address from which the XDR agent connected (know as Last Origin IP).

Allowed values:"endpoint_id_list""endpoint_status""dist_name""first_seen""last_seen""ip_list""group_name""platform""alias""isolate""hostname""public_ip_list"

operatorstring (Enum)

Identifies the comparison operator you want to use for this filter. Valid keywords and values are: in

endpoint_id_list, dist_name, group_name, alias, hostname, username, public_ip_list: List of strings.
endpoint_status: connected, disconnected, lost, or uninstalled
ip_list: List of strings. For example: "192.168.5.12"
platform: windows, linux, macos, android
isolate: isolated or unisolated
scan_status: none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error gte / lte
first_seen and last_seen: Timestamp epoch milliseconds.

Allowed values:"in""gte""lte""eq"

valuestring or array[string]

Value that this filter must match. Valid keywords:

endpoint_id_list, dist_name, group_name, alias, hostname, username, public_ip_list: List of strings.
endpoint_status: String. Permitted values are: connected, disconnected, lost, or uninstalled
ip_list: List of strings.
platform: String. Permitted values are: windows, linux, macos, android.
isolate: String. Permitted values are: isolated or unisolated.
scan_status: String. Permitted values are: none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error.
first_seen and last_seen: Integer. Timestamp epoch milliseconds.

]

search_frominteger

Represents the start offset within the query result set from which you want endpoints returned.

Endpoints are returned as a zero-based list. Any endpoint indexed less than this value is not returned in the final result set and defaults to zero.

search_tointeger

Represents the end offset within the result set after which you do not want endpoints returned.

Endpoint in the endpoint list that is indexed higher than this value is not returned in the final results set. Defaults to 100, which returns all endpoints to the end of the list.

sortobject

Identifies the sort order for the result set.

fieldstring (Enum)

Identifies the field you want to sort by. Case-sensitive.

Default:"first_seen"

Allowed values:"endpoint_id""first_seen""last_seen""scan_status"

keywordstring (Enum)

Whether you want to sort in ascending (ASC) or descending (DESC) order. Case-sensitive.

Default:"DESC"

Allowed values:"ASC""DESC"

REQUEST

{
  "request_data": {
    "search_from": 0,
    "search_to": 1,
    "sort": {
      "field": "endpoint_id",
      "keyword": "asc"
    },
    "filters": [
      {
        "field": "endpoint_status",
        "operator": "eq",
        "value": "disconnected"
      },
      {
        "field": "dist_name",
        "operator": "in",
        "value": [
          "papi-test"
        ]
      },
      {
        "field": "scan_status",
        "operator": "in",
        "value": [
          "none",
          "pending",
          "in_progress",
          "pending_cancellation",
          "aborted",
          "success",
          "canceled",
          "error"
        ]
      }
    ]
  }
}

{
  "request_data": {}
}

Responses

Body

application/json

replyobject

JSON object containing the query result.

total_countinteger

Number of total results of this filter without paging.

result_countinteger

Number of endpoints actually returned as result.

endpointsarray

A list of endpoints.

[

endpoint_idstring

endpoint_namestring

endpointTagsstring

endpoint_typestring

endpoint_statusstring

os_typestring

os_versionstring

iparray[string]

ipv6array

[

]

public_ipstring

usersarray[string]

domainstring

aliasstring

first_seeninteger

last_seeninteger

content_versionstring

installation_packagestring

active_directoryobject

install_dateinteger

endpoint_versionstring

is_isolatedstring

isolated_dateobject

group_namearray

[

]

operational_statusstring

operational_status_descriptionstring

scan_statusstring

content_release_timestampinteger

last_content_update_timeinteger

content_statusstring

operating_systemstring

mac_addressarray[string]

assigned_prevention_policystring

assigned_extensions_policystring

]

RESPONSE

{
  "reply": {
    "total_count": 0,
    "result_count": 0,
    "endpoints": [
      {
        "endpoint_id": "string",
        "endpoint_name": "string",
        "endpointTags": "string",
        "endpoint_type": "string",
        "endpoint_status": "string",
        "os_type": "string",
        "os_version": "string",
        "ip": [
          "string"
        ],
        "ipv6": [
          {}
        ],
        "public_ip": "string",
        "users": [
          "string"
        ],
        "domain": "string",
        "alias": "string",
        "first_seen": 0,
        "last_seen": 0,
        "content_version": "string",
        "installation_package": "string",
        "active_directory": null,
        "install_date": 0,
        "endpoint_version": "string",
        "is_isolated": "string",
        "isolated_date": null,
        "group_name": [
          {}
        ],
        "operational_status": "string",
        "operational_status_description": "string",
        "scan_status": "string",
        "content_release_timestamp": 0,
        "last_content_update_time": 0,
        "content_status": "string",
        "operating_system": "string",
        "mac_address": [
          "string"
        ],
        "assigned_prevention_policy": "string",
        "assigned_extensions_policy": "string"
      }
    ]
  }
}

{
  "reply": {
    "total_count": 1,
    "result_count": 1,
    "endpoints": [
      {
        "endpoint_id": "<endpoint ID>",
        "endpoint_name": "<endpoint name>",
        "endpointTags": "<tag name>",
        "endpoint_type": "<endpoint type>",
        "endpoint_status": "CONNECTED",
        "os_type": "AGENT_OS_WINDOWS",
        "os_version": "8.0.xxx",
        "ip": [
          "<IP address>"
        ],
        "ipv6": [],
        "public_ip": "<IP address>",
        "users": [
          "XDR"
        ],
        "domain": "WORKGROUP",
        "alias": "",
        "first_seen": 1606218761377,
        "last_seen": 1606218769163,
        "content_version": "",
        "installation_package": "XDR",
        "active_directory": null,
        "install_date": 1606218762089,
        "endpoint_version": "<version>",
        "is_isolated": "AGENT_UNISOLATED",
        "isolated_date": null,
        "group_name": [],
        "operational_status": "PARTIALLY_PROTECTED",
        "operational_status_description": "[{\"name\": \"generalStatus\", \"error_code\": 10004}]",
        "scan_status": "SCAN_STATUS_NONE",
        "content_release_timestamp": 1636285746000,
        "last_content_update_time": 1636381954285,
        "content_status": "up_to_date",
        "operating_system": "Debian 10.11",
        "mac_address": [
          "42:00:00:00:00:00"
        ],
        "assigned_prevention_policy": "Linux Default",
        "assigned_extensions_policy": ""
      }
    ]
  }
}

Bad Request. Got an invalid JSON.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. An issue occurred during authentication. This can indicate an incorrect key, id, or other invalid authentication parameters.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Unauthorized access. User does not have the required license type to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Forbidden access. The provided API Key does not have the required RBAC permissions to run this API.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}

Internal server error. A unified status for API communication type errors.

Body

application/json

The query result upon error.

err_codestring

HTTP response code.

err_msgstring

Error message.

Example:"{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}"

err_extrastring

Additional information describing the error.

RESPONSE
{
  "err_code": "example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "example"
}