Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- true
- permission
- any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in the account of the org `org_id`); org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_audit_events
- REST
- POST https://api.containertradehq.com/v1/cap/list_audit_events
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose audit log is listed. |
| event | event_name | optional | tradehq-event-name; 3 to 64 characters Only this event, by name (org.settings_changed). |
| actor_user_id | user_id | optional | tradehq-user-id; 1 to 20 characters Only acts by this user. |
| impersonated | boolean | optional | true: only acts staff took inside the org on platform authority; false: only the others. |
| alerts_only | boolean | optional | Only the admin activity alerts: a new admin, an SSO change, an API key created. |
| since | date | optional | date, YYYY-MM-DD Only acts on or after this UTC day. |
| until | date | optional | date, YYYY-MM-DD Only acts on or before this UTC day. |
| include_platform | boolean | optional | Staff only: also list acts that touched no org (accounts, portfolios, platform FX overrides). |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | uuid | optional | UUID The previous page's next_after. |
Paginated: next next_after · page_max 200 · walk_max 10000 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"audit_id": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
"format": "uuid",
"description": "The row's id: the outbox row it was recorded from.",
"x-data-class": "operational"
},
"occurred_at": {
"type": "string",
"format": "date-time",
"description": "When the act committed.",
"x-data-class": "operational"
},
"event": {
"type": "string",
"description": "The event, noun.past_verb.",
"x-data-class": "operational"
},
"capability": {
"type": "string",
"description": "The capability that acted.",
"x-data-class": "operational"
},
"target_org_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-org-id",
"description": "The org the act was about. For anyone but staff, always the listed org: an act on several orgs is listed to each as its own. For staff, null when it touched no org or several.",
"x-data-class": "operational"
},
"actor_user_id": {
"type": [
"string",
"null"
],
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who acted: null when nobody was signed in to the act, which is only an act anybody may call (provision_sandbox).",
"x-data-class": "operational"
},
"actor_staff": {
"type": "boolean",
"description": "Whether they were staff.",
"x-data-class": "operational"
},
"acting_scope": {
"type": "object",
"properties": {
"target": {
"type": [
"string",
"null"
]
},
"id": {
"type": [
"string",
"null"
]
},
"via": {
"type": [
"string",
"null"
]
},
"org_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"accounts": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"target",
"id",
"via",
"org_ids",
"accounts"
],
"additionalProperties": false,
"description": "{target, id, via, org_ids, accounts}: the target kind, its id, the permission that admitted the call and what it reached. org_ids and accounts are cut to this org for anyone but staff.",
"x-data-class": "operational"
},
"impersonated": {
"type": "boolean",
"description": "Staff acting inside the org on platform authority rather than on a role the org gave them.",
"x-data-class": "operational"
},
"before": {
"type": [
"object",
"null"
],
"description": "What the act replaced; null for a creation. For anyone but staff, only the keys the act changed, redacted.",
"x-data-class": "operational"
},
"after": {
"type": [
"object",
"null"
],
"description": "What the act left. For anyone but staff, only the keys the act changed, redacted.",
"x-data-class": "operational"
},
"alert": {
"type": [
"string",
"null"
],
"enum": [
"new_admin",
"sso_changed",
"key_created",
null
],
"description": "The admin activity alert this act is, if any.",
"x-data-class": "operational"
}
},
"required": [
"audit_id",
"occurred_at",
"event",
"capability",
"target_org_id",
"actor_user_id",
"actor_staff",
"acting_scope",
"impersonated",
"before",
"after",
"alert"
],
"additionalProperties": false
},
"maxItems": 200
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates an audit listing
- Outbound: crosses to no counterparty
Events
None emitted.
Related
export_audit_events, list_accounts, list_agent_reads, list_audit_exports, list_orgs, list_unit_access, list_users, subscribe_audit