> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How runs work

> task id, run states, tool pauses, and how clients wait for completion

A **run** is one execution of an **agent** with a specific set of **inputs**. The API is **run-centric**: you start a run, receive a **`task_id`**, then observe **state changes** until the run reaches a **terminal** state.

## Lifecycle

1. **Start** — Your client sends an execute request with `agent_id`, inputs, and environment. The API returns **`task_id`**.
2. **Running** — Nodes execute; the model may request **tool calls**.
3. **Paused for tools** — Status such as **`awaiting_tool_calls`**. Your integration runs tool handlers and **submits results** so the run can continue.
4. **Terminal** — **`completed`** (with final output), **`failed`**, **`cancelled`**, or similar.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
stateDiagram_v2
  [*] --> Running: start_run
  Running --> AwaitingTools: model_requests_tools
  AwaitingTools --> Running: tool_responses_sent
  Running --> Completed: success
  Running --> Failed: error
  Running --> Cancelled: cancel_evt
```

## Waiting for completion

The usual client experience (**`run_agent`**, CLI **`execute --wait`**) keeps a **long-lived HTTP connection** so the server can **push** status updates (**SSE**). That is the default path in [Getting started](/quickstart/getting-started).

If you architect around **HTTP callbacks** instead (for example jobs that span **hours or days**), see [Running agents](/agents/running-agents) and [Webhooks](/agents/webhooks).

## Related

* [Evals, tests, and feedback](/concepts/evals-tests-and-feedback)
* [Interactive runs and local tools](/agents/sse-and-local-tools)