# Runs API

Runs are the shared asynchronous execution model for Agents, Eos Chat messages, and reports where applicable. A Run provides one place to inspect status, output, errors, tool activity, and required client action.

## Lifecycle

`queued` → `running` → `succeeded` or `failed`

A running execution may move to `requires_action` and return to `queued` after a valid response. A queued, running, or requires-action run may become `cancelled`. Terminal states never change.

## Run object

```json
{
  "object": "run",
  "id": "run_01J8RGK3FMGMNBY87S2C89C9NV",
  "kind": "agent",
  "status": "running",
  "agent_id": "agt_01J8RF2Z3TYMRYQYZPX0K83FWP",
  "conversation_id": null,
  "actor": {"type": "api_client", "id": "apic_01J8Q0Q4M10D6V0Q52QJ7RN8P4"},
  "subject": null,
  "input": {"invoice_id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S"},
  "output": null,
  "required_action": null,
  "error": null,
  "created_at": "2026-08-22T11:00:00Z",
  "started_at": "2026-08-22T11:00:01Z",
  "completed_at": null
}
```

## List and get runs

- `GET /v1/runs` — `listRuns`
- `GET /v1/runs/{run_id}` — `getRun`

Filters: `kind`, `status`, `agent_id`, `conversation_id`, `created_after`, `created_before`, `limit`, and `after`. Runs are visible only to the API Client that created them, unless a later explicit administration contract says otherwise.

## Stream run events

`GET /v1/runs/{run_id}/events`

Operation ID: `streamRunEvents`. Response type: `text/event-stream`.

Events have a stable `id`, `type`, `created_at`, and `data`. Initial event types include `run.started`, `run.progress`, `run.tool.started`, `run.tool.completed`, `run.output.delta`, `run.requires_action`, `run.completed`, and `run.failed`. Tool events contain safe summaries and resource references, not hidden prompts, secrets, or provider credentials.

Clients should reconnect with `Last-Event-ID`. Webhooks are preferable for durable background notification.

## Submit a required action

`POST /v1/runs/{run_id}/actions`

Operation ID: `submitRunAction`. Required header: `Idempotency-Key`.

```json
{
  "action_id": "act_01J8RH1TQ7",
  "response": {"choice": "use_primary_contact"}
}
```

Only a choice offered in `required_action.schema` is accepted. This endpoint supports clarification and explicitly allowed low-risk confirmation; it does not support formal approval, identity assertion, or permission elevation.

## Cancel a run

`POST /v1/runs/{run_id}/cancel`

Operation ID: `cancelRun`. Required header: `Idempotency-Key`. Cancellation is best effort. Completed side effects are not rolled back, and the final Run lists completed tool operations.

## Output and errors

Structured output conforms to the Agent or conversation response schema where one is declared. Large output is represented by file or artifact references. Failures use the standard Eos error envelope and include a run-safe error code; hidden model reasoning and internal prompts are never returned.

## Common errors

`RUN_NOT_FOUND`, `RUN_NOT_ACTIONABLE`, `RUN_ACTION_INVALID`, `RUN_ALREADY_TERMINAL`, `RUN_CANCEL_NOT_AVAILABLE`, and `RUN_OUTPUT_EXPIRED`.

Next: [Conversations API](conversations.html).