1. Docs
  2. API Reference
  3. Create an identity audit-log export job (CSV / NDJSON)

Create an identity audit-log export job (CSV / NDJSON)

POST/portal/v1/accounts/{accountSlug}/audit-log/identities/export

Enqueues an asynchronous export of the filtered window and returns the pending job immediately — rendering happens off-request in a background worker that writes the file to object storage. Accepts the same filter DSL as the query endpoint in the request body; cursor and limit do not apply. format: csv (default) folds metadata into a single JSON column for spreadsheet review; format: ndjson emits one JSON object per line for SIEM ingestion (Splunk, Datadog, Elastic). Customer-visible rows only, scoped to this surface; the same 30-day default window applies when from/to are omitted. The dashboard is notified in realtime when the job completes. Writes an audit.export.requested row (who asked) and, on completion, an audit.export.executed row recording format, filter, and row count — never the row contents.

Authentication

Bearer TokenAuthorization

JWT access token. Never send alongside X-API-Key: a request carrying both is refused.

Requires capability audit.viewSecurity

View the account-wide audit log. Granted through an administrator role in the Admin Workspace; a valid token without it is refused with 403.

Request body

application/json

fromstring · date-time Optional

Lower bound (inclusive). Defaults to `to - 30 days` when omitted.

tostring · date-time Optional

Upper bound (inclusive). Defaults to `now()` when omitted.

actionstring[] Optional

Filter by one or more action keys. Repeat the query param (`?action=a&action=b`) or pass a comma-separated string.

categoryenum Optional

one of "auth" · "identity" · "admin_user" · "tenancy" · "hierarchy" · "organization" · "rbac" · "authorization" · "api_keys" · "oauth" · "webhooks" · "invites" · "mfa" · "audit" · "billing" · "sso" · "unknown"

severityenum Optional

one of "info" · "notice" · "warning" · "critical"

outcomeenum Optional

one of "success" · "failure" · "denied"

actor_idstring · uuid Optional
actor_typestring Optional

Free-form actor-type filter (e.g. `user`, `identity`).

resource_typestring Optional

Free-form resource-type filter (e.g. `identity`, `role`, `node`).

resource_idstring · uuid Optional
correlation_idstring · uuid Optional
application_idstring · uuid Optional

Narrow to rows for one Application within the Account. Omit to include all Applications.

environment_idstring · uuid Optional

Narrow to rows for one Environment. Implies the Environment's parent Application. Omit to include all Environments.

qstring Optional

Full-text query against actor_label, resource_label (trigram), and metadata (GIN).

formatenum Optional

Export wire format. `csv` for spreadsheet review (metadata folded into one JSON column); `ndjson` for SIEM ingestion (one JSON object per line, metadata nested). Defaults to `csv`.

one of "csv" · "ndjson"

Responses

application/json

  • dataExportJobDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Errors

When the request can't be completed, the response body includes a stable error code you can branch on.

403account.capability_requiredForbidden
When it happens

The signed-in user's administrator roles do not grant the capability this endpoint requires.

Remediation

Ask an account administrator to grant a role carrying the capability named in the Authentication section, then retry.

Returned object

ExportJobDtoView all properties on this resource
Request
curl -X POST "https://auth.canopy-io.com/portal/v1/accounts/{accountSlug}/audit-log/identities/export" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2026-04-20T12:00:00.000Z",
    "to": "2026-04-20T12:00:00.000Z",
    "action": [
      "string"
    ],
    "category": "auth",
    "severity": "info",
    "outcome": "success",
    "actor_id": "00000000-0000-0000-0000-000000000000",
    "actor_type": "string",
    "resource_type": "string",
    "resource_id": "00000000-0000-0000-0000-000000000000",
    "correlation_id": "00000000-0000-0000-0000-000000000000",
    "application_id": "00000000-0000-0000-0000-000000000000",
    "environment_id": "00000000-0000-0000-0000-000000000000",
    "q": "string",
    "format": "csv"
  }'
Response
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "pending",
    "surface": "admin",
    "format": "csv",
    "application_id": "00000000-0000-0000-0000-000000000000",
    "environment_id": "00000000-0000-0000-0000-000000000000",
    "row_count": 0,
    "error": "string",
    "created_at": "2026-04-20T12:00:00.000Z",
    "completed_at": "2026-04-20T12:00:00.000Z",
    "expires_at": "2026-04-20T12:00:00.000Z",
    "download_url": "string"
  }
}
 Related endpoints
GETLive-tail identity audit-log events (SSE)
GETQuery identity audit-log events
GETList recent audit-log export jobs
GETGet an audit-log export job
DELETEDelete an audit-log export job
GETGet an identity audit-log row with related events
 Was this page helpful?

Tell us how we can improve this guide.

Canopy