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.

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

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

Request

HeaderRequiredValue
AuthorizationyesBearer sk_… (or X-API-Key: sk_…)
Content-Typeyesapplication/json
Idempotency-KeynoSame as idempotency_key in the body; the body wins when both are sent
FieldTypeRequiredDescription
toolstring, 1 to 64 charactersyesA tool name from GET /v1/tools
inputobjectno (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_keystring, 1 to 128 charactersnoMakes retries safe. Every outcome: Conventions.
client_tagstring, 1 to 64 charactersnoA label (a client's name) that attributes the spend in the dashboard's usage log
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

FieldTypeDescription
oktrue
call_idstringThe call's id; also the X-Call-Id header
toolstringThe tool that ran
class"ok", "ok_free" or "replay"Only ok is charged
cost_paiseintegerWhat was charged; 0 for ok_free and replay
balance_paiseintegerThe balance after settlement (absent on a replay)
dataanyThe source's answer, as it came. Over REST it is complete, whatever its size.
notestringOnly on ok_free with nothing found: "No result found. This call was free."
replay_ofstringOnly on class: "replay": the first call's id

The shape of data is the tool's; each tool page 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):

{
  "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. The contract is on Slow jobs.

FieldTypeDescription
oktrue
call_id, toolstring
status"running"
class"running"
poll_after_secondsintegerHow long to wait before the first poll (the source's interval; 20 s when it gives none)
reserved_paiseintegerThe hold kept open while the job runs
messagestringThe 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 plus:

FieldTypeDescription
okfalse
error"confirmation_required"
confirmation_requiredtrue
estimate_paise, estimate, hold_paise, hold, balance_paise, enough_balanceAs on a quote
messagestring"This call is estimated at about ₹… (hold ₹…). The user has not approved this cost yet. Nothing was charged. …"
how_to_confirmstring"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. Captured from staging:

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

{
  "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):

{
  "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):

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

{
  "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 (402, with estimate_paise, balance_paise, topup_url and how_to_get_credit), budget_exceeded (429, with cap), rate_limited (429, with Retry-After), in_progress (409), idempotency_key_mismatch (422), replay_expired (410), and after the source was called upstream_timeout, upstream_busy, 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.

Next

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