Get Distributions

post /public_api/v1/distributions/get_distributions

Retrieves a paginated list of existing agent installations and metadata based on optional filters and sorting criteria.

This endpoint allows you to:

Retrieve existing agent installations or filter by specific criteria
Paginate through large result sets
Sort results by any field in ascending or descending order
Get total count and filtered count of agent installations

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

Request headers

Authorization String required

{api_key}

Example:

UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP

x-xdr-auth-id String required

{api_key_id}

Example: 241

CLIENT REQUEST

          curl -X 'POST'

        -H
        'Accept: application/json'
      
        -H
        'Content-Type: application/json'
      
          -H
          'Authorization: UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP'
          -H
          'x-xdr-auth-id: 241'
      
      'https://api-yourfqdn/public_api/v1/distributions/get_distributions'
    
      -d
      ''

import http.client

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

payload = "{\"request_data\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}"

headers = {
    'Authorization': "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP",
    'x-xdr-auth-id': "241",
    'content-type': "application/json"
    }

conn.request("POST", "/public_api/v1/distributions/get_distributions", 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/distributions/get_distributions")

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"] = 'UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP'
request["x-xdr-auth-id"] = '241'
request["content-type"] = 'application/json'
request.body = "{\"request_data\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}"

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

const data = JSON.stringify({
  "request_data": {
    "search_from": 0,
    "search_to": 10,
    "sort": {
      "field": "string",
      "keyword": "desc"
    },
    "filters": [
      {
        "field": "platform",
        "operator": "eq",
        "value": "lin"
      }
    ]
  }
});

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/distributions/get_distributions");
xhr.setRequestHeader("Authorization", "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP");
xhr.setRequestHeader("x-xdr-auth-id", "241");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.post("https://api-yourfqdn/public_api/v1/distributions/get_distributions")
  .header("Authorization", "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP")
  .header("x-xdr-auth-id", "241")
  .header("content-type", "application/json")
  .body("{\"request_data\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}")
  .asString();

import Foundation

let headers = [
  "Authorization": "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP",
  "x-xdr-auth-id": "241",
  "content-type": "application/json"
]
let parameters = ["request_data": [
    "search_from": 0,
    "search_to": 10,
    "sort": [
      "field": "string",
      "keyword": "desc"
    ],
    "filters": [
      [
        "field": "platform",
        "operator": "eq",
        "value": "lin"
      ]
    ]
  ]] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api-yourfqdn/public_api/v1/distributions/get_distributions")! 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/distributions/get_distributions",
  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\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}",
  CURLOPT_HTTPHEADER => [
    "Authorization: UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP",
    "content-type: application/json",
    "x-xdr-auth-id: 241"
  ],
]);

$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/distributions/get_distributions");

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

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"request_data\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-yourfqdn/public_api/v1/distributions/get_distributions");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "UCoWpG4rkNzgCp2dsh8m02iVpZsskwKHz7N1tErPcUV3Wmf59Gc9kytmgOv0pDWoem3PBlORyRIPiir4OcYdWUOWAM3JyTgoCxQf4nQoTlKmFRKz9Bj5vIjluw66p9WP");
request.AddHeader("x-xdr-auth-id", "241");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"request_data\":{\"search_from\":0,\"search_to\":10,\"sort\":{\"field\":\"string\",\"keyword\":\"desc\"},\"filters\":[{\"field\":\"platform\",\"operator\":\"eq\",\"value\":\"lin\"}]}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

required

application/json

request_dataobject

Request body containing pagination, sorting, and filtering parameters.

search_frominteger

Starting index for pagination (zero-based). Defines the offset from which to begin returning results.

search_tointeger

Ending index for pagination (exclusive). Defines the maximum number of results to return (search_to - search_from). The maximum allowed value is <=100. Requests exceeding this limit will return a 400 error.

Example:10

Default:100

sortobjectrequired

fieldstring

The field name to filter on. Available fields include:

distribution_id
name
description
package_type
platform
agent_version
status

keywordobject (Enum)

Determines the sort order.

Example:"desc"

Allowed values:"asc""desc"

filtersarray

Filter condition to apply to the query

[

fieldstring

The field name to filter on. Available fields include:

distribution_id
name
description
package_type
platform
agent_version
status

Example:"platform"

operatorobject (Enum)

Comparison operator to use for filtering. Note: The package_type, platform, and status fields are enum types and therefore do not support the contains or not_contains filter operators.

Example:"eq"

Allowed values:"eq""neq""contains""not_contains"

valueobject

The value to compare against. Type should match the field type. Can be a string or number depending on the operator. Examples:

If the field is status, the value can be completed, in_progress, or failed
If the field is platform, the value can be a string such as windows, macos, ios, serverless, or linux
If the field is package_type, the value can be standalone, kubernetes, upgrade, or helm

One of

string

The value to compare against. Type should match the field type. Can be a string or number depending on the operator. Examples:

If the field is status, the value can be completed, in_progress, or failed
If the field is platform, the value can be a string such as windows, macos, ios, serverless, or linux
If the field is package_type, the value can be standalone, kubernetes, upgrade, or helm

Example:"lin"

integer

The value to compare against. Type should match the field type. Can be a string or number depending on the operator. Examples:

If the field is status, the value can be completed, in_progress, or failed
If the field is platform, the value can be a string such as windows, macos, ios, serverless, or linux
If the field is package_type, the value can be standalone, kubernetes, upgrade, or helm

]

