1. Docs
  2. API Reference
  3. Query identity audit events

Query identity audit events

GET/api/v1/audit-events

Cursor-paginated query over the Application's audit events, restricted to the identity surface — admin operational events never surface through the public API even when the API key holds every scope. Results are pinned to the principal's bound Application and Environment, so an env-pinned key cannot read identity rows from other Apps or Environments in the same Account. Supports the same filter DSL as the portal identity surface (action, category, severity, outcome, actor, resource, correlation_id, and full-text q). Each successful query writes one audit.query.executed row with surface: "api"; a malformed cursor returns 400.

Authentication

Bearer TokenAuthorization Option A

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

API KeyX-API-Key Option B

API key for management-tier access. Never send alongside an Authorization header: a request carrying both is refused.

Query Parameters

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).

cursorstring Optional

Opaque base64url cursor returned by the previous response. Omit for the first page.

limitnumber Optional

Page size. Defaults to 50; max 200.

range 1–200

Responses

application/json

  • itemsAuditLogRowDto[]*
  • paginationobject*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

application/json

  • errorApiErrorBodyDto*

Pagination

This endpoint returns a paginated collection. Use the query parameters below to page through results.

pagenumber

Page number (1-indexed). Defaults to 1.

takenumber

Items per page (1–100). Defaults to 20.

Each response includes an items array alongside a pagination object with item_count, page_count, has_previous_page, and has_next_page fields.

Returned object

AuditLogRowDtoView all properties on this resource
Request
curl -X GET "https://auth.canopy-io.com/api/v1/audit-events?from=value&to=value&action=value&category=auth&severity=info&outcome=success&actor_id=value&actor_type=value&resource_type=value&resource_id=value&correlation_id=value&application_id=value&environment_id=value&q=value&cursor=value&limit=0" \
  -H "X-API-Key: $CANOPY_API_KEY"
Response
{
  "items": [
    {
      "id": "string",
      "account_id": "string",
      "application_id": "string",
      "environment_id": "string",
      "actor_id": "string",
      "actor_type": "string",
      "action": "string",
      "resource_type": "string",
      "resource_id": "string",
      "metadata": {},
      "created_at": "2026-04-20T12:00:00.000Z",
      "actor_label": "string",
      "resource_label": "string",
      "correlation_id": "00000000-0000-0000-0000-000000000000",
      "outcome": "success",
      "category": "auth",
      "severity": "info",
      "customer_visible": false,
      "identity_visible": false
    }
  ],
  "pagination": {
    "next_cursor": "string"
  }
}
 Related endpoints
GETList recent audit-log export jobs
POSTCreate an identity audit-events export job (CSV / NDJSON)
GETGet an audit-log export job
DELETEDelete an audit-log export job
GETGet an identity audit event with related events
 Was this page helpful?

Tell us how we can improve this guide.

Canopy