Query the audit log

GET

/audit

curl --request GET \
  --url 'https://your-org.evershell.ai/v1/audit?order=asc&limit=100' \
  --header 'Authorization: Bearer <token>'

• Hosted tenant

Permissions: any of audit:read, audit:read:own, workspace:read, workspace:read:own. The rows returned are the union of what each held scope grants:

• audit:read → every event in the org.
• audit:read:own → events whose user_id is the caller (both audit and activity categories). Workspace-scoped events carry the workspace creator’s user_id, so this is events on workspaces the caller created plus the caller’s own non-workspace actions.
• workspace:read → every activity-category event.
• workspace:read:own → activity-category events on workspaces the caller created.

See Audit events for the full event-type catalog and detail shapes.

Pagination is opaque cursor-based: each response carries a cursor field when the page filled the requested limit; pass that value back as ?cursor=... for the next page. When cursor is absent, the page is the last one.

Authorizations

• bearerAuth

Parameters

Query Parameters

filter

Array<string>

Repeated for AND. Each value is col=val[,val2,...] for IN-match, col!=val[,val2,...] for NOT-IN, or col!= for “column populated”. See the Audit events doc for the column whitelist.

from

string format: date-time

Lower time bound, RFC3339.

to

string format: date-time

Upper time bound, RFC3339.

order

string

default: desc

Allowed values: asc desc

Sort order on (timestamp, id).

limit

integer

default: 100 <= 10000

Page size. Capped at 10000.

cursor

string

Opaque resume pointer returned by a previous page’s cursor field. Don’t construct or parse — pass it back verbatim. A malformed cursor returns 400 invalid_cursor.

Responses

200

One page of events, ordered by (timestamp, id).

Media type application/json

object

events

required

Array<object>

object

id

required

string

org_id

required

string

user_id

required

Real WorkOS user id for session-authenticated requests and proxy-emitted events; "system" for API-key-authenticated and WorkOS-webhook-driven events.

string

timestamp

required

string format: date-time

source_seq

required

Per-producer monotonic sequence used as the tiebreaker on equal timestamps. Order events by (timestamp, source_seq, id) to match the server’s ordering. Always present.

integer format: int64

event_type

required

Closed-enum — see Audit events for the catalog

string

category

required

string

Allowed values: audit activity

actor

required

string

Allowed values: control-plane policy-engine agent

workspace_id

string

task_id

string

agent_role

Role name; populated only on workspace-scoped events.

string

agent_provider

Provider name; populated only on workspace-scoped events.

string

destination

string

method

string

path

string

decision

string

Allowed values: allow deny

reason

string

latency_ms

integer

transforms_applied

integer

validations_applied

integer

capability_name

string

phase

string

Allowed values: request_headers request_body response_headers response_body dns

policy_type

string

Allowed values: http dns

detail

object

key

additional properties

any

debits

object

key

additional properties

integer

budget_state

Per-counter snapshot at commit point (proxy allows).

object

key

additional properties

any

floored

Per-counter “ceiling applied” reasons (proxy allows).

object

key

additional properties

string

transforms_failed

Per-transform failure reasons.

object

key

additional properties

string

auth_used

Credential names whose mint succeeded on the request.

Array<string>

auth_failures

Per-credential mint failure reasons.

object

key

additional properties

string

cursor

Opaque resume pointer for the next page. Present only when the page filled the requested limit; absent means no more pages.

string

Example

{
  "events": [
    {
      "category": "audit",
      "actor": "control-plane",
      "decision": "allow",
      "phase": "request_headers",
      "policy_type": "http"
    }
  ]
}

400

Malformed cursor.

Media type application/json

object

error

required

object

code

required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string

message

required

Human-readable summary

string

request_id

required

Server-generated request id for correlating logs

string

details

Optional structured context. Validation errors land at details.fields as a per-field map.

object

key

additional properties

any

Example

{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}

401

Missing or invalid credential

Media type application/json

object

error

required

object

code

required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string

message

required

Human-readable summary

string

request_id

required

Server-generated request id for correlating logs

string

details

Optional structured context. Validation errors land at details.fields as a per-field map.

object

key

additional properties

any

Example

{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}

403

Caller lacks the required scope, or cross-org access attempted

Media type application/json

object

error

required

object

code

required

Closed-enum slug (e.g. permission_denied, validation_error, workspace_not_found)

string

message

required

Human-readable summary

string

request_id

required

Server-generated request id for correlating logs

string

details

Optional structured context. Validation errors land at details.fields as a per-field map.

object

key

additional properties

any

Example

{
  "error": {
    "code": "permission_denied",
    "message": "caller lacks required scope",
    "request_id": "7f3a9c2e"
  }
}