Runs & the result envelope

Starting a run

• POST /v1/runs — an inline run from a prompt (the one-call primitive).
• POST /v1/jobs/{id}/runs — run a saved job (a reusable template whose prompt carries {{placeholders}}).

Body fields: prompt (or the job's), inputs (fills {{placeholders}}), output_schema (JSON Schema for the shape you want back), model (haiku | sonnet | opus, default sonnet), project_id (optional — defaults to your org's auto-created API Runs project), callback_url, and idempotency_key.

The result envelope

GET /v1/runs/{id} returns:

{
  "task_id": "run_...",
  "status": "queued | running | succeeded | failed | cancelled",
  "result": { /* your output_schema shape, or null */ },
  "confidence": "high | medium | low | null",
  "evidence": { "screenshot_url": "…7-day signed URL…", "matched_text": "…", "checked_at": "…" },
  "failure_reason": "captcha | auth_required | site_down | timeout | ambiguous | not_found | null",
  "usage": { "duration_ms": 0, "input_tokens": 0, "output_tokens": 0, "cost_usd": 0 },
  "created_at": "…", "finished_at": "…"
}

• `result` conforms to your output_schema on a best-effort basis.
• `evidence` lets you verify what the agent actually saw.
• `failure_reason` is explicit — OpenHelm never fabricates a result. auth_required means the task needed a connection that isn't set up.
• `usage.cost_usd` is the actual billed cost (the 202 billing block was only an estimate).

Idempotency

Pass idempotency_key to make retries safe — a replay returns the original run instead of starting a new one.