Long-running requests
A Marvin turn often takes a minute or more, and some research tools take several. The API keeps such requests alive itself, but your client needs a long enough timeout.
Responses: wait, or run in the background
Section titled “Responses: wait, or run in the background”POST /v1/responses is synchronous by default: the request stays open until the turn finishes, and the body is the completed response.
- Keep-alive whitespace. While the turn runs, the API sends a space every 20 seconds, so proxies and load balancers do not close an idle connection. JSON allows leading whitespace, so standard parsers read the body as usual. If you parse by hand, trim leading whitespace first.
- The 60-minute limit. A turn still running after 60 minutes is answered with its current state,
status: "in_progress". PollGET /v1/responses/{id}for the rest. - Client timeouts. Set your HTTP client’s read timeout to at least an hour for synchronous calls, or use background mode.
- Disconnecting does not stop the turn. If your connection drops, the turn carries on. Its result is still available from
GET /v1/responses/{id}.
For anything interactive, prefer background mode: send background: true, get status: "queued" back at once, then poll GET /v1/responses/{id} every few seconds until the status is completed, failed or cancelled. The Quickstart has an example.
A response’s status is one of:
status |
Meaning |
|---|---|
queued |
Accepted, not started yet. It may be waiting behind another turn in the same conversation |
in_progress |
Running |
completed |
Finished. The answer is in output_text |
failed |
The turn failed. error says why |
cancelled |
Cancelled before it finished |
Cancelling
Section titled “Cancelling”POST /v1/responses/{id}/cancel stops a running response. The call waits up to 15 seconds for the turn to stop, so it usually returns cancelled. A turn that is slow to stop can still read in_progress: poll it until it settles. A response still queued behind another turn is not removed by a cancel.
Research tools: keep-alive, and errors in a 200
Section titled “Research tools: keep-alive, and errors in a 200”The /v1/tools endpoints answer directly when they finish within 20 seconds, with the usual status codes.
A call still running after 20 seconds is answered 200 straight away, and the API then sends a space every 20 seconds until the tool is done. Because the status has already been sent, an error after that point arrives in a 200 body as the usual error envelope:
{"error": {"type": "api_error", "code": "upstream_unavailable", "message": "...", "request_id": "req_..."}}Treat a body whose only key is error as the error it describes, whatever the status code.
Each tool has a time limit, after which it answers 504:
| Endpoint | Limit |
|---|---|
POST /v1/tools/documents/explore |
240 s |
POST /v1/tools/financials/statements |
120 s |
POST /v1/tools/financials/query |
600 s |
Set your client’s read timeout above the longest limit you call, for example 11 minutes for financials/query.