Usage, history and billing
What the platform records about your runs and browsers, the usage window, the ledger and the monthly statement.
History
GET /v1/history merges Agent sessions and cloud browsers newest first: { "data": [entry], "next_before": "…" }. Filter with kind (all, agent, browser), status (a session's is its newest run's), q (a session's title, model or id, one of its runs' id or browser id, or a browser's id or profile — a substring, ≤ 200 characters), page with before (the ISO cursor from next_before) and limit (1–100, default 50).
An entry carries identity, outcome and cost only. A session: title, model, created_at, last_run_at; its newest run's status, error, judgment, browser_id, ended_at; runs, duration_ms (the runs' wall time summed, the active one to now) and token usage summed. A browser: status, timestamps, duration_ms, network mode, stop reason and proxy traffic. A session you deleted is not listed; its runs still count in Usage. Traces, events and frames stay behind their own routes.
Usage
GET /v1/usage?days=7 (1, 7, 30 or 90 whole days) returns totals and daily buckets per UTC day; add api_key_id=key_… for one key's share — every run and browser carries the api_key_id it was created with (null from the console):
| Total | Contents |
|---|---|
runs | Counts by outcome, plus timed and duration_ms for ended runs' wall time |
model | Requests and tokens |
browsers | Count, minutes, and how many are active |
network | Proxy bytes at the local bridge |
assets | Downloads, recordings and their bytes |
schedules, webhooks | Occurrences and deliveries |
Usage sums what the platform recorded.
Billing
Every run and browser is metered at its terminal state, whether or not a price applies: tokens (input, output, cache-read), model requests, agent runs, browser seconds and proxy bytes, each on the project it happened in and with a basis — whose resource it was: the platform's model key or proxy, or the project's own. Amounts are in USD, kept as integer micro-USD with a six-decimal string beside every integer.
Credit belongs to the account, not the project. A project's charges land on the account of its owner; one balance pays for every project that account owns, and transferring a project moves its future charges to the new owner. Credit is prepaid: a small credit on the account's first verified sign-in, and top-ups through the console's hosted checkout (the card never reaches the platform; the platform learns of the payment from the provider's signed webhook). A top-up is the signed-in account's own action — a project API key can read billing but never buy credit.
What is priced. A model unit costs the vendor's list price × (1 + the platform fee) on the platform's key, and the fee alone on your own key (the vendor billed you for the tokens; the agent is still the platform's work). Browser time and traffic through your own proxy are metered at no price. The public price list is [GET /v1/pricing](#the-public-price-list), derived from the same rate card that charges.
| Method and path | Result |
|---|---|
GET /v1/billing | The view from the project: account_id (its owner, whose credit pays for it), payer (whether you are that account), currency, enforced, month; the account's balance_*, lifetime_paid_* (top-ups only) and concurrency ({ ceiling, running }); the project's month_charges_* and monthly_budget_*; model_fee_percent; top_up ({ available, min_micro_usd, min_usd }) |
PATCH /v1/billing | { "monthly_budget_usd": 25 } or null; owner or admin |
POST /v1/billing/top-ups | Console session only: { "amount_usd": 20 } → { id, url }, the checkout to follow. A key gets 403 permission_denied; a platform without a checkout, 503 provider_unavailable |
GET /v1/billing/ledger?limit=100 | Entries newest first: the account's credits (grant, adjustment, top_up, signup) and this project's charges, each with fee_percent, basis and the meter (unit, quantity, model, basis, source) behind it |
GET /v1/billing/statement?month=2026-09 | The project's month per unit, model and basis: quantity, usd_per_million (the list price; null while unpriced), fee_percent, fee_micro_usd, amounts; total_*, fee_* (what the platform kept of the model charges), credited_* |
GET /v1/billing/rates | The rate card as it stands: list prices, per unit, model and basis |
account = client.billing.get()print(account["balance_usd"], account["lifetime_paid_usd"], account["concurrency"])statement = client.billing.statement("2026-09")for line in statement["lines"]: print(line["unit"], line["model"], line["basis"], line["quantity"], line["amount_usd"])print("fee kept by the platform:", statement["fee_usd"])const account = await client.billing.get();console.log(account.balance_usd, account.lifetime_paid_usd, account.concurrency);const statement = await client.billing.statement({ month: '2026-09' });for (const line of statement.lines) console.log(line.unit, line.model, line.basis, line.quantity, line.amount_usd);console.log('fee kept by the platform:', statement.fee_usd);Limits on spending
max_spend_usdon a run stops it withspend_limitonce its priced usage (with the fee) passes the cap.- Three gates on new work when the deployment enforces billing; reads and running work are never refused:
402 insufficient_balance— the owner account's balance is zero or below. Add credit.402 budget_exceeded— the project's monthly budget is reached. Raise it, or wait for the next month.429 concurrency_exceeded— the owner account's projects already run as many browsers as its ceiling allows. Stop one, or raise the ceiling: it follows the account's lifetime paid credit (free credit does not count) and never goes down.
The public price list
GET /v1/pricing needs no session: model_fee_percent, signup_grant_usd, min_top_up_usd, the concurrency_ladder ([{ paid_usd, browsers }]), models (per model: input_usd_per_million, cached_input_usd_per_million, output_usd_per_million, the fee included) and units (browser_hour_usd, proxy_gb_usd.platform / .own, null while free or unpriced). It is computed from the platform's configuration and rate card, so it cannot disagree with a statement.