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

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.

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