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

# POST /v1/quote

> The estimated charge and the hold for an input before running it, with the same validation, price table and formulas as the real call. Free; nothing is recorded or held.

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

Scope `read`. Free. Does not count against the paid-call rate limit.

## Request

| Field | Type | Required | Description |
|---|---|---|---|
| `tool` | string | yes | A tool name |
| `input` | object | no (default `{}`) | The exact input you intend to send. It is validated against the tool's schema first. |

```bash
curl https://api.parel.si/v1/quote \
  -H "Authorization: Bearer $PAREL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"find_email","input":{"domain":"zomato.com","full_name":"Jane Example"}}'
```

## Response

### 200: the quote

| Field | Type | Description |
|---|---|---|
| `ok` | `true` | |
| `tool` | string | |
| `quote` | `true` | Marks this as a quote, not a run |
| `charged_paise` | `0` | Nothing was charged for the quote |
| `estimate_paise`, `estimate` | integer, string | The likely charge for this input at today's rate |
| `hold_paise`, `hold` | integer, string | What would be held before the call. The charge is normally the estimate, and the rest is released. See [if a source bills more than expected](https://parel.si/docs/how-it-works.md#if-a-source-bills-more-than-expected). |
| `per_result_paise` | integer | Only for per-result tools: the price of one result |
| `count_field`, `count` | string, integer or null | Only for per-result tools: the input field the estimate was priced on, and the value found in the input |
| `mode` | string | Only for mode-priced tools: the mode the estimate used |
| `confirm_required` | boolean | Whether running this input would answer `confirmation_required` |
| `free_when_no_result` | boolean | Whether an empty answer is ₹0 for this tool |
| `async` | boolean | Whether the tool is a slow job |
| `balance_paise` | integer | Your balance now |
| `enough_balance` | boolean | `balance_paise >= hold_paise` |
| `topup_url` | string | Only when the balance is not enough |
| `note` | string | The rule in a sentence |

Captured from staging:

```json
{
  "ok": true,
  "tool": "find_email",
  "quote": true,
  "charged_paise": 0,
  "estimate_paise": 280,
  "estimate": "₹2.80",
  "hold_paise": 420,
  "hold": "₹4.20",
  "confirm_required": false,
  "free_when_no_result": true,
  "async": false,
  "balance_paise": 9850,
  "enough_balance": true,
  "note": "Estimate at today's rate: what this call normally costs. A failed call costs nothing. The real charge follows what the source bills; if that is more than the hold, the extra is taken only when your balance covers it, and a balance never goes below zero. Nothing was charged for this quote."
}
```

### 400 and 404

The same `invalid_input` (with `errors[]`) and `unknown_tool` refusals as [`POST /v1/run`](https://parel.si/docs/api/run.md#errors), ₹0. Captured, a `search_news` quote with no `q`:

```json
{
  "ok": false,
  "error": "invalid_input",
  "message": "Input did not match the tool's schema.",
  "errors": [
    {
      "path": "$.q",
      "message": "is required"
    }
  ],
  "charged_paise": 0,
  "request_id": "58f42487-e3f2-43ad-9786-c09f542000bd"
}
```

## When to quote

- Before a loop over many inputs: add the estimates up and tell the user the total.
- Before any call the user may think expensive, and always when `confirm_required` is true: the quote is the body to show them.
- Over MCP the same call is `quote_tool`. [MCP reference](https://parel.si/docs/mcp.md#quote_tool).
