Device Users

GET /clients/{client_id}/devices/{device_id}/users

Returns a paginated list of users observed on a specific device. Each item is a DeviceUserRef -- a UserRef extended with device-specific enrollment and last-seen timestamps from the user_devices junction table.

This endpoint is device-primary: the device is the subject and users are the associated resources. For the user-primary direction (devices by user), use the List Devices endpoint with the user_id filter.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
q	string	-	Search filter against username or user_key (case-insensitive, partial match)
sort_by	string	last_seen_at	Sort field: username, enrolled_at, last_seen_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	DeviceUserRef[]	Array of user objects for this device
total_count	integer	Total number of users associated with this device
next_cursor	string | null	Cursor to pass as cursor for the next page. null when on the last page.

Example Requests

List users on a device

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

Search for a user by username

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/users?q=mike" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Sort by enrollment date

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/users?sort_by=enrolled_at&sort_order=asc" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "a1d97031-04e2-4907-a249-093f7436207b",
      "username": "mikechang",
      "user_key": "mikechang",
      "last_activity": {
        "at": "2026-02-24T21:23:53.082Z",
        "desktop_at": "2026-02-22T08:00:00.000Z",
        "web_at": "2026-02-24T21:23:53.082Z"
      },
      "enrolled_at": "2025-11-01T08:00:00.000Z",
      "last_seen_at": "2026-02-24T21:23:53.082Z"
    },
    {
      "id": "b2e08142-15f3-5018-b350-104g8547318c",
      "username": "sarahk",
      "user_key": "sarahk",
      "last_activity": {
        "at": "2026-02-20T14:00:00.000Z",
        "desktop_at": "2026-02-20T14:00:00.000Z",
        "web_at": null
      },
      "enrolled_at": "2025-12-01T09:00:00.000Z",
      "last_seen_at": "2026-02-20T14:00:00.000Z"
    }
  ],
  "total_count": 2,
  "next_cursor": 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	Device or client not found
500	Server error

Example Error Response

{
  "error": {
    "code": "not_found",
    "message": "Device not found",
    "details": {
      "device_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
    }
  }
}

Related Endpoints

• Get Device - Full device profile
• List Devices - Filter devices by user with ?user_id=
• Get User - Full user profile