Skip to content
OTA-Pulse Docs

Query shell audit events

GET
/api/audit
 
curl --request GET \
  --url 'https://example.com/api/audit?organization_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&limit=100' \
  --header 'Authorization: Bearer <token>'

Return a paginated list of shell audit events for the organisation.

Query parameters allow filtering by user, device, tier, event type, outcome, and date range. Pagination is keyset-based (pass cursor from the previous response’s next_cursor).

Role required: audit.view (ShellRole.AUDIT_VIEW).

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “ Query Parameters ”
organization_id
required
Organization Id
string format: uuid
user_id
Any of:
string format: uuid

Filter events where actor_id == user_id OR target_user_id == user_id.

device_id
Any of:
string

Filter via payload->>‘device_id’.

session_id
Any of:
string

Filter via payload->>‘session_id’ (exact match on the session UUID string).

fleet_id
Any of:
string format: uuid

Alias for organization_id. If both fleet_id and organization_id are given they must match (else 400).

tier
Any of:
string

Filter via payload->>‘tier’ (standard|elevated|breakglass).

event_type
Any of:
string

Exact match on the event_type column.

outcome
Any of:
string

Normalised outcome filter. Checked against payload->>‘outcome’, payload->>‘exit_reason’, and payload->>‘decision’ (OR logic).

since
Any of:
string format: date-time

Filter created_at >= since (ISO-8601 UTC).

until
Any of:
string format: date-time

Filter created_at < until (ISO-8601 UTC).

limit
Limit

Maximum rows per page (default 100, max 500).

integer
default: 100 >= 1 <= 500

Maximum rows per page (default 100, max 500).

cursor
Any of:
string

Opaque keyset cursor from a previous response’s next_cursor.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Successful Response

Media type application/json
AuditListResponse

Paginated response from GET /audit.

object
has_more
required
Has More
boolean
items
required
Items
Array<object>
AuditEventItem

Single audit event row returned by GET /audit.

object
actor_id
required
Any of:
string format: uuid
actor_ref
Any of:
string
created_at
required
Created At
string format: date-time
event_hash
required
Event Hash
string
event_type
required
Event Type
string
id
required
Id
string format: uuid
payload
required
Payload
prev_hash
required
Prev Hash
string
reason
required
Any of:
string
target_user_id
required
Any of:
string format: uuid
next_cursor
required
Any of:
string
Example generated 
{
  "has_more": true,
  "items": [
    {
      "actor_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "actor_ref": "example",
      "created_at": "2026-04-15T12:00:00Z",
      "event_hash": "example",
      "event_type": "example",
      "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "payload": "example",
      "prev_hash": "example",
      "reason": "example",
      "target_user_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
    }
  ],
  "next_cursor": "example"
}

422

Section titled “ 422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Example generated 
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}