Run
POST /v1/run: execute a capability with routing and failover, or a raw endpoint under max_cost.
POST /v1/run
Execute a capability, or a raw endpoint. The run holds its maximum charge on the wallet before the provider call, then settles it to the actual charge on success or releases it on failure. The request waits up to wait_seconds (default 30, max 120) for the result and answers 200 with the finished run; a run still executing answers 202 with the same payload (done: false) to poll at GET /v1/runs/{run_id}?wait=60. Send "async": true to get the 202 immediately. A run that would breach the workspace's spend guard ends as blocked before any money moves.
Headers
| Header | Required | Notes |
|---|---|---|
Authorization |
yes | Bearer rg_ |
Content-Type |
yes | application/ |
Idempotency-Key |
recommended | any unique string; makes the call safe to retry (idempotency) |
Request
{
"capability": "contact.find",
"input": {"first_name": "Alex", "last_name": "Rivera", "company_domain": "example.com"},
"routing": {"provider": "auto", "strategy": "best_value", "max_cost": "0.10", "allow_fallback": true},
"response": {"include_raw": false}
}
| Field | Type | Default | Notes |
|---|---|---|---|
capability |
string | one of | from discover |
provider + endpoint |
strings | one of | a raw endpoint instead of a capability; path fills {placeholders}, query adds query parameters |
input |
object | {} |
must match the capability's input_ from inspect, and a value outside one of its enum lists is refused before routing; for a raw endpoint, the provider's own request body. email. takes attachments. An HTML entity in a text value (AT&T as agents sometimes write it, or R&D encoded twice) is decoded before a capability runs, and the run stores the decoded input; fields that carry HTML, templates or schemas (html, content, template, schema, output_) and raw endpoint bodies are sent as given |
routing. |
string | "auto" |
auto, or a provider slug to pin: the run tries that provider alone, even with allow_ (on a lookup it goes first and the rest follow, see waterfall failover) |
routing. |
string | none | a provider to try first, with the rest of the waterfall behind it; an unknown slug answers invalid_. On people., "prefer": "apollo" gets a known company's people with their work email in one call (people search) |
routing. |
string | "best_ |
best_, cheapest, fastest or highest_ (how each orders providers) |
routing. |
string | none | USD cap, as a decimal string. Offers that quote above it are excluded before the call, fallbacks included, so a cap at the cheapest provider's price also disables failover (the error then names the excluded fallbacks and the cap that admits them). It also caps the hold and the charge. On a capability, take it from inspect's waterfall. (a lookup raises a lower cap to it, see waterfall failover); on a raw endpoint it is the only price control: set it on every call |
routing. |
bool | true |
false stops after the first provider; ignored on a lookup |
routing. |
bool | false |
run even when this exact input missed in the last 12 hours (repeated misses), or when a table row already holds the result |
routing. |
bool | false |
with the user's say-so, start a new conversation with someone contacted inside the repeat window |
response. |
bool | false |
add the provider's own payload as result. next to the normalized fields, for anything the normalized shape leaves out; withheld (with result.) when it would name someone who opted out or exceeds 256 kB |
wait_ |
integer | 30 |
how long the request waits for the result, 0 to 120 |
async |
bool | false |
answer 202 at once, like wait_ |
record, into |
object | none | link the run to a row of a workspace table, or land a list result as rows; capabilities only |
Attachments on email.send
An email sent from one of your inboxes can carry files: a deck for an investor, a PDF quote, a one-pager. Pass them in input.attachments, on a new message or a reply (in_reply_to):
{
"capability": "email.send",
"input": {
"inbox_id": "alex@getacme.com",
"to": ["investor@fund.example"],
"subject": "Acme deck, as promised",
"text": "Hi Sam,\n\nThe deck is attached.\n\nAlex",
"attachments": [
{"filename": "acme-deck.pdf", "content_type": "application/pdf", "url": "https://files.getacme.com/acme-deck.pdf"},
{"filename": "one-pager.pdf", "data_base64": "JVBERi0xLjQK..."}
]
},
"routing": {"max_cost": "0.01"}
}
| Field | Notes |
|---|---|
filename |
required; the plain file name the recipient sees, no path |
content_ |
media type such as application/; guessed from the filename when omitted |
url |
a public https URL the sending provider downloads itself; pre-signed and redirecting URLs work. Exactly one of url or data_ |
data_ |
the file's bytes as standard base64, inline in the request |
size_ |
optional with url: the file's size, counted toward the total |
Limits per message: 10 files, 10 MB in total, and 4 MB of inline data_base64 (the request body that carries it is capped at 8 MB). Anything larger goes by url. The run's result lists the attachments the provider accepted; the run's stored input keeps each inline file's name, type and size but not its bytes. A send is priced per email whatever it carries. linkedin.message takes the same attachments within the same limits (images or files; a url is fetched when the message is sent). gmail.send does not take attachments yet.
Response
Abridged:
{
"run_id": "run_8b0e5d2c7a9f4e13b6c1d0a2f5e7c9b4",
"status": "succeeded",
"done": true,
"stoppable": false,
"poll_url": "/v1/runs/run_8b0e5d2c7a9f4e13b6c1d0a2f5e7c9b4",
"kind": "capability",
"capability": "contact.find",
"endpoint": null,
"provider": "apollo",
"routing_reason": "lowest quoted price first, no measured results yet; waterfall: icypeas provider_timeout → apollo succeeded",
"billing": {"currency": "USD", "quoted": "0.0312", "charged": "0.0312", "platform_funded": true},
"timing": {"duration_ms": 8514},
"attempts": [
{"provider": "icypeas", "outcome": "provider_timeout", "duration_ms": 8000, "detail": "icypeas timed out"},
{"provider": "apollo", "outcome": "succeeded", "duration_ms": 514, "detail": null}
],
"request_id": "req_3d9b6f0a1c2e4b7d8f5a6c9e0b1d2f3a",
"created_at": "2026-10-28T09:30:00+00:00",
"coverage": {
"status": "complete",
"providers_attempted": ["icypeas", "apollo"],
"providers_succeeded": ["apollo"],
"providers_failed": [{"provider": "icypeas", "outcome": "provider_timeout", "duration_ms": 8000, "detail": "icypeas timed out"}]
},
"result": {
"email": "alex.rivera@example.com",
"status": "valid",
"person": {"first_name": "Alex", "last_name": "Rivera", "position": "Head of Growth"},
"company": {"name": "Example", "domain": "example.com"}
},
"next_steps": [
{"goal": "get the person's profile and role history", "call": "run", "capability": "person.enrich", "input": {"email": "alex.rivera@example.com"}},
{"goal": "find the person's phone number", "call": "run", "capability": "contact.phone", "input": {"email": "alex.rivera@example.com"}}
]
}
Prices on this page are catalog prices, which start at the Scale plan rate; inspect returns your workspace's exact price.
done turns true once the run is terminal, stoppable is true while it is still queued and can be cancelled, and poll_url reads it again.
billing.quoted is the price for this input on the provider that ran. billing.charged is what settled: null while the run is pending, null or "0" when nothing was charged, less than quoted when fewer results came back than the quote assumed, and more when the provider's measured cost came in above the quote, never above the hold or max_cost. A run served through Apify is settled again a few minutes later, on Apify's final bill: a raw endpoint's charge follows it up or down, a capability's only rises, within the same bounds; GET /v1/runs/{id} shows the final charge.
result is present on success; error ({code, message}) once the run has ended any other way. A raw endpoint run has kind: "endpoint", capability: null, endpoint set, billing.quoted as the rate-card estimate ("0" when there is none), and result.data holding the provider's payload untouched.
hints, when present, gives free guidance about provider pinning, disabled fallback and how to refine a missed people search. It never changes your routing or spending limits. On unbilled no-matches and provider failures, the error message also names the alternatives max_cost excluded, priced for this input when possible.
next_steps, when present on a finished run, lists up to three calls that usually follow it, with their input filled from this result: {goal, call, capability, input}, or inputs when call is batch_run, with an optional routing and note. A contact.find hit marked risky points at contact.verify with the found address; a people.search page points at one contact.find batch for the rows without an email and at the next page; a miss whose max_cost kept dearer providers out points at the same call with the cap that lets them all try. Each step is a suggestion, never run for you, and billed like any run when you make it. Run lists and watch responses leave it out.
coverage is present once a run that reached a provider is terminal, the same on POST /v1/run, GET /v1/runs/{id}, GET /v1/runs and a watch refresh's run. status is complete when a result was delivered or every provider answered (an empty answer is then the finding), partial when the run is no_match but some provider errored, was rate limited or timed out, and failed when no provider answered. providers_failed lists those attempts with their outcome, duration_ms and the provider's error detail (e.g. DataForSEO's 40101). A partial no_match carries error code no_match_partial_coverage instead of no_match: it is not evidence that nothing exists, so retry later or check the source another way.
A run stopped by a workspace control ends as blocked before any money moves, with controls: [{"control", "manage"}] naming the control (daily_spend_guard, per_run_limit, suppression_list, privacy_opt_out, repeat_touch_guard, send_pacing or email_unverified) and where it is managed. It is terminal: tell the user, and do not retry until the control changes.
Run lifecycle
queued → running → succeeded | no_match | failed | timed_out
A run can also end blocked, when a workspace control stops it before any money moves, or cancelled, while it is still queued (the only status a cancel can stop). Run statuses describes each one. no_match means at least one provider answered authoritatively that there is no result; whether that bills depends on the capability's stated billing conditions.
A run the router was executing when it restarted stays running for up to about 15 minutes, then ends failed with error interrupted and its hold released: retry it with a new Idempotency-Key.
Repeated misses
On people.search, company.search, company.enrich, company.funding, person.enrich, contact.find and contact.phone, an input that every provider answered with no_match in the last 12 hours is not sent to them again: the run ends no_match at once, charges nothing, and carries repeat_of with the id of the run that missed. A repeated hit always runs, and so does a run with different routing, a provider added since, or routing.fresh: true. The same holds for a raw endpoint that answers no_match (RB2B's "no record found"): the identical call to the same endpoint within 12 hours is answered from the run log, free, whatever its max_cost.
Waterfall failover
With provider: "auto", a provider error, rate limit, timeout or unbilled no-match falls through to the next provider in the waterfall, up to 3 providers per run. The order follows routing.strategy; a provider that does not serve the input's platform is left out, and one whose recent calls failed, or whose latest call failed in the last few minutes, moves to the back (routing). Only the provider that delivers is charged; every attempt appears in attempts with its outcome. max_cost applies to every attempt, and a pinned provider or allow_fallback: false stops after the first.
Lookups run the whole waterfall. On a capability billed per match or per verdict where a miss is free (contact.find, contact.verify, contact.phone, person.enrich, company.enrich, company.funding, company.technologies, social.profile; inspect shows waterfall.runs_every_provider: true), every live provider tries until one finds. A pinned provider goes first and the rest follow, allow_fallback: false is ignored, and a max_cost under the dearest provider's price is raised to it, so a found result costs at most waterfall.max_cost_for_all. On contact.verify, only a valid or invalid verdict is a find: an unknown, risky or catch-all reading is free and the next verifier tries; when none decides, the run ends no_match, free, with each reading in attempts.
Idempotency
Replaying the same Idempotency-Key returns the original run, marked Idempotent-Replay: true, without executing or billing again, and waits for it like a new request. Use it on every retry loop. The key is scoped to your workspace and never expires, and a replay ignores the body: send a new key for each distinct call. A run refused before any provider was called (cost_limit_exceeded, a short balance, an invalid input: status failed, no attempts, nothing charged) does not hold its key: retry under the same key once you have raised max_cost or fixed the input. Retry a run that reached a provider, ended interrupted or was blocked with a new key: the old one can replay that run.
Errors you should handle
A run refused before any provider was called answers with the error envelope, and nothing is charged:
| Code | Meaning |
|---|---|
invalid_ (400) |
the body or input does not validate, or a value is outside an input_ enum |
capability_ (404), endpoint_ (404) |
unknown capability, or unknown raw endpoint for that provider (list them at /) |
insufficient_ (402) |
the hold exceeds the available balance; details carry checkout links to top up |
cost_ (402) |
every eligible provider quotes above max_ (details. is the price that would run), or the hold exceeds the workspace's per-run ceiling (the run is blocked) |
budget_ (402) |
the daily spend guard would be breached (the run is blocked) |
email_ (403) |
the workspace has not verified its email yet: verify it from the dashboard, or top up (the run is blocked) |
forbidden (403) |
record or into on a workspace with tables off, or a call the credential's grant does not allow |
provider_ (409) |
no live provider for this capability yet, none that serves the input's platform, the pinned provider does not serve it, or the raw endpoint's provider account is not open |
suppressed, opted_ (403), repeat_ (409), paced (429) |
an outbound control stopped a send (the run is blocked) |
With async: true, or once wait_seconds has passed, a refusal raised after the run started executing shows on the polled run instead, as status: failed or blocked with the same error.code.
A run that reached a provider answers 200 whatever its outcome: read status and error.code. provider_error (502) and internal_error (500) can also arrive as an error response, when the failure happens outside a provider attempt (errors and run outcomes).
status |
error.code |
Meaning |
|---|---|---|
no_ |
no_ |
the providers found nothing; billed only if the capability bills no-matches |
no_ |
no_ |
nothing found by the providers that answered, but at least one errored or timed out (coverage.); nothing charged, retry later |
failed |
provider_, provider_ |
every provider tried failed; nothing charged |
timed_ |
provider_ |
the last provider tried timed out; nothing charged |
Full list: Errors.
Reading this as an agent? This page as markdown: /docs/api/run.md · every page: /docs/llms.txt