Organization API
Your organization's usage and spend: totals per time bucket, per-call detail, and a full export. The organization is determined by the caller's API key — there is no organization id in the path, and any valid key of the organization can read it.
Base URL
Get started
Loading…Facts and limits
| Fact | Detail |
|---|---|
| The organization is the key | The caller's API key resolves to exactly one organization; no organization id appears in any path, and any valid key of the organization can read this domain |
| Actual charges only | What the organization was actually charged, in its settlement currency (CNY or USD); promotional balance is taken before cash and is included |
| Column names follow FOCUS 1.3 | BilledCost, ServiceName, ConsumedQuantity and the rest match the FOCUS 1.3 specification verbatim |
| Everything is UTC | Window bounds and buckets are UTC ISO 8601; buckets align to the hour or the UTC day |
| Windows cap at 93 days | Costs, usage and events accept at most 93 days per query; for longer ranges use the charges export, which paginates day by day server-side |
| Pagination is an opaque cursor | Lists carry has_more and next_page; pass next_page back as page unchanged |
Amounts are decimal strings (e.g. "0.001234") in the currency named by BillingCurrency on the same row (CNY or USD) — don't sum them as floats, and never add amounts of different currencies; reconcile with exact decimal arithmetic.
Only usage billed in USD from the funding account is counted here; Credits balances are not part of this domain. See Authentication for how keys work.
Endpoints
| Method | Path | Description | Support |
|---|---|---|---|
| GET | /v1/costs | List costs | ● Supported |
| GET | /v1/usage | List usage | ● Supported |
| GET | /v1/events | List usage events | ● Supported |
| GET | /v1/events/{id} | Get a usage event | ● Supported |
| GET | /v1/charges | Export charges | ● Supported |
Differences from FOCUS 1.3
- The envelope follows OpenAI's organization usage/costs, the bucketing and estimated marker follow AWS GetCostAndUsage, column names follow FOCUS 1.3, and the export follows Vercel's charges JSONL. Raw facts only: shares, trends and top-N views are not in this domain — compute them on your side.
For authoritative parameters and fields, see the spec published at /meta/v1/openapi.yaml and the FOCUS 1.3 specification.
Errors follow the problem+json format, see errors; quotas and response headers are covered in rate limits.