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 XSIAM Premium or Cortex XSIAM Enterprise. In Cortex NG SIEM, requires endpoints or the Cortex Cloud Runtime Security add-on.

Request headers

Authorization String required

{api_key}

Example: authorization_example

x-xdr-auth-id String required

{api_key_id}

Example: xXdrAuthId_example

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'
      
      '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",
    '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["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("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("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",
  "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 => [
    "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, "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("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)required

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).
cloud_provider: Cloud provider (for example, AWS, GCP, Azure).
cloud_region: Cloud region where the endpoint is deployed.
cloud_provider_account_id: Cloud provider account ID.
cloud_instance_id: Cloud instance ID of the endpoint.
cloud_id: Cloud ID of the endpoint.

Allowed values:"endpoint_id_list""endpoint_status""dist_name""first_seen""last_seen""ip_list""group_name""platform""alias""isolate""hostname""public_ip_list""cloud_provider""cloud_region""cloud_provider_account_id""cloud_instance_id""cloud_id"

operatorstring (Enum)required

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: Permitted values are: connected, disconnected, lost, or uninstalled
ip_list: List of strings. For example: "192.168.5.12".
platform: Permitted values are: windows, linux, macos, android.
isolate: Permitted values are: isolated or unisolated.
scan_status: Permitted values are: none, pending, in_progress, canceled, aborted, pending_cancellation, success, or error. gte / lte
first_seen and last_seen: Timestamp epoch milliseconds.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

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

valueobjectrequired

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.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

One of

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.
cloud_provider, cloud_region, cloud_provider_account_id, cloud_instance_id, cloud_id: List of strings.

Array

]

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)required

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

Default:"first_seen"

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

keywordstring (Enum)required

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": "group_name",
        "operator": "in",
        "value": [
          "Test-Group-01"
        ]
      },
      {
        "field": "endpoint_status",
        "operator": "in",
        "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": {}
}

{
  "request_data": {
    "filters": [
      {
        "field": "cloud_provider",
        "operator": "in",
        "value": [
          "aws"
        ]
      },
      {
        "field": "cloud_region",
        "operator": "in",
        "value": [
          "us-east-1",
          "us-west-2"
        ]
      }
    ]
  }
}

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

operational_status_detailsarray

[

titlestring

reasonstring

]

os_typestring

os_versionstring

iparray[string]

ipv6array

[

]

public_ipstring

usersarray[string]

domainstring

aliasstring

first_seeninteger

last_seeninteger

content_versionstring

installation_packagestring

active_directorystring

install_dateinteger

endpoint_versionstring

is_isolatedstring

isolated_datestring

group_namearray[string]

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

cloud_providerstring

Cloud provider of the endpoint (for example, AWS, GCP, Azure). Returns an empty string if the endpoint is not a cloud agent.

cloud_regionstring

Cloud region where the endpoint is deployed. Returns an empty string if the endpoint is not a cloud agent.

cloud_provider_account_idstring

Cloud provider account ID associated with the endpoint. Returns an empty string if the endpoint is not a cloud agent.

cloud_instance_idstring

Cloud instance ID of the endpoint. Returns an empty string if the endpoint is not a cloud agent.

cloud_idstring

Cloud ID of the endpoint. Returns an empty string if the endpoint is not a cloud agent.

]

RESPONSEExample 1
{
  "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",
        "operational_status_details": [
          {
            "title": "XDR Data Collection not running or not sent",
            "reason": "Linux kernel version is not supported"
          },
          {
            "title": "BTP not working",
            "reason": "Linux kernel version is not supported"
          },
          {
            "title": "Antimalware flow is asynchronous",
            "reason": "Linux kernel version is not supported"
          },
          {
            "title": "Local privilege escalation",
            "reason": "Linux kernel version is not supported"
          }
        ],
        "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",
        "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"
}