Skip to content
CostReveal
Menu

Connecting OpenAI to CostReveal, setup guide

The CostReveal team, , 7 minute read

AI spend is the line finance asks about most and understands least. A single OpenAI total on the invoice hides which product, team or feature used the tokens. This guide covers how CostReveal reads your OpenAI organization's costs report with an admin key, what that key can do, how spend is broken down by project, model and line item, how you name the owner of each project, what usage data can and cannot do for OpenAI today, and how each month is checked against OpenAI's own total.

What the OpenAI connection reads

CostReveal reads what OpenAI bills from your organization's costs report, through OpenAI's Admin API. Nothing changes in the code that calls OpenAI, and nothing sits between your application and the API.

The costs report breaks spend down by day, project and line item. That is the grain CostReveal records: a day, a project and one line item, such as gpt-5, input_tokens. The costs report does not break spend down by API key, so CostReveal does not either. If you need to separate two features, the place to do it in OpenAI is the project.

Spend on OpenAI models through Azure is on your Azure bill and arrives through the Azure connection, not this one.

What you need

  • An OpenAI organization, and an organization owner, who can create admin keys.
  • An owner or admin role in CostReveal.

Step by step setup

1. Create an admin key

In the OpenAI Platform, go to Settings, Organization, Admin keys and create a key. Name it for CostReveal, so it can be deleted on its own. Give it an expiry if your policy asks for one, and enter a new key before it ends.

2. Start the connection

In CostReveal, go to Connections and choose Connect OpenAI.

3. Verify and connect

Paste the key and choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal reads your organization's projects and its costs report with the key before saving anything, and says exactly what is wrong if it cannot.

OpenAI reports costs by day and updates the current day as it goes. CostReveal reads them every hour, so today's figures grow until the day ends. The first read brings in the current month and the twelve before it, as far as OpenAI holds them. Where OpenAI holds no older months, Connections says how far back it reached, and each read asks again. After that, each read covers the current and previous month.

Which organization a key belongs to

OpenAI's Admin API does not say which organization a key belongs to. CostReveal knows it by a project the organization had when it was connected: OpenAI archives projects rather than deleting them, so that project identifies the organization for as long as it exists. This stops one OpenAI organization from feeding two CostReveal projects, and it is what a replacement key must match.

What an admin key can do

OpenAI admin keys cannot be limited to reading. A key could also manage your organization's members, projects and API keys. That is how OpenAI's Admin API works today.

CostReveal only ever reads costs and projects with it. The key is encrypted at rest, is never shown again after you enter it, and is deleted when you remove the connection. Delete it in the OpenAI Platform at any time; CostReveal then keeps every figure already read and tells you new data has stopped.

Connection states

Under Connections, the connection is always in one of four states:

  • Setup not finished: no key has been verified yet.
  • Waiting for first data: the key was verified, and the first read is due.
  • Connected: the costs report has been read and the latest read succeeded.
  • Needs attention: the latest read failed, for example because the key expired or was deleted. Everything already read is kept; enter a new key from the same organization to resume.

How OpenAI spend is explained

Service and model are direct

The service and the model come from OpenAI itself, so they carry the DIRECT basis. A token line item such as gpt-5, input_tokens is filed under OpenAI API tokens, for its model, with the tokens it billed for. Other line items, such as images, are each their own service, with their quantity in their own unit. A new model appears as soon as OpenAI bills it.

Team, feature and customer come from project owners you name

OpenAI projects carry no tags, so there is nothing on the bill that says who a project belongs to. You say it: under Connections, Project owners, name the team, feature or customer for each project. That explains the project's spend, with the INFERRED basis.

  • A project without an owner is UNKNOWN, shown as such and never spread across teams.
  • A project's name is never read as its owner. A project called support-bot explains nothing until you name its owner.
  • Costs OpenAI reports outside any project are listed as No project, and can be given an owner too.
  • Naming a project's owner explains every past period again. Renaming a project in OpenAI changes the name shown, and no figure.

Allocation rules for what is left

An allocation rule can name an owner for OpenAI lines that match conditions such as the model, the service or the resource (INFERRED), or share what is still unknown among owners at fixed percentages, evenly, or in proportion to explained spend (ALLOCATED). Project owners always come first.

What usage data does for OpenAI today

Usage data is how CostReveal divides spend that many customers share, from your application's own record of each call. For OpenAI, it does not divide spend yet. Dividing a bill by tokens needs each line item matched reliably to a kind of token, and dividing on a guess could split a bill wrongly. Until that is in place, usage data naming OpenAI calls is accepted and recorded, and OpenAI spend shared between customers stays unknown by customer. Anthropic spend is divided by usage data today.

How the figures are checked

  • Exact amounts. Every amount is read exactly as OpenAI wrote it, never through a floating point number, so 0.1 and 0.2 add up to 0.3.
  • The ledger is append only. Every line is recorded as OpenAI reported it. A day OpenAI updates is recorded as a correction, and what it said before is kept. Reading the same data again records nothing new.
  • Attribution adds up. On every dimension, what is attributed must add up exactly to the ledger.
  • A second source. Each month's detailed lines must add up to the organization's total for the month from OpenAI's costs report, read separately. While a month is open, a difference is shown as pending; once the month has closed, it is flagged.

Getting the most out of attribution

Use one project per product, team or environment. Since the project is the finest unit of ownership OpenAI reports, it decides how finely you can attribute. A support assistant and a code assistant sharing one project are one figure; in separate projects, they are two.

Name owners as soon as you connect. Home's next best action suggests naming the team for the OpenAI project that would explain the most, and states what share of the period's total spend that is. Each named owner also applies to every past month.

Watch the model mix. Explore by model shows which models carry the bill. Grouped by model, then by project, it shows which projects use the expensive ones. Insights adds a forecast for the month and flags days when a service spent outside its normal range.

Give owners budgets. A budget on a team alerts the people you choose as its OpenAI spend nears a monthly limit. It never blocks a call.

Frequently asked questions

Why does CostReveal need an admin key instead of a regular API key? Only admin keys can read an organization's costs report and its projects. Regular API keys make calls; they cannot see what anything cost.

Does CostReveal break OpenAI spend down by API key? No. OpenAI's costs report breaks spend down by project and line item, not by API key, so CostReveal records it by project and line item. Use separate projects to separate spend.

How do I tell CostReveal which team owns a project? Under Connections, Project owners, name the team, feature or customer for each project. OpenAI projects carry no tags, so this is how project spend is explained, and every past period is explained again.

What is the No project line? Costs OpenAI reports outside any project. They are listed as No project and can be given an owner like any project.

Can usage data divide OpenAI spend by customer? Not yet. Usage data naming OpenAI calls is accepted and recorded, but OpenAI spend shared between customers stays unknown by customer until line items can be matched to kinds of token reliably.

How much history does CostReveal read? The first read brings in the current month and the twelve before it, as far as OpenAI holds them. Where OpenAI holds no older months, Connections says how far back it reached, and each read asks again. After that, each hourly read covers the current and previous month.

What happens when my admin key expires? The connection shows Needs attention and keeps every figure already read. Create a new key in the same OpenAI organization and enter it in the connection.

Keep reading

More setup guides