For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Migrate from Codex Daily Usage to Unified Daily Usage API

Move daily usage reporting to the unified Daily Usage Analytics API

Move integrations that call the Codex Daily Usage API to the unified Daily Usage Analytics API before the retirement date in your deprecation notice. The replacement reports daily ChatGPT, Codex, and Work usage.

This guide covers the /usage endpoint. It doesn’t retire the Codex turn-insights, code-review, or code-review-response endpoints. For the current API contract, see the Admin API reference.

1. Grant access to the replacement API

Before you create the key, confirm that the replacement endpoint is enabled for your workspace.

In the OpenAI Admin Console, open Credentials > Admin keys. Create a workspace-scoped Admin key with Custom permissions and Enterprise analytics API set to Read.

The required scope is enterprise.analytics.usage.read. The old scope, codex.enterprise.analytics.read, doesn’t grant access to the replacement endpoint. Use an Admin key, not an API Platform project key.

Keep the old integration available while you validate the replacement. Keep its credentials and codex.enterprise.analytics.read permission while you compare results from both APIs.

2. Change the endpoint and keep the reporting window

Replace the old endpoint:

GET https://api.chatgpt.com/v1/analytics/codex/workspaces/{workspace_id}/usage

Use the new endpoint with the same workspace ID:

GET https://api.chatgpt.com/v1/analytics/workspaces/{workspace_id}/usage

Send Authorization: Bearer <admin_api_key> and use the exact path without a trailing slash. Set ADMIN_API_KEY in your environment. Replace the illustrative workspace ID ws_123 with your workspace ID. This example reports September 10, 2026, UTC. Change start_time and end_time to Unix timestamps in seconds at UTC midnight for your reporting window:

curl --get "https://api.chatgpt.com/v1/analytics/workspaces/ws_123/usage" \
  --header "Authorization: Bearer ${ADMIN_API_KEY}" \
  --data-urlencode "start_time=1788998400" \
  --data-urlencode "end_time=1789084800" \
  --data-urlencode "group=workspace" \
  --data-urlencode "limit=1000"

The start_time bound is inclusive; end_time is exclusive. Use explicit date bounds for repeatable comparisons. Set group=workspace for one workspace-wide row per UTC day, or omit group for per-user daily rows. The default page limit is 1,000 rows, and the maximum is 30,000.

3. Update response parsing

The page envelope remains object, data, has_more, and next_page. The fields start_time, end_time, user_id, actor, clients, models, and code_attribution retain their roles. Optional fields are returned when available.

Update these values and fields in each daily row:

Codex Daily Usage API Daily Usage Analytics API Interpretation
workspace.codex.usage.result workspace.usage.result Row discriminator
totals.threads totals.chats For Codex, threads started
totals.turns totals.messages For Codex, turns sent
clients[].threads clients[].chats Apply the same rename to each client
clients[].turns clients[].messages Apply the same rename to each client

Accept additional client IDs for ChatGPT and other supported products. Preserve unknown IDs so that new clients don’t break ingestion. Keep models[] at the daily-row level: model buckets can combine products and clients, and there is no clients[].models[] breakdown.

For example, selected fields in a Codex client entry change from:

{
  "client_id": "CODEX_CLI",
  "threads": 2,
  "turns": 5,
  "credits": 1.5,
  "cost_usd": null
}

To:

{
  "client_id": "CODEX_CLI",
  "chats": 2,
  "messages": 5,
  "credits": 1.5,
  "cost_usd": null
}

These examples show selected fields only. Parse the actual response without requiring optional fields.

4. Preserve billing, token, and identity semantics

  • Keep credits and cost_usd separate. The cost_usd field reports native USD-priced usage when available. It can be null and isn’t a final invoice amount.
  • Treat estimated_cost_usd as an estimate of only the credit-priced portion at the workspace’s current credit overage rate. It’s omitted for USD-only usage. Don’t replace native cost_usd with this estimate or add credits directly to dollars.
  • Keep the token field names: uncached_text_input_tokens, cached_text_input_tokens, text_output_tokens, and text_total_tokens. Token fields are optional. An omitted token field means no eligible contribution is available, not zero. Don’t assume token counts cover every product or client in the unified report.
  • Use user_id as the stable key for per-user rows. The actor.email field can be null. Workspace aggregates have no individual actor.
  • Expect differences between workspace and per-user totals. Per-user results can omit deleted-user activity that remains in the group=workspace historical totals.

5. Start a new pagination sequence

Don’t reuse a Codex Daily Usage cursor on the replacement endpoint. Make the first request without page. While has_more is true, pass next_page as page and preserve the other query parameters. Stop when has_more is false. A single page might not contain the complete workspace or date range.

Keep existing retry and backoff behavior for rate limits and transient failures. Treat a 401 as an authentication problem, a 403 as a permission or workspace access problem, and a 400 as a request or cursor problem. Correct the cause before retrying a persistent client error.

6. Validate comparable usage, then switch over

Run both endpoints for the same closed UTC days and grouping, and fetch every page. Unified totals include ChatGPT activity, so they can exceed the old Codex and Work totals. Compare matching Codex and Work client entries and the renamed activity fields. Review client grouping changes, particularly review-related and unknown clients.

Don’t require totals or models[] to equal the sum of selected clients[]. Billing and token totals can contain usage without supported client attribution. If your integration requires exact Codex-only monetary or model totals, validate that requirement before switching over. Contact your OpenAI account team if the available breakdown is insufficient.

Usage is eventually consistent. Fetch recent days again to include late corrections. Insert or update rows by workspace, UTC day, and user ID or workspace grouping, instead of appending duplicate daily rows.

Before you stop the old integration:

  • Verify per-user and workspace reports, responses with multiple pages, and days with no returned rows.
  • Verify billing values that can be null, omitted token fields, days with both credit and USD usage, and missing actor emails.
  • Update scheduled jobs, saved queries, parsers, dashboards, and alerting to use the replacement endpoint.
  • Confirm successful scheduled runs, then stop polling the old endpoint. Remove obsolete credentials only when no other integration needs them.

If you need more time

Contact your OpenAI account team before retirement with your workspace ID, remaining migration blocker, and requested extension end date. Short extensions require explicit confirmation. Continue migration work while the request is reviewed.