Appearance
Audit and usage
The audit log and the usage records.
GET /v1/audit
Audit log (audit.read).
A page of the events the filters select, newest first. Each event names the principal, its actorKind (user, key or agent), onBehalfOf for agents, the source the request came through (api, mcp, cli, sweep), and the node that wrote it. The log is read across its rotated files (dataDir/audit/), or on state.driver postgres from the table every node writes to.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | The first time, inclusive. An RFC 3339 time, or a date for the start of that UTC day. | |
to | query | string | The last time, exclusive. An RFC 3339 time, or a date, which includes that UTC day. | |
principal | query | string | Who acted, or the user an agent acted for. | |
action | query | string | An action prefix; template. selects template.create, template.trash and the rest. | |
template | query | string | The template (or the folder or source the action names). | |
environment | query | string | ||
cursor | query | string | The next of the page before; leave it out for the newest. | |
limit | query | integer |
Responses
| Status | Description | Body |
|---|---|---|
200 | A page of events | AuditPage |
400 | A filter that can't be read, or {error: bad-cursor} for a cursor this log didn't hand out | |
403 | The caller lacks audit.read | |
429 | The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class. | object |
GET /v1/audit/export
Export the audit log (audit.read).
Streams every event the filters select, newest first, as a download: JSON lines, or CSV with one column per field (a cell a spreadsheet would read as a formula starts with '). The export is itself audited, as audit.export with its format.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | The first time, inclusive. An RFC 3339 time, or a date for the start of that UTC day. | |
to | query | string | The last time, exclusive. An RFC 3339 time, or a date, which includes that UTC day. | |
principal | query | string | Who acted, or the user an agent acted for. | |
action | query | string | An action prefix; template. selects template.create, template.trash and the rest. | |
template | query | string | The template (or the folder or source the action names). | |
environment | query | string | ||
format | query | jsonl, csv |
Responses
| Status | Description | Body |
|---|---|---|
200 | The events | AuditEvent, string |
400 | A filter or format that can't be read | |
403 | The caller lacks audit.read | |
429 | The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class. | object |
GET /v1/usage
Usage totals (audit.read).
The daily totals of the days from from to to, grouped by day, template, environment or format: renders by outcome, pages, bytes, and render time as total, p50, p95 and max (of the renders that reached the engine). days has each day's peak concurrent renders, jobs, webhook deliveries, API requests, 429s and 5xx answers by rate-limit class, and sign-ins. A day not rolled up yet, such as today, is totalled from its records and marked partial. Totals grouped across several days or groups take their percentiles from histograms, within 5%. template and environment narrow the renders; the rest is the whole install's.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string (date) | The first day (default 29 days before today, UTC) | |
to | query | string (date) | The last day, included (default today) | |
by | query | day, template, environment, format | ||
template | query | string | ||
environment | query | string | ||
format | query | json, csv | csv answers the rows, with each day's activity for by=day |
Responses
| Status | Description | Body |
|---|---|---|
200 | The totals | UsageReport, string |
400 | A range, grouping or format that can't be read | |
403 | The caller lacks audit.read | |
429 | The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class. | object |
GET /v1/usage/records
Usage records (audit.read).
A page of the records, newest first, within usage.detailDays: one per render, job, webhook delivery, sign-in, 429 and 5xx answer, and one tally a minute per node and rate-limit class. With format=csv, every record the filters select, from the cursor on.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
from | query | string | The first time, inclusive. An RFC 3339 time, or a date for the start of that UTC day. | |
to | query | string | The last time, exclusive. An RFC 3339 time, or a date, which includes that UTC day. | |
kind | query | render, job, webhook, signIn, rateLimited, error, tally | ||
template | query | string | ||
principal | query | string | Who acted, or the user an agent acted for | |
cursor | query | string | ||
limit | query | integer | ||
format | query | json, csv |
Responses
| Status | Description | Body |
|---|---|---|
200 | object, string | |
400 | A filter that can't be read, or | |
403 | The caller lacks audit.read | |
429 | The request's class is over its rate limit (limits.rate, or the API key's own rateLimits): {error: "rate-limited", class, message, retryAfter}. The MCP tool-call and agent edit limits answer the same body without class. | object |
200 body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
records | array of UsageRecord | yes | |
next | string |
200 body (text/csv): string