Run

POST /v1/run: execute a capability with routing and failover, or a raw endpoint under max_cost.

POST /v1/run

Execute a capability. The maximum billable amount is reserved before the provider call, then settled to the actual charge on success or released 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 organization's daily spend guard ends as blocked with error budget_exceeded before any money moves.

Headers

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}
}

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"}
}

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. gmail.send does not take attachments yet.

Response

{
  "run_id": "run_...",
  "status": "succeeded",
  "kind": "capability",
  "capability": "contact.find",
  "endpoint": null,
  "provider": "...",
  "routing_reason": "auto: best_value picked ...",
  "billing": {"currency": "USD", "quoted": "0.05", "charged": "0.05", "platform_funded": true},
  "timing": {"duration_ms": 842},
  "attempts": [
    {"provider": "...", "outcome": "provider_timeout", "duration_ms": 8000, "detail": "..."},
    {"provider": "...", "outcome": "succeeded", "duration_ms": 842, "detail": null}
  ],
  "result": {"...": "..."},
  "request_id": "req_...",
  "created_at": "2026-09-02T09:30:00+00:00"
}

hints, when present, provides 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 also explains budget-excluded alternatives using quotes for the requested input when available.

result is present on success; error ({code, message}) is present on failure. billing.charged is what actually settled: null or lower than quoted when the reservation was released or partly released. A raw endpoint run has kind: "endpoint", capability: null, endpoint set, billing.quoted as the rate-card estimate (or 0), and result.data holding the provider's payload untouched.

A run stopped by a workspace control ends as blocked before any money moves, with controls: [{"control": "daily_spend_guard" | "per_run_limit", "manage": "/v1/spend-guard"}]. It is terminal: tell the user, do not retry until the control changes.

Run lifecycle

created → reserved → running → succeeded | no_match | failed | timed_out

A run still in created, reserved or queued can be cancelled. 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.

Waterfall failover

With provider: "auto", a provider error, timeout or unbilled no-match falls through to the next-best provider automatically, up to 3 attempts. Only the provider that delivers is charged; every attempt appears in attempts with its outcome. max_cost caps every attempt, and a pinned provider never falls back.

Idempotency

Replaying the same Idempotency-Key returns the original run, marked Idempotent-Replay: true, without executing or billing again. Use it on every retry loop.

Errors you should handle

Full list: Errors.

Reading this as an agent? This page as markdown: /docs/api/run.md · every page: /docs/llms.txt