Balance and usage

Amounts are in USD, the currency the ledger charges in. Every amount carries a decimal amount and the exact integer amount_micro_usd, so you never have to trust a rounding.

What a call costs

The price in a source detail is the buyer total for that operation. There is no separate charge to add to that quoted total. The sum of usage.sources[].cost equals usage.cost for every run.

How money moves

Approve. The plan’s maximum cost is checked against the key’s per-request limit, its monthly limit and the organisation’s balance.
Reserve. Before a source is called, its cost is reserved on the balance.
Run. The source is called.
Settle. The actual cost is charged and the remainder released.

A call that fails is refunded. A call whose outcome is unknown stays held until it is reconciled, and is never charged twice. Because the reservation happens before the provider is called, a balance can never go negative.

Balance

GET /v2/balance

Requires billing:read.

{
  "organisation_id": "0d2a…",
  "balance": { "available": { "amount": 47.82, "amount_micro_usd": "47820000", "currency": "USD" } },
  "key": { "id": "8c41…", "name": "Nomi Production", "scopes": ["sources:read"], "expires_at": "2027-09-22T16:41:08Z" },
  "limits": {
    "per_request": { "amount": 2, "amount_micro_usd": "2000000", "currency": "USD" },
    "monthly": { "amount": 100, "amount_micro_usd": "100000000", "currency": "USD" },
    "month_spent": { "amount": 0.54, "amount_micro_usd": "540000", "currency": "USD" },
    "month_remaining": { "amount": 99.46, "amount_micro_usd": "99460000", "currency": "USD" },
    "month_start": "2026-09-01T00:00:00Z"
  }
}

The balance is the organisation’s and is shared by all of its keys. The limits are this key’s alone.

Usage

GET /v2/usage?limit=50

Requires billing:read. Returns what this key spent this month and its most recent charges, newest first.

Query parameter	Type	Default	Meaning
`limit`	integer 1–200	50	How many charges to return

{
  "key_id": "8c41…",
  "organisation_id": "0d2a…",
  "month_start": "2026-09-01T00:00:00Z",
  "month_spent": { "amount": 0.54, "amount_micro_usd": "540000", "currency": "USD" },
  "charges": [
    {
      "id": "c19f…",
      "status": "charged",
      "cost": { "amount": 0.023, "amount_micro_usd": "23000", "currency": "USD" },
      "created_at": "2026-09-22T16:58:11Z",
      "source_id": "kvk-dutch-business-register",
      "operation": "company_registry.search",
      "name": "Company search",
      "run_id": "6f0b…"
    }
  ]
}

string

charged is settled money. reserved is held for a call in flight. refunded was given back and counts against nothing.

string

The run that produced the charge; read it back with GET /v2/runs/{id}.

Topping up

Balances are funded in the app, under Organisation → Billing. An organisation’s main balance is separate from any workspace budget: API keys spend the main balance only.

Status	Code	Meaning
200	—	The balance or usage
401	`invalid_api_key`	See Authentication
403	`insufficient_scope`	The key lacks `billing:read`
403	`api_key_required`	`GET /v2/usage` is per key; people read usage in the app

Buy data

Use cases

Operating it

API Reference

Ask

Balance and usage

What a call costs

How money moves

Balance

Usage

Topping up

​What a call costs

​How money moves

​Balance

​Usage

​Topping up

What a call costs

How money moves

Balance

Usage

Topping up