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

Body parameters

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 array

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.

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.

Allowed values:"ASC""DESC"

REQUEST BODY


    {"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"]}]}}

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

Responses

Body

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"
      }
    ]
  }
}

Bad Request. Got an invalid JSON.

Body

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": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

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

Body

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": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

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

Body

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": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

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

Body

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": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}

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

Body

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": "err_code_example",
  "err_msg": "{\"line\": 1, \"column\": 19, \"message\": \"no viable alternative at input '|alter2'\"}",
  "err_extra": "err_extra_example"
}