> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/slow-jobs

# 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`](https://parel.si/docs/api/discover.md) 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

1. **Start.** [`POST /v1/run`](https://parel.si/docs/api/run.md#running) answers HTTP 202 with `class: "running"`, `status: "running"`, `poll_after_seconds` and `reserved_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.
2. **Poll.** Read [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md#polling) (or the MCP tool `get_run`) after `poll_after_seconds`. While the job runs the read answers 202 with the source's own progress word in `status`, `poll_after_seconds` again and a `Retry-After` header. Polling sooner than the interval returns the same state without asking the source again.
3. **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](https://parel.si/docs/how-it-works.md#if-a-source-bills-more-than-expected), the extra is taken only when the balance covers it), `balance_paise` and `data` (the output and its sources when the source gives them; never the source's internal trace). Later reads return the finished record without `data`.
4. **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_tool` says `async: true` and the estimate; tell the user the cost and get a yes before `confirm: true`.
- After the 202, tell the user the job is running and how long the source expects; then call `get_run` with the `call_id` at the interval, not faster.
- Report `cost_paise` from the final read, not `reserved_paise` from 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`](https://parel.si/docs/errors.md#in_progress) with the `call_id` to poll.
