Usage data

Export complete AI usage meters with UTC windows, pagination, and stable record IDs.

GET /v1/finops/usage exports complete meter-per-row usage for an authorized account.

GET /v1/finops/usage?start=2026-07-01T00:00:00Z&end=2026-07-08T00:00:00Z&granularity=1h&limit=1000
Authorization: Bearer <credential>

Windows and granularity

start inclusive, end exclusive (UTC RFC 3339)
Granularities in v0.1: 1h, 1d
Reject unsupported granularity with 400
Providers should retain at least 90 days; declare shallower retention in capabilities
Do not advertise hourly granularity if you only synthesize hours from a daily total

One meter per row

Input tokens, output tokens, cache reads/writes, requests, audio, characters, credits, and other meters are separate records.

Required fields include stable x_RecordId, x_RecordUpdatedAt, x_Granularity, charge period bounds, service identity, SkuId, SkuMeter, ConsumedQuantity, ConsumedUnit, and x_UsageType.

Core meters

`x_UsageType`	`ConsumedUnit`	Semantics
`input_tokens`	`tokens`	Uncached input only
`output_tokens`	`tokens`	Generated output
`cache_read_tokens`	`tokens`	Cache-served input
`cache_write_5m_tokens` / `cache_write_1h_tokens`	`tokens`	Cache writes
`input_audio_tokens` / `output_audio_tokens`	`tokens`	Audio token legs
`requests`	`requests`	Billable requests
`audio_seconds`	`seconds`	Audio duration
`characters`	`characters`	Text characters
`events`	`events`	Billable events
`session_minutes`	`minutes`	Session duration
`credits`	`credits`	Provider-native credits

Providers may add x_ extension meters. Consumers must preserve unknown extensions.

input_tokens is deliberately uncached. Summing it with cache_read_tokens yields total input without double-counting.

Dimensions

Advertise support in capabilities. Common AI dimensions:

x_ModelId (required for model inference when available)
x_ProjectId, x_WorkspaceId
x_ApiKeyId (opaque ID or irreversible hash, never the secret)
x_ServiceTier
x_WorkloadType (completions, embeddings, audio_in, tts, ...)
x_UpstreamProvider (actual serving host for gateways)

SkuId identifies the billable good. Do not use it as the only model identifier when one model has multiple meter or tier SKUs.

Completeness and pagination

The feed must be exhaustive for the window and account. Do not silently return only top-N models or keys.

Responses use cursor pagination:

{
  "data": [],
  "next_cursor": null,
  "as_of": "2026-07-08T01:05:00Z",
  "available_through": "2026-07-08T01:00:00Z"
}

Cursors bind account, filters, window, granularity, page size, and snapshot. Records stay stable for one cursor traversal. Prefer a deterministic order such as ChargePeriodStart, then x_RecordId.

Privacy

Exports must not include prompts, completions, audio/image payloads, plaintext inference keys, or unrelated personal data.