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.

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

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

Request

FieldTypeRequiredDescription
toolstringyesA tool name
inputobjectno (default {})The exact input you intend to send. It is validated against the tool's schema first.
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

FieldTypeDescription
oktrue
toolstring
quotetrueMarks this as a quote, not a run
charged_paise0Nothing was charged for the quote
estimate_paise, estimateinteger, stringThe likely charge for this input at today's rate
hold_paise, holdinteger, stringWhat 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.
per_result_paiseintegerOnly for per-result tools: the price of one result
count_field, countstring, integer or nullOnly for per-result tools: the input field the estimate was priced on, and the value found in the input
modestringOnly for mode-priced tools: the mode the estimate used
confirm_requiredbooleanWhether running this input would answer confirmation_required
free_when_no_resultbooleanWhether an empty answer is ₹0 for this tool
asyncbooleanWhether the tool is a slow job
balance_paiseintegerYour balance now
enough_balancebooleanbalance_paise >= hold_paise
topup_urlstringOnly when the balance is not enough
notestringThe rule in a sentence

Captured from staging:

{
  "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, ₹0. Captured, a search_news quote with no q:

{
  "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.

This page as Markdown: /docs/api/quote.md. Something wrong or missing: hello@parel.si.