Usage

Read-only, and the most-used group in practice: what was consumed, when, and by what. Usage is a view of the same usage records the portal's Analytics and Logs pages and your invoice use. The API computes nothing of its own, so a late correction appears everywhere at the same time.

Both routes need an owner who is currently an organization Admin — the same rule as the portal's Analytics page. A Member's token gets 403 insufficient_scope.

Two rules make this data safe to build on:

• Breakdowns sum to totals — usually. For every field of totals except units, the sum over breakdown[] equals the total exactly when reconciled is true (the normal case). totals are never raised to match the breakdown; usage that cannot be attributed to a group, plus the tail beyond the top 20 groups, is reported in an other row rather than dropped. In rare cases the breakdown can briefly exceed the totals; the response then has reconciled: false and a breakdown_note. Retry for a consistent report — see below.
• No content, ever. Usage reports counts, money and identifiers only. Prompt and completion content, error text and client addresses are never returned by this API.

Money is reported twice: cost_nanousd is the exact integer amount in nano-USD (10⁻⁹ USD), and cost_usd is the same amount as a decimal string ("12.345678901"). Sum cost_nanousd or parse cost_usd as a decimal — never as a float.

Query usage

GET /api/v1/mgmt/usage

Aggregated usage and cost over [from, to), broken down by one dimension.

GET /usage is a report, not a list: it is not paginated, and limit or cursor return 422 unsupported_filter, as does any other unknown parameter.

For project, model and key, the top 20 groups are returned individually; the rest, plus any usage that could not be attributed (for example requests with no key), are folded into a single row with key: "other".

The usage report

Every total and every breakdown row carries the same usage quantities:

totals.units[] gives the native-unit quantity per billing unit (token, image, second, character, document, …) — unit, requests, quantity_in, quantity_out, cost_nanousd, cost_usd. Quantities of different units are never summed together.

curl -G https://portal.<domain>/api/v1/mgmt/usage \
  -H "Authorization: Bearer $TF_PAT" \
  -d from=2026-09-01T00:00:00Z \
  -d to=2026-09-08T00:00:00Z \
  -d group_by=model

import os
import requests

resp = requests.get(
    "https://portal.<domain>/api/v1/mgmt/usage",
    headers={"Authorization": f"Bearer {os.environ['TF_PAT']}"},
    params={"from": "2026-09-01T00:00:00Z", "to": "2026-09-08T00:00:00Z", "group_by": "model"},
    timeout=60,
)
resp.raise_for_status()
report = resp.json()
rows_total = sum(r["cost_nanousd"] for r in report["breakdown"])
if report["reconciled"]:
    assert rows_total == report["totals"]["cost_nanousd"]  # breakdowns reconcile exactly
else:
    print("not reconciled:", report["breakdown_note"])  # retry for a consistent report
for row in report["breakdown"]:
    print(row["key"], row["requests"], row["cost_usd"])

{
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-08T00:00:00Z",
  "group_by": "model",
  "currency": "USD",
  "totals": {
    "requests": 105,
    "errors": 2,
    "input_tokens": 1500,
    "output_tokens": 700,
    "total_tokens": 2200,
    "cached_input_tokens": 40,
    "cache_write_tokens": 0,
    "reasoning_tokens": 0,
    "cost_nanousd": 3123456789,
    "cost_usd": "3.123456789",
    "units": [
      { "unit": "token", "requests": 105, "quantity_in": 1500, "quantity_out": 700, "cost_nanousd": 3123456789, "cost_usd": "3.123456789" }
    ]
  },
  "breakdown": [
    {
      "key": "openai/gpt-4o",
      "requests": 60,
      "errors": 0,
      "input_tokens": 1000,
      "output_tokens": 500,
      "total_tokens": 1500,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0,
      "cost_nanousd": 2000000000,
      "cost_usd": "2.00"
    },
    {
      "key": "other",
      "requests": 45,
      "errors": 2,
      "input_tokens": 500,
      "output_tokens": 200,
      "total_tokens": 700,
      "cached_input_tokens": 40,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0,
      "cost_nanousd": 1123456789,
      "cost_usd": "1.123456789"
    }
  ],
  "reconciled": true,
  "usage_stale": false,
  "usage_as_of": "2026-09-24T09:59:15Z"
}

