Billing API

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.

Method	Path	Returns
`GET`	`/v1/account`	Team, plan, models and the calling key; on pay-as-you-go, also the wallet
`GET`	`/v1/account/keys`	Your team’s API keys, metadata only
`GET`	`/v1/account/spend`	Spend, requests and tokens in daily buckets
`GET`	`/v1/account/prices`	Per-token prices for your models (pay-as-you-go only)

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.

-H "Authorization: Bearer $IMPALA_API_KEY"

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/keys and /v1/account/spend work the same on every plan.

Endpoints

Values in the response examples are illustrative.

Get account

GET /v1/account Returns your team, billing plan, the models on your team and the key that made the call. On pay-as-you-go, it also returns wallet.

curl https://api.platform.getimpala.ai/v1/account \
  -H "Authorization: Bearer $IMPALA_API_KEY"

{
  "customer_id": "acme-research",
  "team_alias": "acme-research",
  "billing_plan": "pay_as_you_go",
  "models": ["glm-5.2", "kimi-k3"],
  "key": {
    "id": "7faeb355f584484a0e051892a69b58290ac927f8d0b858539564ae196ff9f2e0",
    "alias": "prod-batch",
    "masked": "sk-...4f2a",
    "spend_usd": 412.37,
    "max_budget_usd": 500.0,
    "budget_remaining_usd": 87.63,
    "blocked": false,
    "created_at": "2026-08-02T09:14:00.212000+00:00",
    "is_caller": true
  },
  "wallet": {
    "currency": "usd",
    "balance_cents": 67945,
    "funded_cents": 250000,
    "deposited_cents": 250000,
    "adjustments_cents": 0,
    "spent_cents": 182055,
    "overdraft_cents": 0,
    "floor_cents": 0,
    "blocked": false,
    "spend_as_of": 1791727200
  }
}

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.

string[]

The model names on your team. These are the names the spend report and price list use.

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.

Show properties

string

Always usd.

integer

funded_cents minus spent_cents. Can be negative.

integer

deposited_cents plus adjustments_cents.

integer

Top-ups and credit grants.

integer

Refunds and corrections, either sign.

integer

Usage charged to the wallet since you enrolled. Lags the last request by about a minute.

integer

How far below zero the balance may go.

integer

Minus overdraft_cents. Inference requests are refused once balance_cents drops below it.

boolean

true while nothing has been funded (funded_cents is 0 or less). A funded wallet that runs past the floor still reads false, so compare balance_cents with floor_cents to tell whether requests are being refused.

integer

When spent_cents was read, as Unix seconds.

List keys

GET /v1/account/keys Returns your team’s API keys. Only metadata is returned, never the key itself.

curl https://api.platform.getimpala.ai/v1/account/keys \
  -H "Authorization: Bearer $IMPALA_API_KEY"

{
  "keys": [
    {
      "id": "7faeb355f584484a0e051892a69b58290ac927f8d0b858539564ae196ff9f2e0",
      "alias": "prod-batch",
      "masked": "sk-...4f2a",
      "spend_usd": 412.37,
      "max_budget_usd": 500.0,
      "budget_remaining_usd": 87.63,
      "blocked": false,
      "created_at": "2026-08-02T09:14:00.212000+00:00",
      "is_caller": true
    },
    {
      "id": "9977ac6a31d4bbd6981498c00796240500012473ae7299425ec69d0b05a43698",
      "alias": "staging",
      "masked": "sk-...91bc",
      "spend_usd": 38.05,
      "max_budget_usd": null,
      "budget_remaining_usd": null,
      "blocked": false,
      "created_at": "2026-09-14T16:02:41.508000+00:00",
      "is_caller": false
    }
  ],
  "count": 2
}

object[]

Show properties

string

An opaque ID for the key. This is the value api_key_ids takes on /v1/account/spend.

string | null

The key’s name.

string | null

The key with most characters hidden.

number

Spend metered on this key, in USD.

number | null

This key’s own spending cap in USD, separate from your wallet. null if the key has no cap.

