Credits
The API draws on the same credit allowance as your use of the Marvin app. A call that makes Marvin do AI work books credits to your account. A call that only reads what already exists is free.
What uses credits
Section titled “What uses credits”| Endpoint | Credits |
|---|---|
POST /v1/responses |
Yes, like a chat turn in the app |
POST /v1/tools/documents/search |
Yes |
POST /v1/tools/documents/explore |
Yes |
POST /v1/tools/financials/query |
Yes |
POST /v1/tools/documents/list, /read |
No |
POST /v1/tools/financials/statements, /provenance |
No |
GET /v1/responses/..., POST /v1/responses/{id}/cancel |
No |
/v1/conversations, /v1/agent_results |
No |
What a call costs depends on the work it does, such as a turn’s length and the number of documents explored, so it is not a fixed price per call. Responses carry usage: null: the API bills in credits, not tokens.
When credits run out
Section titled “When credits run out”A call that would use credits is refused with 429 and the code insufficient_credits once your allowance is used up. Free calls keep working.
POST /v1/responseschecks your credits before the turn is queued, so a refused turn never starts.- When the allowance resets at the end of a window,
Retry-Aftergives the seconds until then. It is absent when no reset is coming, for example once a one-time free allowance is used.
You can see your credit use and upgrade your plan in the Marvin app.