> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/api/run

# POST /v1/run

> Run a tool. Returns the result with its cost, 202 for a slow job, 428 with a quote when confirmation is needed, or an error with charged_paise 0.

```text
POST https://api.parel.si/v1/run
```

Scope `run`. Counts against the per-key rate limit (300 paid calls per minute by default).

## Request

| Header | Required | Value |
|---|---|---|
| `Authorization` | yes | `Bearer sk_…` (or `X-API-Key: sk_…`) |
| `Content-Type` | yes | `application/json` |
| `Idempotency-Key` | no | Same as `idempotency_key` in the body; the body wins when both are sent |

| Field | Type | Required | Description |
|---|---|---|---|
| `tool` | string, 1 to 64 characters | yes | A tool name from [`GET /v1/tools`](https://parel.si/docs/api/tools.md) |
| `input` | object | no (default `{}`) | The tool's input, validated against its schema before anything is held. `confirm: true` may ride inside it; it is stripped before validation and never sent to the source. |
| `idempotency_key` | string, 1 to 128 characters | no | Makes retries safe. Every outcome: [Conventions](https://parel.si/docs/api/conventions.md#idempotency). |
| `client_tag` | string, 1 to 64 characters | no | A label (a client's name) that attributes the spend in the dashboard's usage log |

```bash
curl https://api.parel.si/v1/run \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"search_web","input":{"q":"best crm for small business","country":"in","language":"en","limit":10},"idempotency_key":"docs-capture-search-web-1"}'
```

## Responses

What happens, in order: the request shape is checked (`invalid_request`), the tool looked up (`unknown_tool`, `tool_unavailable`, `paused`), the input validated (`invalid_input`), the idempotency key checked (replay, `in_progress`, mismatch, expired), the confirmation rule applied (`confirmation_required`), the hold placed (`insufficient_balance`, `budget_exceeded`), the source called, and the call settled. Everything before the source is called costs ₹0 and is logged as `class: "rejected"`.

### 200: a result

| Field | Type | Description |
|---|---|---|
| `ok` | `true` | |
| `call_id` | string | The call's id; also the `X-Call-Id` header |
| `tool` | string | The tool that ran |
| `class` | `"ok"`, `"ok_free"` or `"replay"` | Only `ok` is charged |
| `cost_paise` | integer | What was charged; `0` for `ok_free` and `replay` |
| `balance_paise` | integer | The balance after settlement (absent on a replay) |
| `data` | any | The source's answer, as it came. Over REST it is complete, whatever its size. |
| `note` | string | Only on `ok_free` with nothing found: `"No result found. This call was free."` |
| `replay_of` | string | Only on `class: "replay"`: the first call's id |

The shape of `data` is the tool's; each [tool page](https://parel.si/docs/tools.md) shows a recorded example. A successful `search_web` answer looks like this (fields from the tool's contract; the money fields are exactly what the API sends):

```json
{
  "ok": true,
  "call_id": "…",
  "tool": "search_web",
  "cost_paise": 14,
  "balance_paise": 9825,
  "class": "ok",
  "data": { "output": { "results": [ { "position": 1, "title": "…", "link": "https://…", "snippet": "…" } ] } }
}
```

> **Captured examples on this page.** Every response below was captured from staging on 2026-10-28 with a test key and trimmed. On that day the staging environment's connection to the data source was being re-keyed, so every paid call failed upstream (for ₹0, as designed) and no success body could be captured; the one above is the documented shape. The failure bodies are real.

### 202: a slow job started

Only for tools marked `async` (none of today's 59). The hold stays on the balance for up to 24 hours; poll [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md). The contract is on [Slow jobs](https://parel.si/docs/slow-jobs.md).

| Field | Type | Description |
|---|---|---|
| `ok` | `true` | |
| `call_id`, `tool` | string | |
| `status` | `"running"` | |
| `class` | `"running"` | |
| `poll_after_seconds` | integer | How long to wait before the first poll (the source's interval; 20 s when it gives none) |
| `reserved_paise` | integer | The hold kept open while the job runs |
| `message` | string | The same facts in a sentence |

### 428: confirmation needed

The estimate is above the confirmation threshold (₹200 by default) or the tool always needs confirmation. No call row, nothing held, ₹0. The body is the full [quote](https://parel.si/docs/api/quote.md) plus:

| Field | Type | Description |
|---|---|---|
| `ok` | `false` | |
| `error` | `"confirmation_required"` | |
| `confirmation_required` | `true` | |
| `estimate_paise`, `estimate`, `hold_paise`, `hold`, `balance_paise`, `enough_balance` | | As on a quote |
| `message` | string | "This call is estimated at about ₹… (hold ₹…). The user has not approved this cost yet. Nothing was charged. …" |
| `how_to_confirm` | string | "After the user approves the estimate, the same input with confirm: true runs the call." |

Resend the same body with `"confirm": true` inside `input`.

### 4xx and 5xx: a refusal or a failure

Always ₹0. The body carries `error`, `message`, `charged_paise: 0`, `retryable`, `request_id`, and `call_id` when a call row was recorded; after a source failure also `class`, `upstream_status` and a short `upstream_message`. Every code is on the [error table](https://parel.si/docs/errors.md). Captured from staging:

Invalid input, before the source was called (HTTP 400). `errors[]` names each path; here the one-of sets of `find_email`:

```json
{
  "ok": false,
  "call_id": "50c8ccdd-b498-4783-bc1e-b92a343ecadc",
  "error": "invalid_input",
  "message": "Input did not match the tool's schema.",
  "charged_paise": 0,
  "retryable": false,
  "errors": [
    {
      "path": "$",
      "message": "must include one of: domain+full_name | domain+first_name+last_name | company+full_name | company+first_name+last_name | linkedin_handle"
    }
  ],
  "request_id": "443f0ee4-0c0a-4c52-b48e-b388fa8f6598"
}
```

A request body of the wrong shape (HTTP 400; no call row, no `call_id`):

```json
{
  "ok": false,
  "error": "invalid_request",
  "issues": [
    {
      "expected": "string",
      "code": "invalid_type",
      "path": [
        "tool"
      ],
      "message": "Invalid input: expected string, received number"
    }
  ],
  "charged_paise": 0,
  "request_id": "c42d2e86-e064-4084-b7db-3290c91a6906"
}
```

A tool that does not exist or is switched off (HTTP 404):

```json
{
  "ok": false,
  "call_id": "1c86327f-68e3-4f7b-b843-bd889e46ac03",
  "error": "unknown_tool",
  "message": "No tool named \"nope\". Use discover to list tools.",
  "charged_paise": 0,
  "retryable": false,
  "request_id": "2e08f28e-0168-43fb-b160-feb6c19bb6c2"
}
```

The source failed (HTTP 502, `class: "upstream_error"`, `retryable: false` because the source refused rather than timed out). Nothing was charged; the hold was released in the same transaction:

```json
{
  "ok": false,
  "call_id": "ff83d554-fb75-4cf9-896a-bf53f91ea587",
  "tool": "search_web",
  "error": "upstream_error",
  "class": "upstream_error",
  "charged_paise": 0,
  "message": "The provider rejected this call. Nothing was charged.",
  "retryable": false,
  "upstream_status": 401,
  "upstream_message": "",
  "request_id": "e2ab626c-a886-42f6-924a-115ce37a5b5f"
}
```

Other refusals you will meet: [`insufficient_balance`](https://parel.si/docs/errors.md#insufficient_balance) (402, with `estimate_paise`, `balance_paise`, `topup_url` and `how_to_get_credit`), [`budget_exceeded`](https://parel.si/docs/errors.md#budget_exceeded) (429, with `cap`), [`rate_limited`](https://parel.si/docs/errors.md#rate_limited) (429, with `Retry-After`), [`in_progress`](https://parel.si/docs/errors.md#in_progress) (409), [`idempotency_key_mismatch`](https://parel.si/docs/errors.md#idempotency_key_mismatch) (422), [`replay_expired`](https://parel.si/docs/errors.md#replay_expired) (410), and after the source was called [`upstream_timeout`](https://parel.si/docs/errors.md#upstream_timeout), [`upstream_busy`](https://parel.si/docs/errors.md#upstream_busy), [`upstream_unavailable`](https://parel.si/docs/errors.md#upstream_unavailable) (502, retryable, sometimes with `retry_after_seconds`) and `vendor_<status>` (422, not retryable).

## Response headers

`X-Call-Id`, `X-Cost-Paise` (0 on every failure), `X-Balance-Paise` when known, `X-RateLimit-Limit` and `X-RateLimit-Remaining`, `X-Request-Id`. [Conventions](https://parel.si/docs/api/conventions.md#response-headers).

## Next

- [`POST /v1/quote`](https://parel.si/docs/api/quote.md): the same numbers before you spend.
- [`GET /v1/runs/:id`](https://parel.si/docs/api/runs.md): the record of any call; polling for slow jobs.
