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
| 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 |
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. |
client_tag | string, 1 to 64 characters | no | A 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
| 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 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.
| 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 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. 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
POST /v1/quote: the same numbers before you spend.GET /v1/runs/:id: the record of any call; polling for slow jobs.
This page as Markdown: /docs/api/run.md. Something wrong or missing: hello@parel.si.