Query shell audit events

GET

/api/audit

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

• HTTPBearer

Parameters

Query Parameters

organization_id

required

string format: uuid

user_id

Any of:

string

string format: uuid

null

null

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

device_id

Any of:

string

string

null

null

Filter via payload->>‘device_id’.

session_id

Any of:

string

string

null

null

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

fleet_id

Any of:

string

string format: uuid

null

null

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

tier

Any of:

string

string

null

null

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

event_type

Any of:

string

string

null

null

Exact match on the event_type column.

outcome

Any of:

string

string

null

null

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

since

Any of:

string

string format: date-time

null

null

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

until

Any of:

string

string format: date-time

null

null

Filter created_at < until (ISO-8601 UTC).

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

string

null

null

Opaque keyset cursor from a previous response’s next_cursor.

Responses

200

Successful Response

Paginated response from GET /audit.

object

has_more

required

boolean

items

required

Array<object>

Single audit event row returned by GET /audit.

object

actor_id

required

Any of:

string

string format: uuid

null

null

created_at

required

string format: date-time

event_hash

required

string

event_type

required

string

id

required

string format: uuid

payload

required

prev_hash

required

string

reason

required

Any of:

string

string

null

null

target_user_id

required

Any of:

string

string format: uuid

null

null

next_cursor

required

Any of:

string

string

null

null

422

Validation Error

object

detail

Array<object>

object

loc

required

Array

msg

required

string

type

required

string