Research-backed calculator guide
OpenAI Usage CSV Field Dictionary for Finance and Engineering
Map OpenAI usage and cost export fields to owners, chargeback dimensions, and invoice reconciliation checks without confusing token activity with billed cost.
Quick answer
An OpenAI usage CSV is easiest to interpret when you separate four layers: the reporting bucket, the usage result, the attribution dimensions, and the monetary cost row. The dashboard export is not one universal schema. Activity exports describe usage, while Cost exports are intended for spend reporting and invoice-like line-item reconciliation. OpenAI’s current dashboard guidance recommends Cost data grouped by line item, with a daily interval, for a calendar-month reconciliation; Activity data can instead be grouped by project, user, API key, model, batch, or service tier. Dates in the dashboard are shown in UTC. [1]
For engineering, the practical dictionary is: start_time and end_time define the bucket; input_tokens, output_tokens, cache and modality fields describe measured usage; num_model_requests counts requests; and project_id, user_id, api_key_id, model, batch, service_tier, and sometimes api_source are attribution dimensions that become meaningful when selected in group_by. For finance, amount.value, amount.currency, line_item, quantity, and the export’s project or key grouping are the safer reconciliation fields. The Cost API documents amount.value as the numeric monetary value and amount.currency as a lowercase ISO-4217 code such as usd. [4]
Do not add every token column together. In particular, cached, cache-write, audio, image, uncached, and text fields can be component views of broader totals. Treat the vendor’s cost export as the billed-cost evidence, and use token fields for allocation, diagnostics, and variance analysis unless your rate-card assumptions explicitly match the meter and period.
What the CSV represents
There are two related jobs hidden behind “export my OpenAI usage CSV.” The first is operational analysis: which project, model, key, or service tier generated activity? The second is accounting: what amount and line item should reconcile to the invoice? OpenAI’s export instructions distinguish Activity data from Cost data and recommend Cost data grouped by line item when the goal is a detailed monthly breakdown. [1]
A useful mental model is a nested record flattened into rows:
- A bucket covers a UTC time interval. The API uses Unix-second
start_timeandend_time; the end is exclusive in the API reference. [3] - A result holds aggregate usage or cost for that bucket. One bucket can contain several results when you group by dimensions.
- Dimensions identify where to assign the result, such as project or API key. A dimension may be blank or null when it was not selected for grouping.
- Measures quantify activity or money. Token counts and request counts are not dollars; a cost amount is not a token count.
The dashboard can produce a CSV for a selected date range, including a full calendar month or month-to-date. Large exports may take time to generate, and the Usage Dashboard follows UTC. [1] [2] Preserve the original file and record the organization, filters, date range, interval, and export type beside your transformed table. Those metadata are part of your audit trail even if they do not appear as ordinary business columns.
OpenAI usage CSV columns: field dictionary
The names below are the fields to expect or map when normalizing current dashboard/API output. A downloaded CSV can use presentation labels rather than the JSON names, so map by meaning and retain the raw header as a source column. The exact set varies by export type, endpoint, capability, grouping, and product changes.
| Field or CSV label | What it means | Unit or shape | Finance/engineering handling |
|---|---|---|---|
start_time | Beginning of the aggregate bucket | Unix seconds in API; date/time in CSV | Convert once to UTC and retain the raw value |
end_time | End of the bucket, exclusive in the API | Unix seconds; date/time in CSV | Use half-open intervals to avoid double counting |
project_id | Project attribution dimension | Identifier | Charge back to project when grouped or present |
user_id | User attribution dimension | Identifier | Apply privacy and access controls; may be null |
api_key_id | API key attribution dimension | Identifier | Useful for service ownership, not necessarily a human owner |
model | Model associated with a grouped result | String | Join to the rate-card snapshot used for analysis |
batch | Whether the grouped result is batch or non-batch | Boolean | Keep as a dimension; batch pricing may differ |
service_tier | Service tier associated with the usage | String | Segment standard, priority, scale, or other tiers only when returned |
api_source | Published source attribution where supported | agents_api, unlabeled, or null | Do not treat unlabeled as proof of direct API usage |
input_tokens / output_tokens | Aggregate input and output token measures | Token counts | Use for activity and allocation, not automatic invoice totals |
input_cached_tokens | Cached input token measure | Tokens | Do not add to input_tokens unless the schema says they are separate |
input_cache_write_tokens | Input written to cache | Tokens | Keep separate because cache-write pricing may differ |
input_text_tokens, audio and image fields | Modality-specific components | Tokens | Sum only within a defined meter; keep modality columns visible |
num_model_requests | Count of model requests in the result | Count | Useful for unit economics and outlier checks |
object | Record type, such as a bucket or usage result | String | Keep for schema validation, not chargeback |
line_item | Cost category selected for grouping | String | Prefer for invoice-like cost reporting |
amount.value / amount.currency | Monetary amount and currency | Decimal plus ISO currency code | Reconcile as money; never assume cents without evidence |
quantity / quantity_unit | Quantity behind a cost line where available | Number plus unit | Interpret together; unit can be tokens, seconds, images, or another supported meter |
The official Completions Usage reference lists grouping by project, user, API key, model, batch, service tier, and API source. It also documents cache-write windows, cached text/audio/image tokens, uncached input, modality outputs, and pagination fields such as has_more and next_page. [3] A blank dimension is therefore not automatically missing data. It can mean that the report was not grouped by that dimension. The cookbook illustrates this behavior: without group_by, fields such as project and model can return as null, while adding a grouping produces useful attribution. [5]
The Costs reference adds an important accounting distinction. Cost results have an amount object, and when the result is grouped by line item, the row can include line_item and quantity; the documented cost response also includes project and API-key dimensions when requested. [4] That makes a line-item Cost export the better starting point for invoice matching, while Activity data is the better starting point for explaining who or what generated the work.
How to normalize the export safely
Start by storing a raw landing table with the original CSV untouched. Add source_file, organization_id, export_type, exported_at_utc, range_start_utc, range_end_utc, and group_by_snapshot. These are your provenance fields. Do not silently rename an ambiguous column or overwrite an existing export when a new file has a different interval.
Next, normalize time. Convert Unix seconds to UTC timestamps and use a half-open interval, [start_time, end_time). If one file is daily and another is hourly, do not compare row counts as if they represented the same grain. Aggregate the finer-grain file to the coarser grain before comparing totals.
Then classify columns as dimensions or measures. A dimension answers “where or how should this row be assigned?” A measure answers “how much activity or money is in this row?” Keep IDs as strings, keep booleans as booleans, and keep monetary values as decimals. Preserve nulls. Replacing a null model or project with unknown can be useful for a display layer, but retain a separate raw-null flag for reconciliation.
Finally, paginate API pulls and retain the cursor. The cookbook’s example retrieves buckets until next_page is empty, then flattens each bucket’s results into a pandas table. [5] A CSV downloaded from the dashboard may already be complete, but the same completeness check applies: confirm the requested date range, number of files, row count, and whether an export was split.
Worked cost example: allocation without double counting
Assume a finance team receives a daily Cost export and wants to allocate one line to Engineering. The numbers below are an illustrative calculation, not a vendor quote and not a claim about current OpenAI pricing. The assumed rates are deliberately labeled so the team can replace them with its approved rate-card snapshot.
| Step | Input or assumption | Output |
|---|---|---|
| 1. Reporting grain | 2026-10-14 00:00–2026-10-15 00:00 UTC; project proj_engineering; model model-example | One half-open daily bucket |
| 2. Usage measures | 1,000,000 uncached input tokens; 200,000 cached input tokens; 300,000 output tokens; 10,000 requests | Activity profile, not yet an invoice |
| 3. Illustrative rates | Uncached input $2.50 / 1M; cached input $0.25 / 1M; output $10.00 / 1M | Assumptions only |
| 4. Component math | 1.0M × 2.50 / 1M + 0.2M × 0.25 / 1M + 0.3M × 10.00 / 1M | $2.50 + $0.05 + $3.00 = $5.55 estimated usage cost |
| 5. Cost-export check | Cost row has amount.value = 5.80, amount.currency = usd, line_item = model-example, quantity_unit = 1000_tokens | $5.80 is the reconciliation value; $0.25 variance needs investigation |
| 6. Chargeback output | Project owner = Engineering; period = UTC day; source file and filters retained | Allocate $5.80, annotate the $5.55 estimate and variance |
The difference is not automatically an error. The Cost row may include a meter the simple token formula omitted, a different rate tier, rounding, or a line-item treatment that is not represented by the three assumed components. The correct workflow is to investigate the variance, not to replace the cost export with an invented formula. If the Cost export is grouped by line item, preserve the line item and quantity together; if it is grouped by project and API key, retain both dimensions so Finance can explain the owner and Engineering can trace the source.
For the next step, use the AI API invoice reconciliation calculator to structure the estimate-versus-actual comparison. If you need to test a rate-card assumption, compare models in the Model pricing comparison, then use the LLM cost calculator or AI token cost calculator for scenario math. These tools estimate; the provider’s export remains the evidence for the actual billed amount.
Run your scenario
Turn this framework into an editable estimate.
Use dated, source-linked assumptions and see cost per request, successful task and month.
What to join for a finance handoff
A useful handoff table has one row at the chosen reporting grain and at least these join keys: organization, UTC bucket, project, API key, model, service tier, batch flag, line item, currency, and source file. Add an owner mapping outside the provider export, such as project_id → cost_center and api_key_id → service_owner. Do not treat a key name as proof of ownership; keys can be shared, rotated, or used by automation.
Keep two totals in the report. The first is provider actual, taken from the Cost export’s monetary fields. The second is analytical estimate, calculated from usage measures and a dated rate card. The variance between them is a control metric. It can reveal a wrong period, wrong organization, missing capability, cache treatment, currency conversion, or a grouping mismatch.
The dashboard’s project selector is independent of project selection elsewhere in the API Platform, and OpenAI advises checking the organization and period when an invoice does not reconcile. [2] This is why a reproducible handoff records filters instead of exporting a number and pasting it into a spreadsheet with no context.
Limitations and exclusions
This dictionary is a normalization guide, not a promise that every future CSV will have these exact headers. OpenAI can add fields, change labels, introduce new capability-specific meters, or expose fields only for selected groupings. Validate the header and the export metadata on every ingestion run.
The examples use USD notation for readability, but a real cost row must carry its returned currency. Do not convert currencies or assume cents, mills, or microdollars without a documented unit. Do not infer an invoice total by multiplying request count by an average price. Requests can differ by model, modality, cache status, service tier, batch treatment, and non-token capability.
The usage export also does not automatically create a business owner, department, customer, or product feature. Those are internal dimensions that require a controlled mapping table. Keep personal and key identifiers access-controlled, and avoid exposing raw user-level data in broad finance reports.
FAQ
Is an OpenAI usage CSV the same as an OpenAI cost CSV?
No. Activity data explains usage, such as tokens, requests, models, and attribution dimensions. Cost data is designed for detailed spend reporting and can include monetary amount, currency, line item, and quantity. Use Activity data to investigate drivers and Cost data to reconcile spend. OpenAI’s monthly export guidance explicitly presents them as separate export types. [1]
Why is project_id blank in my export?
A blank value can mean the report was not grouped by project, or that the particular result has no project attribution. The Usage API makes grouping explicit, and the cookbook notes that fields such as project and model can be null without a group_by parameter. Check the export settings before treating the blank as a data-quality incident. [5]
Can I calculate the invoice from input_tokens and output_tokens?
You can calculate an estimate if you have a dated rate card and know how cache, modality, batch, tier, and other meters are billed. You should not assume that estimate is the invoice. For reconciliation, compare the Cost export’s amount.value and currency, then use token math to explain or test the difference. The Costs API documents monetary amount separately from usage fields. [4]
What does api_key_id tell Finance?
It identifies the API key dimension when the result is grouped by key. It can support service ownership and chargeback, but it is not automatically a person, department, or product. Maintain an internal, access-controlled mapping from key ID to owner and review it when keys rotate.
Should I add cached tokens to input tokens?
Not by default. The API exposes broad and component token fields, including cached, cache-write, text, audio, image, and uncached measures. Adding them indiscriminately can double count. First identify which field is the aggregate meter for the report and which fields are component breakdowns; then use the provider’s cost row for the monetary check. [3]
Which timezone should I use for monthly reconciliation?
Use UTC unless your controlled reporting policy explicitly performs a documented conversion. OpenAI states that Usage Dashboard dates and times are shown in UTC, and its monthly export instructions use the calendar-month period in UTC for reconciliation. [1] [2]
Primary sources checked
Pricing and product behavior can change. These sources support the time-sensitive claims in this guide; verify current provider terms before committing spend.