Organization Usage & Costs API¶

Report what this deployment consumed and what it cost, in time buckets, through the OpenAI Administration Usage and Costs API.

At a glance¶

• Eleven endpoints — ten /v1/organization/usage/* families reporting tokens, characters, seconds of audio, images and tool calls, plus /v1/organization/costs for what AWS bills — see Endpoints.
• Grouped by model, source, tenant API key or user — the keys that are served, and the ones refused with an explanation, are listed under Grouping.
• 1m buckets for 15 days, 1h and 1d for 455 — a query past the boundary is refused rather than answered at a coarser resolution, see Bucket width.
• Off by default — the surface is served only when usage_api is enabled.

from openai import OpenAI

client = OpenAI(base_url="https://your-gateway/v1", api_key="...")

page = client.admin.organization.usage.completions.list(
    start_time=1756000000, bucket_width="1d", limit=7, group_by=["model"]
)
for bucket in page.data:
    for result in bucket.results:
        print(bucket.start_time, result.model, result.input_tokens)

Endpoints¶

The two endpoints that report nothing answer a well-formed page of empty buckets rather than a 404: the endpoint exists, and no measurement was taken.

Enabling the surface¶

With usage_api disabled every endpoint answers 503. Enabling usage_api without cloudwatch_metrics fails at startup instead, rather than serving endpoints that could never answer — the server log names the missing setting.

The server role needs cloudwatch:GetMetricData and cloudwatch:ListMetrics — see Usage API IAM permissions — and the queries are billed per metric read, which Usage API query cost puts a number on.

Query parameters¶

Every endpoint takes:

Buckets are aligned to the UTC grid of the requested width, so start_time is rounded down to a bucket boundary and the reported start_time of the first bucket may be earlier than the one asked for.

/v1/organization/usage/images additionally takes sources (image.generation, image.edit, image.variation).

Grouping¶

A refused key answers 400 naming the key and the reason. A refused key is never silently ignored: the grouping is the request.

api_key_id and user_id may each be combined with model, but not with each other: usage is reported per key or per user, never per pair of the two. The same holds for the api_key_ids and user_ids filters, and for one of them combined with a grouping by the other.

A key that was not grouped by is omitted from the JSON object rather than sent as an explicit null. The openai SDK reads it back as None either way, so only a client parsing the raw JSON sees the difference — read such a key with result.get("model"), never result["model"].

Bucket width and how far back¶

Narrow buckets are only kept for so long:

A query past the boundary is refused with 400 naming the limit, rather than answered at a coarser resolution than it asked for — a usage report that silently changes resolution mid-range is a number that ends up in a spreadsheet. Ask for a later start_time, or a wider bucket_width.

The span between start_time and end_time is additionally bounded by usage_api_max_range_days, 92 days by default.

Costs¶

/v1/organization/costs reports the cost of the work in daily buckets, one result per currency:

{
  "object": "bucket",
  "start_time": 1756000000,
  "end_time": 1756086400,
  "results": [
    {
      "object": "organization.costs.result",
      "amount": {"value": 1.42, "currency": "usd"}
    }
  ]
}

Amounts are never summed across currencies: a deployment spanning partitions reports one result per currency.

Who may call it¶

Anything else answers 403. Upstream gates the same endpoints on a separate administrator credential; this is the closest equivalent a deployment can express.

Limits and behaviour to know¶

Where this surface answers differently from the upstream Administration API:

• Only the grouping keys and filters in Grouping are served; the rest are refused with an explanation rather than ignored.
• completions reports input_tokens, output_tokens, input_cached_tokens, input_cache_write_tokens, input_uncached_tokens and num_model_requests. input_tokens covers the whole prompt, cached and cache-write tokens included, so it reconciles with the prompt_tokens the same requests returned. The text/audio/image token breakdown upstream also publishes is not reported.
• num_model_requests counts only the records carrying the endpoint's own measurement. A guardrail applied around the call, the built-in web search, a managed knowledge base retrieval and the translation behind an audio translation are each billed apart and recorded under the operation of the request they served, so they reach neither the count nor the group_by=model rows of the endpoint that request went to.
• moderations reports num_model_requests for every moderation, and input_tokens only for the ones a language model answered: a guardrail and Amazon Comprehend are moderating backends here rather than a filter around another call, so their records are counted — and a moderation answered by an Amazon Bedrock guardrail counts once per policy that guardrail applies.
• web_search_calls reports num_requests and num_model_requests; context_level is never reported. num_model_requests counts every request the model answered in the bucket, not only the ones that called the search tool, whenever the two shared the same model, operation and grouping in that bucket: the search count is recorded on the model's own usage record, so a bucket mixing searching and non-searching traffic to the same model cannot be told apart from the metrics alone.
• file_search_calls counts searches for the deployment as a whole; vector_store_id is never reported.
• Batch API usage is absent from the usage endpoints. A batch's tokens are recorded against the route that collected its results, which carries no reported endpoint, so they reach neither completions nor embeddings — yet their spend is included in /v1/organization/costs. On a deployment running significant batch traffic, usage and costs therefore do not reconcile, by the whole batch workload.
• Usage is reported from a single region — see cloudwatch_metrics_region. A deployment publishing from more than one region reports the one it reads.
• next_page is this server's own cursor and is only meaningful to it.

How far back a bucket width is answered, and the two-week metric index behind every answer, are covered in Bucket width and how far back.

Try it¶

Report the last seven days of token usage per model, with administrator credentials:

curl -G "https://your-gateway/v1/organization/usage/completions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d start_time=1756000000 \
  -d bucket_width=1d \
  -d limit=7 \
  -d group_by=model

Next steps¶

Next: Configuration · Cost Management · Logging & Monitoring · IAM Permissions