export_audit_events

Export an org's audit log

act entity tenant-private since 2026-10-01

Exports the audit log of one org, with the filters list_audit_events takes (event, actor, impersonation, admin alerts, a UTC date range; staff may add the acts on no org), to a CSV and a JSON file. Answers 202 with the export's id while it is built; list_audit_exports says when it is ready and answers a download link for each file, signed and good for 24 hours. The files hold exactly what list_audit_events shows the caller: staff read each row whole; an account owner or an org admin gets before and after as the keys the act changed only, redacted. More than 50,000 events fail the export rather than cut it short. One export of an org runs at a time.

Contract

shape: entity
authority: act
evidence: none
subscription: false
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: keyed
emits: audit.export_requested
MCP tool: export_audit_events
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/export_audit_events

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org whose audit log is exported.
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 export acts that touched no org (accounts, portfolios, platform FX overrides).

Response

export_id · string · The export: ae and eighteen characters, derived from the Idempotency-Key.
org_id · string · The org.
status · string · running when first answered (202); a replay answers where it is now.
filters · object · The filters as asked, by their input names; the export holds exactly the rows they list.

Full JSON Schema

{
  "type": "object",
  "properties": {
    "export_id": {
      "type": "string",
      "description": "The export: ae and eighteen characters, derived from the Idempotency-Key.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "running",
        "ready",
        "failed"
      ],
      "description": "running when first answered (202); a replay answers where it is now.",
      "x-data-class": "operational"
    },
    "filters": {
      "type": "object",
      "description": "The filters as asked, by their input names; the export holds exactly the rows they list.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "export_id",
    "org_id",
    "status",
    "filters"
  ],
  "additionalProperties": false
}

Refusals

audit_export_unavailable · 422 · this deployment has no object store or no link secret for audit exports yet
audit_export_running · 409 · an export of this org's audit log is still running; wait for it to land
audit_export_busy · 429 · as many exports as front-door builds at once are building or waiting; try again in a minute
idempotency_key_reused · 409 · this Idempotency-Key already made an export of another org, or by someone else
retry_key_mismatch · 409 · the Idempotency-Key was already used with different inputs
retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
retry_key_lost · 409 · another request took over this Idempotency-Key first; no export was made

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

PushF

OneBoxN

OutboundN

MCP: approval required
Voice: degraded: visualization
OneBox: no document originates an audit export
Outbound: crosses to no counterparty

Events

audit.export_requested audit_only

list_audit_events, subscribe_audit

get a test key

curl https://api.containertradehq.com/v1/cap/export_audit_events \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"org_id":"<org_id>"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.exportAuditEvents({
  "org_id": "<org_id>"
});
// Idempotency-Key is generated once per call and reused across its retries.

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.export_audit_events({
    "org_id": "<org_id>",
})
# Idempotency-Key is generated once per call and reused across its retries.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "export_audit_events",
    "arguments": {
      "org_id": "<org_id>"
    }
  }
}

MCP

export_audit_events · readOnlyHint false · approval required

“Call export_audit_events”