Pricing and usage
The API draws on the same dollar wallet as your organisation’s use of the Marvin app and of Marvin over MCP. Calls that make Marvin search or think are billed to it; calls that only read what already exists are free. Failed calls are never billed.
Prices
Section titled “Prices”| What | Price |
|---|---|
Financial search and document search or exploration (/v1/tools/financials/query, /v1/tools/documents/search, /v1/tools/documents/explore) |
$0.03 per successful call |
AI work in a turn (POST /v1/responses) |
$3 per 1M input tokens, $0.30 per 1M cached input tokens, $15 per 1M output tokens (thinking included). One rate for every model |
| Searches and explorations Marvin makes during a turn | $0.03 each, the same as calling the tool yourself |
Economic data searches and retrieval (search_series, get_series_data), launching shortly |
$0.03 per successful call |
Everything else: /v1/tools/documents/list and /read, /v1/tools/financials/statements and /provenance, reading responses and conversations, /v1/agent_results |
Free |
The live price list is at GET /v1/pricing. It needs no API key:
curl -s https://app-api.marvin-labs.com/v1/pricingA search that runs and finds nothing is still a successful call and is billed. A call that fails and a tool that times out are not billed. A turn that fails or is cancelled is not billed for its own AI work, but what it finished before it stopped is: each successful search and exploration, and any research it delegated that completed.
Retrying without paying twice
Section titled “Retrying without paying twice”Send an Idempotency-Key header (any unique string of up to 255 characters, such as a UUID) on POST /v1/responses and on the billed research tools. If the connection drops before you get the answer, send the same request with the same key:
POST /v1/responsesreturns the response the first request started instead of asking again. A synchronous retry waits for that turn to finish, like the first request.- A research tool may run the lookup again, but the call is billed once. Its
usagereports the one charge.
A key is yours alone and lasts 24 hours; after that the same key is a new request. Reusing a key with a different body is refused with 422 validation_error.
What a call cost
Section titled “What a call cost”Billable responses carry a usage object: what the call was billed and your organisation’s balance after it.
"usage": { "cost_usd": 0.78, "balance_usd": 182.4, "retrieval_calls": 7, "retrieval_usd": 0.21, "input_tokens": 92000, "cached_input_tokens": 220000, "output_tokens": 15000, "llm_usd": 0.57}- On
/v1/responsesit covers the whole turn, including the research Marvin delegated, and grows while the turn runs. - On the research tools it covers that one call.
balance_usdis your organisation’s wallet after the call, its own charges included. It can be slightly negative: a call that starts with credit left always finishes, and a small overspend comes off your next credit.
GET /v1/usage returns your organisation’s spend per day, grouped by line (retrieval, llm, upload), member, key, surface (app, api, mcp) or component: what the spend bought, one row per token kind, search tool and uploaded pages, with its quantity and unit. It defaults to the last 30 days; pass start, end and group_by to change that.
When the wallet is empty
Section titled “When the wallet is empty”A billable call is refused with 402 and the code insufficient_credits once your organisation’s balance is at or below zero. Free calls keep working. The error carries the balance and where to add credit:
{"error": {"type": "billing_error", "code": "insufficient_credits", "message": "...", "balance_usd": -0.12, "topup_url": "https://app.marvin-labs.com/billing/", "request_id": "req_..."}}POST /v1/responseschecks the wallet before the turn is queued, so a refused turn never starts.- Nothing resets on its own: an admin of your organisation adds credit with a top-up (from $10, never expires), turns on auto-recharge, or changes the plan in the Marvin app. Plans grant monthly credit: $100 a month on Standard ($89 a month, or $890 a year), $500 a month on Pro ($399 a month, or $3,990 a year). Annual billing still grants the credit one month at a time.