Usage

Export daily aggregates as CSV or JSON

Changed on

Returns a downloadable file (CSV uses RFC-4180 quoting; JSON is a flat array — no envelope). The format query selects the content type. When projectId is set, every row carries that project's name in the project_name column. Supply startDate + endDate (YYYY-MM-DD, together, max 366 days) for a custom period; the filename then reflects those bounds instead of the preset.

connectionId and connectionType (api | oauth | agent | browser) narrow either mode to those connections; a connection from another organization matches nothing.

detail=full returns one row per UTC day × model × connection × project × person (UsageExportFullRow), sorted by date, connection, model, project and person, in a file named crbon-usage-full-<range>-<today>.<format>. With a signed-in (Clerk) session, an admin's export covers every person and anyone else's covers only their own usage. API-key callers get no person data: person_key and person_name are empty (null in JSON) and the rows are not split by person; the totals are the same. provider_cost_usd is empty (CSV) or null (JSON) where no event reported a provider cost. In the full CSV, a text cell that starts with =, +, -, @, a tab or a carriage return is prefixed with a single quote so a spreadsheet won't run it as a formula; JSON is not changed. Above 200,000 rows it answers 413 EXPORT_TOO_LARGE: narrow the date range or filter. The default, detail=daily, is the daily file as always.

get/api/v1/usage/export

Request

Query parameters

range'7d' | '30d' | '90d' | '365d'
startDatestring
endDatestring
format'csv' | 'json'
projectIdstring uuid
detail'daily' | 'full'
connectionIdstring uuid
connectionType'api' | 'oauth' | 'agent' | 'browser'

Response

Exported file (CSV or JSON depending on format param); detail=full rows are UsageExportFullRow

OR

Changes

    • breaking

      the response's body type changed from array to no type for status

    • info

      added the new optional query request parameter connectionId

    • info

      added the new optional query request parameter connectionType

    • info

      added the new optional query request parameter detail

    • info

      added subschema #1 subschema #2 to the response body anyOf list for the response status

    • info

      added the non-success response with the status

    • info

      added the new optional query request parameter endDate

    • info

      added the new optional query request parameter startDate