Collection Control Audit Log

GET /clients/{client_id}/collection-control/audit-log

Returns a paginated audit trail of all collection control changes for a client -- client mode changes, device state changes, user status changes, log shipping changes, and bulk actions. One audit entry is created per affected entity per change.

Path Parameters

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

Query Parameters

Parameter	Type	Default	Description
entity_type	string	-	Filter by entity type: client, device, user
entity_id	string (uuid)	-	Filter by specific entity (client_id, device_id, or user_id)
sort_order	string	desc	Sort direction by created_at: asc, desc
page_size	integer	50	Items per page. Max: 200
cursor	string	-	Pagination cursor from a previous response

Response

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

Example Request

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

Filter by entity type

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/collection-control/audit-log?entity_type=device" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Filter by specific device

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/collection-control/audit-log?entity_type=device&entity_id=f1e2d3c4-b5a6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-7890-cdef-1234567890ab",
      "entity_type": "client",
      "entity_id": "aa7cf840-9ca9-46a3-9778-9015d6580d50",
      "actor_id": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
      "action": "collection_mode_changed",
      "previous_value": { "collection_mode": "saas_usage" },
      "new_value": { "collection_mode": "disabled" },
      "created_at": "2026-03-10T14:30:00.000Z"
    },
    {
      "id": "d2e3f4a5-b6c7-8901-defg-2345678901bc",
      "entity_type": "device",
      "entity_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
      "actor_id": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
      "action": "device_state_changed",
      "previous_value": { "collection_state": "enabled" },
      "new_value": { "collection_state": "disabled" },
      "created_at": "2026-03-10T14:25:00.000Z"
    },
    {
      "id": "e3f4a5b6-c7d8-9012-efgh-3456789012cd",
      "entity_type": "user",
      "entity_id": "a1d97031-04e2-4907-a249-093f7436207b",
      "actor_id": "u1v2w3x4-y5z6-7890-abcd-ef1234567890",
      "action": "user_status_changed",
      "previous_value": { "status": "active" },
      "new_value": { "status": "archived" },
      "created_at": "2026-03-10T14:20:00.000Z"
    },
    {
      "id": "f4a5b6c7-d8e9-0123-fghi-4567890123de",
      "entity_type": "device",
      "entity_id": "a9b8c7d6-e5f4-3210-fedc-ba9876543210",
      "actor_id": null,
      "action": "log_shipping_changed",
      "previous_value": { "log_shipping_enabled": false },
      "new_value": { "log_shipping_enabled": true },
      "created_at": "2026-03-10T14:15:00.000Z"
    }
  ],
  "total_count": 47,
  "next_cursor": "WyJjY2FsIl0"
}

CollectionControlAuditEntry

Field	Type	Nullable	Description
id	string (uuid)	No	Unique identifier for the audit entry
entity_type	string	No	Type of entity: client, device, user
entity_id	string (uuid)	No	ID of the affected entity (client_id, device_id, or user_id)
actor_id	string (uuid)	Yes	Admin user ID who performed the action. null for system-initiated actions.
action	string	No	Action performed (see Action Values)
previous_value	object	No	State before the change
new_value	object	No	State after the change
created_at	string (ISO 8601)	No	When the change was recorded

Note on actor_id

The v2 design guidelines omit created_by as an internal audit field. actor_id on the audit log is intentionally exposed because the audit log's entire purpose is to surface who made a change -- the actor is a first-class domain field here, not incidental metadata.

Action Values

Action	Entity Type	Description
collection_mode_changed	client	Client collection mode was updated
device_state_changed	device	Device collection state was updated
log_shipping_changed	device	Device log shipping setting was updated
user_status_changed	user	User status was updated

Bulk operations create one audit entry per affected entity (not one entry per bulk request).

DB source: collection_control_audit_log table

Pagination

This endpoint uses cursor-based pagination, sorted by created_at in the direction specified by sort_order.

Error Responses

Status	Description
400	Invalid query parameters
401	Authentication required
403	Insufficient permissions for this client
404	Client not found
500	Server error

Related Endpoints

• Update Client - Change client collection mode
• Update Device Controls - Change device collection state
• Update User - Change user status