List Devices

GET /clients/{client_id}/devices

Returns a paginated list of devices for a client organization. Use this endpoint for inventory tables, search, and filtering devices by a specific user.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization

Query Parameters

Parameter	Type	Default	Description
q	string	-	Search filter against name (case-insensitive, partial match)
user_id	string (uuid)	-	Filter to devices associated with a specific user
status	string	-	Filter by device status: active, inactive, pending
os_name	string	-	Filter by OS name (e.g. Windows, macOS, Linux)
sort_by	string	last_seen_at	Sort field: name, status, os_name, last_seen_at, installed_at, created_at
sort_order	string	desc	Sort direction: asc, desc
page_size	integer	50	Items per page. Max: 500
cursor	string	-	Pagination cursor from a previous response

Response

Field	Type	Description
data	Device[]	Array of device objects
total_count	integer	Total number of devices matching the current filters
next_cursor	string | null	Cursor to pass as cursor for the next page. null when on the last page.

Example Requests

List all devices

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Devices for a specific user

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices?user_id=a1d97031-04e2-4907-a249-093f7436207b" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter active Windows devices

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices?status=active&os_name=Windows" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Search by name

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices?q=macbook" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "name": "DESKTOP-DEV-ALICE",
      "status": "active",
      "serial_number": "5CG1234567",
      "unique_key": "DESKTOP-DEV-ALICE-HWID-5CG1234567",
      "os_name": "Windows",
      "os_version": "10.0.19045",
      "last_seen_at": "2026-02-24T21:23:53.082Z",
      "installed_at": "2025-11-01T08:00:00.000Z",
      "agent_version": "1.2.3",
      "hardware": {
        "manufacturer": "Dell Inc.",
        "model": "XPS 15 9520",
        "cpu_model": "Intel(R) Core(TM) i7-12700H",
        "cpu_cores": 8,
        "ram": 17179869184
      },
      "extensions": {
        "chrome": {
          "version": "1.11.0",
          "installed": true,
          "auto_update": true,
          "last_activity_at": "2026-02-24T21:23:53.082Z"
        },
        "edge": {
          "version": "1.11.0",
          "installed": true,
          "auto_update": false,
          "last_activity_at": "2026-02-24T21:22:00.000Z"
        },
        "firefox": {
          "version": null,
          "installed": false,
          "auto_update": false,
          "last_activity_at": null
        }
      },
      "created_at": "2025-11-01T08:00:00.000Z",
      "updated_at": "2026-02-24T21:23:53.082Z"
    },
    {
      "id": "a9b8c7d6-e5f4-3210-fedc-ba9876543210",
      "name": "MacBook-Morgan",
      "status": "active",
      "serial_number": "C02G1234MD6T",
      "unique_key": "MACBOOK-MORGAN-HWID-C02G1234MD6T",
      "os_name": "macOS",
      "os_version": "14.2.1",
      "last_seen_at": "2026-02-24T20:00:00.000Z",
      "installed_at": "2025-10-15T10:30:00.000Z",
      "agent_version": "1.2.3",
      "hardware": {
        "manufacturer": "Apple Inc.",
        "model": "MacBook Pro",
        "cpu_model": "Apple M2 Pro",
        "cpu_cores": 10,
        "ram": 34359738368
      },
      "extensions": {
        "chrome": {
          "version": "1.11.0",
          "installed": true,
          "auto_update": true,
          "last_activity_at": "2026-02-24T20:00:00.000Z"
        },
        "edge": {
          "version": null,
          "installed": false,
          "auto_update": false,
          "last_activity_at": null
        },
        "firefox": {
          "version": null,
          "installed": false,
          "auto_update": false,
          "last_activity_at": null
        }
      },
      "created_at": "2025-10-15T10:30:00.000Z",
      "updated_at": "2026-02-24T20:00:00.000Z"
    }
  ],
  "total_count": 84,
  "next_cursor": "eyJsYXN0X2lkIjoiYTliOGM3ZDYifQ"
}

Empty Result

{
  "data": [],
  "total_count": 0,
  "next_cursor": null
}

Pagination

This endpoint uses cursor-based pagination.

1. Omit cursor on the first request
2. If next_cursor is not null, pass its value as cursor on the next request
3. Repeat until next_cursor is null

Error Responses

Status	Description
400	Invalid query parameters (e.g. unknown sort_by value)
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Get Device - Full profile for a specific device
• Device Users - Users observed on a specific device