OpenAI API Usage by Key: Reconcile Research Spend Without Exposing Secrets

Correct the reporting model before allocating spend

The official OpenAI organization Usage reference documents separate usage resources for completions, images, audio, vector stores, file search, web search and other activity. Relevant usage resources can return an api_key_id when the request uses group_by=api_key_id. That is an identifier and usage dimension, not the secret API key.

The same reference documents GET /organization/costs, but its supported grouping fields are project_id and line_item. This distinction changes the accounting method. You can inspect which key generated recorded units, and you can reconcile billed spend at the project or line-item level, but you cannot honestly label an amount “billed cost for this key” unless your own project design makes that attribution exclusive.

Choose an attribution design that matches the decision

The cleanest design is one project per durable budget boundary and one service-account key per operational owner or application inside that project. A project can then carry the authoritative cost boundary, while key-level usage reveals which controlled workload consumed the units. Do not create hundreds of keys merely to avoid keeping an internal run ledger.

Use a stable, non-secret alias such as sea-research-batch-06 in your own registry. Preserve the OpenAI key ID only in access-controlled operational records when it is needed for the Usage query. Never publish the raw key, authorization header, full admin response, account email, or private project name in an article download.

Collect usage without collecting secrets

Set an inclusive start_time, an exclusive end_time, a documented bucket width, and the exact usage resource being queried. Request the dimensions you need, including api_key_id, project_id, model, batch or service_tier only where that resource supports them. Continue through pagination until has_more is false.

Store totals in their native units. Tokens, image counts, audio seconds, file-search calls and web-search calls are not interchangeable. If a request fails before billable work is recorded, the application log and Usage response may disagree. Preserve the difference rather than forcing every internal request into a platform usage row.

The organization reporting endpoints use an administrative credential. Keep that credential out of the research worker and run the export through a restricted accounting job. The public worksheet needs the export time and aggregation rules, not the credential or raw response.

Reconcile project cost without inventing key-level billing

Fetch the Costs endpoint for the same time window and group by project_id and, when useful, line_item. Record the returned amount and currency exactly. OpenAI’s reference notes that usage and cost reporting may not reconcile perfectly because they record activity and spend differently; it recommends the Costs endpoint or Costs tab for financial reconciliation.

If a project contains only one controlled key and no other activity during the period, you can label the project cost as exclusively attributable under this project design. If several keys share the project, choose one of these honest treatments:

1. Report project cost and key usage side by side without allocating the amount.
2. Allocate using a documented unit-based method and label the result an estimate.
3. Change the future project design so the required budget boundary is native rather than reconstructed.

Do not distribute cost by token share when the project also uses images, web search, file search, storage, audio or other differently priced resources. A single unit ratio cannot represent heterogeneous line items.

Use the 24-field reconciliation ledger

Download the OpenAI usage and cost reconciliation ledger. Its unit of analysis is one usage bucket and editorial run association. Replace or remove all rows marked EXAMPLE-REMOVE; they demonstrate field use and are not observed SearchEngineAnswer results.

The ledger keeps the evidence boundary visible with separate columns for the usage source, cost source, allocation method, confidence and limitation. It also includes an owner, review date and artifact status so a budget anomaly becomes a decision instead of another unattended dashboard number.

Label every allocation estimate

Suppose a project’s completion usage contains two keys and no other billed service for the period. Key A accounts for 70% of the chosen billable unit and Key B for 30%. You may calculate an internal estimate using those shares, but the result remains an allocation model, not an OpenAI cost-by-key field.

Record the formula, denominator, included line items and residual. If the allocated rows total $19.80 while the Costs endpoint reports $20.00, preserve the $0.20 reconciliation difference. Do not silently spread it across keys. A residual can reveal timing, rounding, excluded services or an invalid allocation assumption.

Connect spend to editorial outcomes without a false ROI score

Give each research run an internal ID and carry it through the application log, source ledger, draft package and reconciliation row. Then record whether the result was accepted, revised, rejected, abandoned or left unpublished. A rejected run can still be useful if it prevents an unsupported article; an inexpensive draft can be costly if it creates hours of fact-checking.

Keep platform spend separate from quality and audience outcomes. Cost does not prove factual accuracy, originality, publication, indexing, citation, referral traffic or revenue. Use the AI visibility measurement crosswalk when the downstream question reaches citation or referral reporting, and use the small-experiment method when comparing workflow changes.

Run a monthly governance review

1. Confirm that every active project and key alias has an owner and purpose.
2. Export complete paginated usage and cost windows with matching time boundaries.
3. Investigate orphaned usage, unowned keys, unexpected models and unexplained line items.
4. Reconcile estimated allocations to the billed project amount and preserve residuals.
5. Review rejected and unpublished runs before calling them waste.
6. Rotate or revoke credentials that no longer serve an approved workload.
7. Set the next review date and retain only privacy-safe evidence in public artifacts.

The useful outcome is not a prettier cost chart. It is a record that lets an editor explain which controlled workload consumed resources, which amount is billed evidence, which amount is estimated, and what decision followed.

Sources, correction and method

Correction: the earlier version said OpenAI cost reporting could group by API key. The current official API reference supports API-key grouping on relevant Usage resources, while the Costs resource supports project and line-item grouping. The title and method were rebuilt around that boundary.

• OpenAI organization Usage and Costs API reference
• SearchEngineAnswer editorial and correction standards

Documentation was rechecked on August 29, 2026. This article describes the reporting contract and a reconciliation template; it does not claim access to the reader’s account, run an organization export, or report measured OpenAI spend.