Slow jobs
Tools that take minutes answer 202 and are polled to completion. The contract, the intervals, the reserve, and what an agent should do. None of today's 268 tools is slow.
Which tools
A tool marked async: true in POST /v1/discover is a slow job. None of the 268 tools in the beta is. Deep research, when it is switched on, will be, and will also require confirm: true on every call because a report can cost hundreds of rupees. Its description will say both.
The contract
- Start.
POST /v1/runanswers HTTP 202 withclass: "running",status: "running",poll_after_secondsandreserved_paise. The hold is placed as for any call and extended to 24 hours. The source may already have charged a reserve at the start; it is on our books from that moment, so an abandoned job is never an invisible loss on your side. - Poll. Read
GET /v1/runs/:id(or the MCP toolget_run) afterpoll_after_seconds. While the job runs the read answers 202 with the source's own progress word instatus,poll_after_secondsagain and aRetry-Afterheader. Polling sooner than the interval returns the same state without asking the source again. - Finish. The read that sees the job complete answers 200 with
class: "ok",cost_paise(the real cost, settled against the hold; if it comes to more than the hold, the extra is taken only when the balance covers it),balance_paiseanddata(the output and its sources when the source gives them; never the source's internal trace). Later reads return the finished record withoutdata. - Failure. The read that sees the job fail answers 422 with
class: "vendor_error",error,charged_paise: 0. The hold is released; if the source kept its reserve, that is Parel's loss, not yours.
A poll that itself fails (the source answered 5xx or timed out while being asked) does not end the job; the next read tries again after at least 30 seconds. A job with no terminal answer after 24 hours is expired by housekeeping, its hold released, nothing charged.
What an agent should do
- Quote first:
quote_toolsaysasync: trueand the estimate; tell the user the cost and get a yes beforeconfirm: true. - After the 202, tell the user the job is running and how long the source expects; then call
get_runwith thecall_idat the interval, not faster. - Report
cost_paisefrom the final read, notreserved_paisefrom the start. - If the user cancels: there is no stop call today. Stop polling; the hold is released when the job ends or expires, and a job that fails is ₹0.
Idempotency and slow jobs
A slow job started with an idempotency_key replays its final data for ₹0 for 24 hours after it finishes, like any other call. While it runs, the same key answers in_progress with the call_id to poll.
This page as Markdown: /docs/slow-jobs.md. Something wrong or missing: hello@parel.si.