REQUEST

{
  "request_data": {
    "search_from": 0,
    "search_to": 5,
    "sort": {
      "field": "distribution_id",
      "keyword": "asc"
    },
    "filters": [
      {
        "field": "distribution_id",
        "operator": "eq",
        "value": "068bcaad02974ac5b223bfa786e7573c"
      },
      {
        "field": "name",
        "operator": "contains",
        "value": "macos-369121"
      },
      {
        "field": "description",
        "operator": "contains",
        "value": "Production-ready macos agent installer with enhanced monitoring capabilities"
      },
      {
        "field": "package_type",
        "operator": "eq",
        "value": "standalone"
      },
      {
        "field": "platform",
        "operator": "eq",
        "value": "macos"
      },
      {
        "field": "agent_version",
        "operator": "contains",
        "value": "9.1."
      },
      {
        "field": "status",
        "operator": "eq",
        "value": "completed"
      }
    ]
  }
}

Responses

Successful response containing the list of distributions matching the criteria

Body

application/json

Response object containing the list of distributions and metadata

replyobject

Container object for the response data

dataarray

Array of distribution objects matching the filter criteria

[

distribution_idstring

Unique identifier for the distribution

Example:"068bcaad02974ac5b223bfa786e7573c"

namestring

Human-readable name of the distribution

Example:"macos-369121"

descriptionstring

Detailed description of the distribution, its features, or release notes

Example:"Production-ready macos agent installer with enhanced monitoring capabilities"

package_typestring

Type of installation package

Example:"standalone"

platformstring

Target operating system or platform

Example:"macos"

agent_versionstring

Version number of the agent in semantic versioning format

Example:"9.1.0.9877"

statusstring

Current lifecycle status of the distribution.

Example:"completed"

tagsarray[string]

Array of tags for categorization and filtering

Example:["production","stable"]

eol_timeintegerint64

Unix timestamp in milliseconds (UTC) indicating the date and time when the resource reaches End-of-Life (EOL).

Example:1735689600

created_bystring

Name of the user or API key ID that created the distribution.

Example:"John Doe"

creation_timeinteger

Unix timestamp (milliseconds) when the distribution was created.

Example:1704067200

modification_timeinteger

Unix timestamp (milliseconds) when the distribution was modified.

Example:1704153600

supported_packagesarray[string]

List of package formats supported by this distribution

Example:["pkg"]

]

filter_countinteger

Number of distributions returned in the current response after applying filters.

Example:1

total_countinteger

Total number of distributions available in the system without filters.

Example:10

RESPONSE

{
  "reply": {
    "data": [
      {
        "distribution_id": "068bcaad02974ac5b223bfa786e7573c",
        "name": "macos-369121",
        "description": "Production-ready macos agent installer with enhanced monitoring capabilities",
        "package_type": "standalone",
        "platform": "macos",
        "agent_version": "9.1.0.9877",
        "status": "completed",
        "tags": [
          "production",
          "stable"
        ],
        "eol_time": 1735689600,
        "created_by": "John Doe",
        "creation_time": 1704067200,
        "modification_time": 1704153600,
        "supported_packages": [
          "pkg"
        ]
      }
    ],
    "filter_count": 1,
    "total_count": 10
  }
}

Bad Request - Invalid request parameters or malformed JSON

Body

application/json

replyobject

err_codeinteger

Numeric error code returned by the API.

err_msgstring

Human-readable summary of the error.

err_extrastring

Detailed description of the error, including the cause and how to resolve it when applicable.

RESPONSE

{
  "reply": {
    "err_code": 400,
    "err_msg": "Got an invalid input while processing XDR public API",
    "err_extra": "Unsupported operator 'contains' for field platform"
  }
}

{
  "reply": {
    "err_code": 400,
    "err_msg": "Got an invalid input while processing XDR public API.",
    "err_extra": "Search size must fulfill the requirement: 0 < search_size <= 100"
  }
}

Internal Server Error - An unexpected error occurred on the server

Body

application/json

replyobject

err_codeinteger

Numeric error code returned by the API.

err_msgstring

Human-readable summary of the error.

err_extrastring

Detailed description of the error, including the cause and how to resolve it when applicable.

RESPONSE

{
  "reply": {
    "err_code": 500,
    "err_msg": "An unexpected error occurred by XDR public API",
    "err_extra": "Invalid value 'serverless_functions' for field platform"
  }
}

{
  "reply": {
    "err_code": 500,
    "err_msg": "Got an invalid input while processing XDR public API",
    "err_extra": "Invalid parameter names: creation_time"
  }
}