Need two dimensions — per project per day, say? Make one group_by=day call per project (project_id=…), or one group_by=project call per day. Several values in one call (group_by=project,day) are refused with 422 unsupported_filter.

Export usage

GET /api/v1/mgmt/usage/export

The backfill path: one record per metered request in [from, to), newest first, streamed as JSON Lines or CSV.

There is no group_by, and the export is not paged: limit, cursor and any other parameter return 422 unsupported_filter.

At most 10,000 records per call. A window that matches more is refused with 422 export_too_large before anything streams — narrow from/to and export in windows, or read the aggregates with GET /usage. Requests running longer than 60 seconds are cut off.

Each record:

Truncation

An export can stop early after the 200 status has been sent. A truncated export is therefore not an error response; it is a stream that ends with a marker line:

• JSONL: a last line {"truncated":true,"rows":N,"reason":"row_cap"|"upstream_error"}.
• CSV: a last line # truncated after N rows (<reason>).

A response that was cut short also carries an X-Export-Truncated: true HTTP trailer (declared in the Trailer header) — but trailers are sent after the body and some proxies silently drop them, so treat the trailer as a convenience, not the source of truth. The final line of the stream is the reliable signal: always check for the truncation marker before treating an export as complete.

reason: row_cap means the window matched more than 10,000 records after all — narrow from/to and export the rest separately. reason: upstream_error means reading the usage data failed mid-stream — re-run the same export.

The export reads records newest first, in pages of 200, with a cursor on (created_at, id). Records that share the same created_at are all exported, each exactly once, however many there are.

Every completed export is recorded in the audit log as usage_export, with row_count, format, from and to — bulk data movement deserves the same trail as any other.

curl -G https://portal.<domain>/api/v1/mgmt/usage/export \
  -H "Authorization: Bearer $TF_PAT" \
  -d format=csv \
  -d from=2026-09-23T00:00:00Z \
  -d to=2026-09-24T00:00:00Z \
  -o usage-2026-09-23.csv

import json

with requests.get(
    "https://portal.<domain>/api/v1/mgmt/usage/export",
    headers={"Authorization": f"Bearer {os.environ['TF_PAT']}"},
    params={"format": "jsonl", "from": "2026-09-23T00:00:00Z", "to": "2026-09-24T00:00:00Z"},
    stream=True,
    timeout=90,
) as resp:
    if resp.status_code == 422 and resp.json()["error"]["code"] == "export_too_large":
        raise SystemExit("more than 10,000 requests in this window: split it")
    resp.raise_for_status()
    for line in resp.iter_lines():
        if not line:
            continue
        row = json.loads(line)
        if row.get("truncated"):
            # the reliable signal — X-Export-Truncated is a trailer some proxies drop
            print(f"stream cut short after {row['rows']} rows: {row['reason']}")
            break
        load_into_finops(row)  # your ingestion

{"id":"7c2e4f1a-9b3d-4e8a-a1c6-5d0f2b8e3a97","created_at":"2026-09-23T23:59:41.203Z","project_id":"5b3e9a41-0c7d-4e2f-8a16-9d4b7c2e1f08","key_id":"c41d8e2a-7b90-4f3c-a6e5-2d1f0b9c8a74","model":"openai/gpt-4o","provider":"openai","status":"ok","unit":"token","input_tokens":812,"output_tokens":164,"total_tokens":976,"cached_input_tokens":0,"cache_write_tokens":0,"reasoning_tokens":0,"quantity_in":0,"quantity_out":0,"cost_nanousd":3670000,"cost_usd":"0.00367","cost_available":true,"latency_ms":1840,"streaming":true}

Errors specific to usage

To reconcile usage with balances and invoices, see Billing.