Audit events scoped to this workspace

GET

/workspaces/{id}/audit

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

• Hosted tenant

Permissions: caller must hold both a workspace-read scope (workspace:read or workspace:read:own with creator-match) and an audit-read scope (audit:read or audit:read:own). The handler doesn’t further narrow by user_id — workspace creators see every event for their workspace, including events triggered by other actors.

Same response shape as GET /audit. Filter columns, time bounds, limit, cursor, and order query params behave identically.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string

Query Parameters

filter

Array<string>

from

string format: date-time

to

string format: date-time

order

string

default: desc

Allowed values: asc desc

limit

integer

default: 100 <= 10000

cursor

string

Opaque resume pointer. See /audit for semantics.

Responses

200

One page of events.

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

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

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"
  }
}

404

Resource not found in the caller’s org

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"
  }
}