# Supported billing export formats

All examples in `fixtures/` are synthetic. Use plain UTF-8 CSV or JSON. The local CLI and MCP accept 1 MB per file, up to 12 files and 4 MB combined. Split larger exports into non-overlapping periods. Currency codes are preserved; no exchange rate is assumed. Money results use JavaScript numbers normalized to 15 significant decimal digits, preserving subcent analysis rather than rounding to cents; this is not a bookkeeping ledger. Credits, refunds and taxes need invoice reconciliation and are not silently invented from usage.

## OpenRouter

Activity CSV supports the exported `model_permaslug`, `tokens_prompt`, `tokens_completion`, `tokens_cached`, `tokens_reasoning`, `cost_total` and `created_at` fields. A missing request count is one request per activity row. Cache reads are a subset of prompt tokens. Reasoning is a subset of completion tokens. `cost_total` is reported USD spend.

Start with `synthetic-openrouter.csv`. A normal provider API key is not required to analyze an export.

## OpenAI

Organization **completions usage** JSON: `data[]` buckets with `start_time`, `end_time` (Unix seconds) and `results[]` containing `object: "organization.usage.completions.result"`, `input_tokens`, `output_tokens`, `input_cached_tokens`, `num_model_requests`, optional `model` and `project_id`.

Organization **cost** JSON: the same bucket shape with `object: "organization.costs.result"`, `amount: { value, currency }`, optional `project_id` and `model`. `amount.value` is denominated in the stated currency; it is not cents. Costs may not be grouped by model. A missing model stays unknown.

Usage and cost are distinct reports. Loading both does not authorize allocating total project cost to individual models. See `synthetic-openai-usage.json` and `synthetic-openai-costs.json`.

Official reference: https://developers.openai.com/api/reference/resources/admin/subresources/organization/subresources/usage

## Anthropic

The current **Usage and Cost Analytics API** returns flat `data[]` rows with `starting_at`, `ending_at`, `group` (including optional model/workspace) and either `usage` or `cost`.

Usage metrics include `uncached_input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation.ephemeral_5m_input_tokens`, `cache_creation.ephemeral_1h_input_tokens` and `requests`. Uncached inputs, cache reads and cache writes are additional to one another.

Cost metrics include `cost.amount`, `cost.currency`, and `cost.requests`. `amount` is decimal **cents**: `"825.000000"` means USD 8.25. This importer does not silently reinterpret the legacy Usage and Cost API shape.

See `synthetic-anthropic-usage.json` and `synthetic-anthropic-costs.json`. The examples are not evidence of connected account access. Official reference: https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api

## Generic normalized CSV

Use `synthetic-normalized.csv` as a starting point. Headers:

```csv
provider,model,project,start,end,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,input_semantics,requests,amount,currency
```

`provider` is required. Supply at least token counts or an amount. Blank optional values remain unknown. `input_semantics` is `inclusive` when cache counts are a subset of input tokens, or `exclusive` when they are additional; the default is inclusive with a warning when needed. Dates may use `date`, `created_at` or `timestamp` as alternatives to `start`. `cost_usd` explicitly states USD. `cost_cents` is divided by 100 only when no other cost header exists. An amount without a stated currency is excluded from monetary totals.

Fields not needed by the normalized contract are ignored. Do not include prompts, completions, API-key secrets or user data.

## Pagination, overlapping files and errors

Combine complete pages from one report in `{ "pages": [page1, page2] }`. A response advertising more pages generates a partial-coverage warning. Do not combine usage and cost schemas in one JSON file. Identical imports are ignored; same-provider overlapping scopes are excluded conservatively. See warnings and `coverage.excludedImports` before interpreting totals. Keep separate billing accounts distinguishable; this MVP cannot reconcile arbitrary multi-account overlap automatically.

Malformed rows are rejected and counted; all-invalid files fail. Never treat an empty/error result as a zero bill. Dates, numbers and currencies must be valid. Negative monetary amounts are not supported in this MVP; do not remove credit rows without explaining that the reported usage cost is not a payable invoice.

## ccusage Claude Code and Codex daily JSON

Tested against `ccusage@20.0.48`. Export a dedicated report using `ccusage claude daily --json --offline --timezone UTC --breakdown` or `ccusage codex daily --json --offline --timezone UTC`. User-selected exports may contain private project labels; omit prompts and credentials. Unified multi-agent, session and project reports are not this format.

Both dedicated ccusage daily exports report uncached input separately from cache reads. Native Codex telemetry uses inclusive input; its dedicated ccusage daily export converts that to exclusive input. The importer normalizes these once, treats reasoning as a subset of output, and imports each daily estimate only once instead of repeating it across model breakdowns. Costs become **API-equivalent usage estimates**, separate from reported API charges and subscription commitments. Export JSON does not prove the pricing source, rate date, overrides or calculation mode. Native Codex cache writes remain unknown even when the report defaults them to zero.

Examples: `ccusage-claude-daily.json`, `ccusage-codex-daily.json`. Loading duplicate or overlapping reports does not authorize adding both totals. Check exclusion warnings.