Returns provider billing data shaped as chart series, so you can plot spend and usage
over time or compare them across providers, models, API keys and people. Choose a
metric, a dimension and a mode.

metric: totalCost | inputCost | outputCost | cacheReadCost | cacheWriteCost
| requestCount | tokenCount | inputTokens | outputTokens
| uncachedInputTokens | cacheReadTokens | cacheWriteTokens

In aggregate mode metric also accepts a comma-separated list, and the response then
carries one series per metric. Time mode takes a single metric, because each series
there is named after its dimension value.

inputTokens is uncached plus cached input tokens. uncachedInputTokens,
cacheReadTokens, cacheWriteTokens and outputTokens split tokenCount without
overlapping.

dimension: none | provider | model | workspace | apiKey | usageType | serviceTier
| apiKeyModel | subscriber

• none: a single series named Total.
• provider: one series per provider.
• model: one series per model.
• workspace: one series per workspace. The key is the workspace name, or its id when it has no name.
• apiKey: one series per API key. The key is the API key name, or its id when it has no name.
• usageType: one series per usage type.
• serviceTier: one series per billing category the provider itself uses. For Cursor that is seat-included against usage-based.
• apiKeyModel: one series per API key and model. The key is the API key id and the model name joined by the character U+001F, so you can split it without relying on a key name that can be renamed.
• subscriber: one series per person. The key is the address the provider attributed the spend to, or the handle the provider names the person by when there is no address. Spend that belongs to nobody is grouped under (no person). One person is one key across every provider in the range, so a developer billed by two providers appears once, with their spend summed. This dimension works with cost metrics only, because usage is stored without a person. Asking for it with any other metric returns a 400.

mode: time (one series per dimension value over date buckets) | aggregate (one series per metric, one point per dimension value)
grain: day | week | month (time mode only)

Each response holds at most the 500 largest dimension keys, ranked by the metric named
first in metric. Every series in the response carries that same set of keys, so you
can join metrics by key. totalKeys reports the number of distinct keys before the
cap and truncated says whether the cap was applied, so a partial result is never
mistaken for a complete one.

To scope the chart to a single API key, pass the apiKey filter. Filtering the series
yourself after the request can give wrong results, because only the 500 largest keys
are returned.