Tasks and Runs

Track asynchronous work, execution state, run steps, artifacts, costs, and traces.

Tasks and runs are the runtime backbone of SOIT. A run is the trace root for an execution. A task tracks asynchronous or long-running work with its own status language. Run steps describe each observable unit inside the run.

When to use tasks and runs

Use tasks for queued, running, or retryable work — long ingestion jobs, scheduled workflow executions, batch operations. Use runs to inspect the execution ledger for chat turns, agent runs, workflow runs, tool calls, retrieval, and batch execution.

What is recorded

Record	Contents
Run	Status (`queued / running / succeeded / failed / canceled`), mode, execution subject and its exact version, bounded input/output summaries, timings
Run step	Type (`llm / retrieval / rerank / tool / workflow_node / agent_plan / memory_write / io`), status, owner references, bounded summaries, metrics (tokens, latency, HTTP status, vector counts)
Artifact	Large payloads by reference: storage key, mime, size, hash
Cost entry	Currency, amount, unit, quantity, provider, model/tool ref, token breakdowns
Task	Async work state with explicit status transitions

Runs also record the entry they came through (source: platform or gateway) and the API key that started them (api_key_id), so calls from the gateway and their spend can be read on their own or per key.

Three properties make the ledger trustworthy: steps are append-only (retries add steps, never rewrite), failures preserve evidence (a failed run keeps all prior steps, artifacts, and costs plus the failing step's error), and every run records the exact published version it executed.

Working with the ledger

/tasks shows the execution queue with per-task detail and control.
/observe/runs is the Run Explorer — filter by tool calls, citations, or audits to find a specific execution.
/observe/runs/{run_id} assembles the full timeline: response events, steps, tool calls, child workflow runs, costs, citations, and audit records.
Every API response that triggers execution returns its run_id, so application logs can always be joined to runtime evidence.
A run's evidence bundle packages its records, tool calls, approvals, citations, and policy ids in a verifiable zip, and ledger exports take runs, steps, costs, audit, and events out by time window — see Evidence and Exports.

How they connect

Every capability's execution — Chat, Workflows, Evaluation, knowledge ingestion — lands in this same ledger.
Cost entries roll up for workspace-level attribution.
The outbox keeps ledger state and async side effects consistent.

API and UI surfaces

API prefixes: /api/v1/tasks, /api/v1/runs
Web routes: /tasks, /observe, /run

For the underlying invariants, see Runtime Ledger.