DocsAPI reference

Export

The usage page and every reply behind it, as a file.

get/api/usage/export
Authentication
Bearer token
Retries
Safe to repeat
Body
None
Version
2026-09-03

csv is the reply log alone - one row per reply, the table a spreadsheet wants. The other formats carry the summary, breakdowns and chart as well. Capped at usage_service.EXPORT_MAX_ROWS replies; the file says so when the cap was reached.

Query parameters#

  • formatstring

    Default: xlsx·Pattern: ^(csv|xlsx|json|pdf|html)$

  • daysinteger | null

    Window length in days (default 30)

    ≥ 1 and ≤ 400

  • hoursinteger | null

    Window length in hours; overrides days

    ≥ 1 and ≤ 9600

  • fromstring (date-time) | null

    Window start (ISO 8601); overrides days and hours

  • tostring (date-time) | null

    Window end (ISO 8601)

  • agent_idstring | null

    Only this agent

  • modelstring | null

    Only this model id

    Up to 128 characters

  • channelstring | null

    Pattern: ^(website|whatsapp|telegram|slack|email|api)$

Responses#

  • 200OKapplication/json

    any

    5 response headers
    RateLimit-Limit

    Requests permitted in the current window.

    RateLimit-Remaining

    Requests left in the current window. Back off before it reaches 0.

    RateLimit-Reset

    Seconds until the current window resets.

    X-API-Version

    The dated version of the API contract that served this response, e.g. 2026-09-03. Pin against it; it changes only when a response shape changes incompatibly.

    X-Request-ID

    Quote this in a support request to identify the call.

  • 422Validation error

    The shared error envelope, served as application/problem+json with error.code set to validation_error. Its details name each field that failed and why.

Errors#

Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:

  • validation_error · 422 — The payload was well-formed JSON but failed schema validation.
  • unauthenticated · 401 — The request carried no API key, or one the API could not verify.
  • forbidden · 403 — The key is valid, but it is not allowed to do this — either the scope is missing or the resource belongs to another workspace.
  • rate_limited · 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.

More AI usage endpoints#

Something unclear or missing? Tell us and we’ll fix it.