Martini Billing API

A key holds a set of family:level permissions, chosen when it is created and never widened; write implies read. The Billing API is its own family: billing:read reads the reporting routes (account, price list, costs, ledger, invoices, budgets), billing:write additionally sets budgets. The balance needs neither — it answers any valid key — so a Runtime key (generations:write, workflows:write, assets:write) reads it and nothing else on this page.

A Finance read-only key holds billing:read alone: it reads spend and cannot generate, run a workflow, or upload, so it is the key to hand a dashboard, a warehouse loader, or a finance tool. A call the key may not make answers 403 API_KEY_PERMISSION_MISSING with the required permission, the granted set, and the settingsUrl where a key with it is created; GET /v1/me lists key.permissions so a client can check before its first call.

Each key may make 120 requests per sliding minute across /v1/billing, the balance included. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (Unix seconds by which the window has fully turned over); a request past the allowance answers 429 RATE_LIMITED with Retry-After. A warehouse sync that pages the ledger at 1000 rows a page stays well inside it; a dashboard that polls the balance every second does too.

What an organization key or an account key gets.

With billing disabled:

To check a batch, compare olives.available against your estimate (a run's olives.budget, or the model's price from the price list times the count). unlimited: true or billingEnabled: false covers any batch.

What a workflow run key gets. An agent executing inside a run can plan against its own budget, and learns whether the organization stands behind it, without the organization's balance ever landing in a run log. The same read answers covered; the numbers stay on the server.

The balance is read from the billing system and cached for 10 seconds per organization, so a launcher polling every second costs one read; asOf is the read time, so a poller can see the age. When the billing system cannot be reached and no fresh value is cached, the route answers 503 BALANCE_UNAVAILABLE with Retry-After: 10. A value past its cache window is discarded, not served with a flag: a stale number is never presented as current.

Enforcement happens at charge time, not here. A balance that covers a batch when you read it does not reserve anything; a generation submitted in between spends from the same pool. Submit soon after checking, or set an oliveBudget on each run so the total is bounded either way.

The MCP tool get_balance answers the same question with the same shape for an agent working through the MCP connector or the CLI. It takes an optional organizationId, or a projectId to read the organization that pays for that project; omitted, it reads the organization the key or session acts for. Inside a workflow run it returns the run form regardless of arguments — the same fence as the route. It is reachable as POST /v1/tools/get_balance with a key like every other tool, and as martini get_balance from the CLI.

A card is everything needed to price a request before it is submitted. Start from the tier the request lands in (or olivesPerUnit when there is none), apply the quality and aspect factors, add the surcharges, and respect minimumOlives where the card carries one. The card reads the way the charge does: a tier’s own figure wins over the card’s, and a figure the charge never applies to a model is not on its card. Members a model does not use are absent, not null.

agentWork is what the organization pays for the work an agent does on its behalf: chat models by the id and name the picker shows, the sandbox, and tools such as transcription. Rates are olives per million units of each bucket the resource is metered in — the finished price, with nothing of its terms.

A list parameter repeats (types=generation&types=export), takes a [] suffix, or joins with commas; at most 50 distinct values each. Filters narrow the rows before they are bucketed, so a group that has no rows in a bucket is absent from that bucket, an empty bucket holds an empty results, and the cells of a bucket are sorted by netOlives, largest first.

Pages run over buckets, oldest first: limit buckets per page and nextCursor naming the next, null on the last. A page is computed from the ledger rows it covers; one that covers too many answers 400 INVALID_QUERY — lower limit or narrow the range. A cursor belongs to its filters: change a filter and start again without one, or the server answers 400 INVALID_CURSOR.

Every budget of the organization with where it stands, the organization-wide one first. GET /v1/billing/budgets/{budgetId} reads one; an id that is not one of the organization's budgets answers 404 BUDGET_NOT_FOUND.

status is read from the same figures the admission uses, so the number a charge is refused on is the number reported here. The second budget above is spent: blocked is true, and the Finance key's next generation is refused until the limit is raised.

Set a budget. scope is { "type": "organization" } or { "type": "project" | "member" | "apiKey", "id": "<uuid>" } — the project id, the member's user id, or the key id. One budget per scope: a second answers 409 BUDGET_EXISTS; change the existing one instead. A scope that is not the organization's (a project of another workspace, a user who is not a member, a revoked key) answers 404 BUDGET_SCOPE_NOT_FOUND. alerts are optional, at most 10, each atOlives distinct and at most amountOlives; a body that does not fit answers 400 BUDGET_INVALID naming the field. The answer is 201 with the budget as it stands now.

PATCH /v1/billing/budgets/{budgetId} raises or lowers amountOlives, replaces alerts, or both; name at least one. The scope and the period are fixed — delete and create again to change them. A new limit re-arms the period's alerts, so a threshold already reached notifies again once spend reaches it under the new limit. DELETE /v1/billing/budgets/{budgetId} removes the budget: the scope is no longer capped, its alerts no longer fire, and spend already recorded against it stays in the ledger. It answers { "id": "…", "deleted": true }.

A charge a budget refuses is answered 402 before any work starts, and nothing is charged. On POST /v1/generations the code is SPEND_CAP_EXCEEDED — the Generation API's one code for every cap — and the message names the scope and its limit:

Martini's own surfaces (the app's generate, chat, uploads, and set creation) answer BUDGET_EXCEEDED for an organization or key budget, with budget naming the one that refused; a project or member budget keeps the codes the app has always shown (PROJECT_SPEND_CAP_EXCEEDED, MEMBER_CAP_EXCEEDED) with the same budget detail.

Either way, GET /v1/billing/budgets shows which budget is blocked. Agent work inside a workflow run is admitted the same way, operation by operation, against the organization, project, and member budgets. Alerts never block: an alerts threshold emails the organization's admins once per period when settled spend reaches it, and the limit itself is what refuses.