Eos Developers
Design target — not live yet. This documentation defines the contract Eos will implement. Existing internal application APIs are not part of this contract.

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

{
  "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.

{
  "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.