Skip to main content
The Billing API returns your team’s usage and spend as JSON, so you can track costs, charge usage back to internal teams, or feed your own dashboards. It’s read-only and scoped to the team that owns the calling key: any key on your team reads all of the team’s figures. Spend figures update within about a minute of a request. Base URL: https://api.platform.getimpala.ai

Authentication

Send the API key you already use for inference as a bearer token. No separate key is needed.
A blocked or expired key gets a 401. Billing reads keep working when your wallet is empty and inference requests are refused.

Plan differences

On pay-as-you-go, /v1/account includes wallet, and /v1/account/prices returns your price list. On other plans, wallet is left out of the response (the field is absent, not null) and /v1/account/prices returns 404. /v1/account/spend reports spend_usd on pay-as-you-go and committed-usage plans; on contract plans it’s null. /v1/account/keys works the same on every plan.

Endpoints

Values in the response examples are illustrative.

Get account

GET /v1/account Returns your team, billing plan and the key that made the call. On pay-as-you-go, it also returns wallet.
string | null
Your customer ID.
string | null
Your team’s name.
string | null
pay_as_you_go, contract or committed_usage. null if your team has no plan on record.
object
The calling key, with the same fields as an entry in /v1/account/keys.
object
Pay-as-you-go only. Your prepaid wallet, in integer US cents.

List keys

GET /v1/account/keys Returns your team’s API keys. Only metadata is returned, never the key itself.
object[]
integer
The number of keys.

Get spend

GET /v1/account/spend Returns spend, requests and tokens for a date range, in one bucket per UTC day. spend_usd is the figure your Billing page shows for the same days and models.
string
First day, as YYYY-MM-DD. Defaults to the first day of the current month.
string
Last day, inclusive, as YYYY-MM-DD. Defaults to today, and a future date is treated as today. The window can span up to 400 days.
string
Breaks each day down by model, api_key, or both (model,api_key). Without it, each day has a single row.
string
Only include these keys, as a comma-separated list of key ids from /v1/account/keys. Every ID must be a current key on your team.
string
Only include these models, as a comma-separated list of model names as the report shows them. Any other name matches nothing.
string
The inclusive window the report covers. start can be later than requested when your account’s history starts later.
string
Always 1d.
string
Always usd.
string[]
The dimensions applied, in the order model, api_key.
object
The sum of every row in the report.
object[]
One entry per UTC day with usage. Days with no usage are left out rather than reported as zeros.
Token and request counts come from the usage meter, and the API key breakdown is usage only: grouping by api_key or filtering with api_key_ids returns spend_usd: null. Days before your billing started show their usage at 0.

Get prices

GET /v1/account/prices Returns your price list in USD per 1M tokens, the one your Billing page shows. Pay-as-you-go only; other plans get a 404.
string
Always usd.
object[]
One row per model on your price list.

Errors

Errors return JSON with a detail message. Errors specific to this API also carry a code:
Other errors carry no code. A date that isn’t YYYY-MM-DD returns 422 with a list of validation errors in detail. /v1/account/prices returns 404 on plans other than pay-as-you-go. A 502 means an upstream service didn’t answer; retry the request.

Full example

Prints your plan and key, your wallet if you have one, month-to-date spend by day and model, your keys, and your prices where they apply.