number | null

max_budget_usd minus spend_usd. null if the key has no cap.

boolean

Whether the key is blocked.

string | null

When the key was created, as an ISO 8601 timestamp.

boolean

true for the key that made this request.

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.

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 names from models on /v1/account. A name that isn’t on your team matches nothing.

curl "https://api.platform.getimpala.ai/v1/account/spend?start=2026-10-01&end=2026-10-01&group_by=model,api_key" \
  -H "Authorization: Bearer $IMPALA_API_KEY"

{
  "start": "2026-10-01",
  "end": "2026-10-01",
  "bucket_width": "1d",
  "currency": "usd",
  "group_by": ["model", "api_key"],
  "totals": {
    "spend_usd": 13.9024,
    "prompt_tokens": 41323993,
    "completion_tokens": 3778884,
    "cache_read_input_tokens": 29292113,
    "total_tokens": 45102877,
    "requests": 6950,
    "successful_requests": 6946,
    "failed_requests": 4
  },
  "buckets": [
    {
      "start": "2026-10-01",
      "end": "2026-10-02",
      "totals": {
        "spend_usd": 13.9024,
        "prompt_tokens": 41323993,
        "completion_tokens": 3778884,
        "cache_read_input_tokens": 29292113,
        "total_tokens": 45102877,
        "requests": 6950,
        "successful_requests": 6946,
        "failed_requests": 4
      },
      "results": [
        {
          "spend_usd": 11.2051,
          "prompt_tokens": 30120442,
          "completion_tokens": 2914330,
          "cache_read_input_tokens": 21880104,
          "total_tokens": 33034772,
          "requests": 5402,
          "successful_requests": 5398,
          "failed_requests": 4,
          "model": "glm-5.2",
          "api_key_id": "7faeb355f584484a0e051892a69b58290ac927f8d0b858539564ae196ff9f2e0",
          "api_key_alias": "prod-batch"
        },
        {
          "spend_usd": 2.6973,
          "prompt_tokens": 11203551,
          "completion_tokens": 864554,
          "cache_read_input_tokens": 7412009,
          "total_tokens": 12068105,
          "requests": 1548,
          "successful_requests": 1548,
          "failed_requests": 0,
          "model": "kimi-k3",
          "api_key_id": "9977ac6a31d4bbd6981498c00796240500012473ae7299425ec69d0b05a43698",
          "api_key_alias": "staging"
        }
      ]
    }
  ]
}

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.

Show properties

number

Spend in USD, unrounded, so rows add up to totals exactly.

integer

Input tokens.

integer

Output tokens.

integer

Input tokens served from cache. Included in prompt_tokens.

integer

Input plus output tokens.

integer

All requests.

integer

Requests that succeeded.

integer

Requests that failed.

object[]

One entry per UTC day with usage. Days with no usage are left out rather than reported as zeros.

Show properties

string

The day.

string

The next day (exclusive).

object

The day’s totals, with the same fields as the report’s totals.

object[]

One row per group, with the same metrics as totals plus model, api_key_id and api_key_alias. A dimension you didn’t group by is null. api_key_alias is also null for a key with no alias or a deleted key, so fall back to api_key_id. Usage that doesn’t map to a model on your team is reported as (other).

On pay-as-you-go, the wallet charges usage from the day you enrolled, so a window that starts before then reports usage your wallet’s spent_cents doesn’t include. On other plans, your invoice is the reference for what you owe.

Get prices

GET /v1/account/prices Returns the per-token prices for the models on your team, in USD per 1M tokens. Pay-as-you-go only; other plans get a 404.

curl https://api.platform.getimpala.ai/v1/account/prices \
  -H "Authorization: Bearer $IMPALA_API_KEY"

{
  "currency": "usd",
  "models": [
    {
      "model": "glm-5.2",
      "input_price_per_1m": 0.4,
      "cached_input_price_per_1m": 0.038,
      "output_price_per_1m": 1.6
    },
    {
      "model": "kimi-k3",
      "input_price_per_1m": 0.6,
      "cached_input_price_per_1m": null,
      "output_price_per_1m": 2.5
    }
  ]
}

