Usage¶

GET /v1/usage returns aggregated usage for the project that owns the API key. It is meant for cost dashboards and internal integrations. The project is taken from the key, never from a parameter, so a key can only ever read its own project.

Data comes from the metering aggregate and can lag by up to about 5 minutes.

GET https://api.trusttyped.com/v1/usage?start=2026-09-01&end=2026-09-08&group_by=day
Authorization: Bearer tt_live_…

Parameters¶

Parameter	Required	Description
`start`	yes	Start of the range, inclusive, as `YYYY-MM-DD`.
`end`	yes	End of the range, exclusive, as `YYYY-MM-DD`. Must be after `start`; the range may be at most 92 days.
`group_by`	no	`day` (default) or `model`.

Dates are interpreted on the service's local day (Asia/Jakarta), not UTC.

Grouping¶

group_by=day → one row per day, with date set and model absent.
group_by=model → one row per model, with model set and date absent.

Response¶

{
  "object": "usage_summary",
  "start": "2026-09-01",
  "end": "2026-09-08",
  "data": [
    {
      "date": "2026-09-01",
      "requests": 128,
      "errors": 3,
      "input_tokens": 5120,
      "output_tokens": 2011,
      "fields": 384,
      "images": 2
    }
  ]
}

Field	Description
`object`	Always `"usage_summary"`.
`start` / `end`	Echo of the requested range.
`data[].date`	Present when `group_by=day`.
`data[].model`	Present when `group_by=model`.
`data[].requests`	Requests counted in the bucket.
`data[].errors`	Error responses in the bucket.
`data[].input_tokens`	Prompt tokens.
`data[].output_tokens`	Generated tokens.
`data[].fields`	Extracted fields.
`data[].images`	Images processed.

Example: group by model¶

curl "https://api.trusttyped.com/v1/usage?start=2026-09-01&end=2026-09-08&group_by=model" \
  -H "Authorization: Bearer tt_live_…"

Errors¶

`code`	Status	When
`invalid_request`	400	Missing/malformed date, `end` not after `start`, range over 92 days, or a bad `group_by` (the `param` names the culprit).
`permission_error`	403	The key is not bound to a project (no project usage to read).
`rate_limit_exceeded`	429	Per-key rate limit exceeded.
`usage_unavailable`	503	Usage data temporarily unavailable.

Rate limit headers

GET /v1/usage includes the standard X-RateLimit-* headers and is subject to the same per-key rate limit. It does not consume engine concurrency (no engine work runs).