Skip to content

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.

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/pricing

A 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.

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/responses returns 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 usage reports 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.

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/responses it 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_usd is 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.

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/responses checks 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.