API: all pagesDocs homeOverviewAPITools & MCPBasicsSavingReading and contextAgent runsWebhooks and connectorsRetries and idempotencyErrors and limitsCreditsPrivacy and deletionConsole sign-in
API / Use it / Agent runsCopy this page for your AI (Markdown)

Agent runs

  • Start a run: POST /v1/runs {user, task} returns run_id.
  • Log each step: POST /v1/runs/steps {user, run_id, kind: "tool_call" | "tool_result", tool, args | output, status}. A repeated failing call returns warnings from past failures. Large outputs are stored, not searched, and paged with GET /v1/handles/{id}.
  • Finish: POST /v1/runs/end {user, run_id, outcome: success | failure}.
  • Use the history: a later /v1/context with run_id cites the steps of similar successful runs. For coding tasks, that includes the past run whose edits touched the files or functions the new task names (strong matches only).