string

Always usd.

object[]

One row per model on your team.

Show properties

string

The model name.

number | null

Price per 1M input tokens.

number | null

Price per 1M input tokens served from cache.

number | null

Price per 1M output tokens.

null means no price is set for that side. Prices never read 0.

Errors

Errors return JSON with a detail message. Errors specific to this API also carry a code:

{
  "detail": "window is 412 days; the maximum is 400",
  "code": "window_too_large"
}

Status	`code`	Meaning
`401`	`invalid_api_key`	The key is missing, unknown, blocked or expired.
`409`	`key_has_no_team`	The key isn’t attached to a team. Contact Impala to attach it.
`422`	`invalid_window`	`end` is before `start`.
`422`	`window_too_large`	The window is longer than 400 days.
`422`	`invalid_group_by`	`group_by` has a value other than `model` or `api_key`.
`422`	`unknown_api_key_ids`	`api_key_ids` includes an ID that isn’t a current key on your team. The body lists the offending IDs in `api_key_ids`.

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, model and key, your keys, and your prices where they apply.

import os

import requests

BASE = "https://api.platform.getimpala.ai"
API_KEY = os.environ["IMPALA_API_KEY"]  # your inference key

s = requests.Session()
s.headers["Authorization"] = f"Bearer {API_KEY}"


def get(path, **params):
    r = s.get(f"{BASE}{path}", params=params, timeout=30)
    if r.status_code == 404:
        return None  # prices are pay-as-you-go only
    r.raise_for_status()
    return r.json()


# Account: plan, models, your key, and (pay-as-you-go) wallet
acct = get("/v1/account")
print(f"team: {acct['team_alias']} ({acct['customer_id']})   plan: {acct['billing_plan']}")
print(f"models: {', '.join(acct['models'])}")
k = acct["key"]
print(f"this key: {k['alias']} {k['masked']}   spent ${k['spend_usd']:.2f}")
if "wallet" in acct:
    w = acct["wallet"]
    print(f"wallet: funded ${w['funded_cents']/100:.2f}  spent ${w['spent_cents']/100:.2f}  balance ${w['balance_cents']/100:.2f}")

# Spend report: one bucket per UTC day, grouped by model and key (defaults to month-to-date)
report = get("/v1/account/spend", group_by="model,api_key")
t = report["totals"]
print(f"\n{report['start']} → {report['end']}: ${t['spend_usd']:.4f}  {t['requests']} requests  {t['total_tokens']:,} tokens")
for day in report["buckets"]:
    print(f"  {day['start']}  ${day['totals']['spend_usd']:.4f}")
    for row in day["results"]:
        key = row["api_key_alias"] or row["api_key_id"][:12]
        print(f"      {row['model']:<14} {key:<16} ${row['spend_usd']:.4f}  {row['requests']} req")

# Your keys (metadata only) and your per-token prices (USD per 1M tokens)
print("\nkeys:")
for key in get("/v1/account/keys")["keys"]:
    print(f"  {key['alias'] or key['id'][:12]:<16} ${key['spend_usd']:.2f}")
prices = get("/v1/account/prices")
if prices is None:
    print("prices: not applicable on this plan")
else:
    print("prices:")
    for p in prices["models"]:
        print(f"  {p['model']:<14} in {p['input_price_per_1m']}  cached {p['cached_input_price_per_1m']}  out {p['output_price_per_1m']}")

Introduction

Serverless inference

Batch inference

Agent orchestration

Optimization

Bring your own model

Bring your own cloud (BYOC)

Integrations

Reference

API reference

Authentication

Plan differences

Endpoints

Get account

List keys

Get spend

Get prices

Errors

Full example

​Authentication

​Plan differences

​Endpoints

​Get account

​List keys

​Get spend

​Get prices

​Errors

​Full example

Authentication

Plan differences

Endpoints

Get account

List keys

Get spend

Get prices

Errors

Full example