List Endpoints

Route

/v2/endpoints/list

Description

List and filter Cyberhaven endpoints (sensors) with advanced filtering and pagination capabilities. Endpoints are devices with installed Cyberhaven sensors that monitor data movement activities.

Method

POST

Inputs

Parameter	Type	Required	Description
page_request	PageRequest	No	Pagination and sorting configuration
page_request.size	integer	No	Number of results per page (max 1000)
page_request.id	string	No	Page token for next page
page_request.sort_by	string	No	Sort field and direction (e.g., "hostname desc")
filter	EndpointFilter	No	Filtering criteria
filter.ids	array[string]	No	List of specific endpoint IDs
filter.hostnames	array[string]	No	List of hostnames to filter by
filter.statuses	array[string]	No	Endpoint statuses (active, inactive)
filter.groups	array[string]	No	Deployment group names
filter.oses	array[string]	No	Operating systems (windows, macos, linux)
filter.os_versions	array[string]	No	Operating system versions
filter.endpoint_versions	array[string]	No	Sensor software versions

Request Example

{
  "page_request": {
    "size": 100,
    "sort_by": "hostname asc"
  },
  "filter": {
    "statuses": ["active"],
    "oses": ["windows", "macos"],
    "groups": ["Production"]
  }
}

Output

Field	Type	Description
type	string	Always "endpoints"
size	integer	Number of endpoints returned
resources	array[Endpoint]	Array of endpoint objects
page_response	PageResponse	Pagination information
page_response.next_id	string	Token for next page
page_response.total	integer	Total number of matched endpoints
errors	array[Error]	Any errors encountered

Endpoint Object Structure

Field	Type	Description
id	string	Unique endpoint identifier
hostname	string	Device hostname
machine_serial_number	string	Device serial number
deployment_group	string	Deployment group name
os	string	Operating system (windows, macos, linux)
os_version	string	Operating system version
sensor_version	string	Sensor software version
last_active_username	string	Last active user on device
last_active	string	Last activity timestamp (ISO 8601)
status	string	Endpoint status (active, inactive)

Rate Limit

• 60 requests per minute per API key
• 5 concurrent requests per endpoint

Example Response

{
  "type": "endpoints",
  "size": 2,
  "resources": [
    {
      "id": "endpoint-123",
      "hostname": "LAPTOP-001",
      "machine_serial_number": "ABC123456",
      "deployment_group": "Production",
      "os": "windows",
      "os_version": "Windows 11",
      "sensor_version": "24.03.90.366",
      "last_active_username": "john.doe",
      "last_active": "2024-01-15T10:30:00Z",
      "status": "active"
    }
  ],
  "page_response": {
    "next_id": "eyJwYWdlX2lkIjoiMiJ9",
    "total": 150
  },
  "errors": []
}