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

# Streaming & Replay

> Follow task execution via SSE and reproduce runs from recorded traces.

Instead of polling for task completion, you stream events as the task runs — seeing each state change, context assembly, and output delta in real time. When something goes wrong (or you just want to understand what happened), replay lets you reproduce a past run from its recorded trace without re-executing anything.

Tasks emit a live stream of Server-Sent Events (SSE) as they plan and execute. Completed or failed tasks can be replayed from their recorded trace for debugging, auditing, and reproduction.

## How streaming works

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/task-submission.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=3e691bdaa3c0d0ce67cefcc7a659f4dc" alt="Task submission and streaming" width="1536" height="1024" data-path="assets/diagrams/task-submission.png" />

## SSE event types

### Task lifecycle events

| Event            | Meaning                                            |
| ---------------- | -------------------------------------------------- |
| `task.submitted` | Task was accepted.                                 |
| `task.state`     | Task changed state (carries new state in payload). |
| `task.result`    | A result payload is available.                     |
| `task.error`     | An error occurred during execution.                |
| `task.complete`  | Task finished successfully (terminal).             |
| `task.failed`    | Task failed (terminal).                            |
| `task.cancelled` | Task was cancelled (terminal).                     |

### Output events

| Event           | Meaning                                          |
| --------------- | ------------------------------------------------ |
| `runtime.delta` | Incremental output chunk (render progressively). |

### Platform events

These events provide additional observability but are implementation details — do not depend on their presence or ordering in your application logic. They may change without notice.

| Event             | Meaning                             |
| ----------------- | ----------------------------------- |
| `runtime.lease`   | Execution resources were allocated. |
| `runtime.context` | Context was assembled for the run.  |
| `runtime.handoff` | Work was routed between agents.     |
| `runtime.why`     | Reasoning detail for a step.        |

<Note>
  Terminal events (`task.complete`, `task.failed`, `task.cancelled`) signal end-of-stream. Stop reading after receiving one.
</Note>

## Stream a task

```python theme={"dark"}
for event in client.orchestrator.task.stream("YOUR_TASK_ID"):
    match event["type"]:
        case "runtime.delta":
            print(event["data"], end="", flush=True)
        case "task.complete":
            print("\nDone.")
            break
        case "task.failed":
            print(f"\nFailed: {event.get('data')}")
            break
```

```bash theme={"dark"}
# Use the SDK: client.orchestrator.task.create(...) with goal as input
```

## Resuming a stream

The stream is resumable. If a connection drops, reconnect and pass the last received event ID to resume without replaying already-delivered events.

## Replay a task

Replay re-runs a task from its recorded execution trace.

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    client.orchestrator.task.replay("YOUR_TASK_ID")
    ```
  </Tab>
</Tabs>

<Tip>
  Replay reproduces the recorded run. External systems may have changed since the original execution; side effects are not guaranteed to be identical.
</Tip>

## Errors

| HTTP  | When                                              |
| ----- | ------------------------------------------------- |
| `404` | The task ID doesn't exist or isn't in your scope. |
| `400` | Invalid stream resume position or replay request. |

A dropped stream connection is not an error — reconnect and resume from the last event ID you received.

## Production recommendations

* Treat `task.complete`, `task.failed`, and `task.cancelled` as terminal: stop reading once one arrives.
* Render `runtime.delta` events incrementally rather than buffering the whole stream.
* Persist the last received event ID so you can resume cleanly after a disconnect.
* Use replay to reproduce a failed run before changing the agent or input.

## Rate limits

100 requests per organization per minute.

<AccordionGroup>
  <Accordion title="Handling runtime.delta">
    `runtime.delta` events carry incremental text chunks. Concatenate and render them progressively for a responsive UI. Do not wait for the full result before displaying output.
  </Accordion>

  <Accordion title="Distinguishing terminal events">
    A stream always ends with exactly one of `task.complete`, `task.failed`, or `task.cancelled`. Use this to determine the final outcome and clean up resources.
  </Accordion>
</AccordionGroup>

## Related pages

<CardGroup cols={2}>
  <Card title="Tasks" icon="list-check" href="/docs/orchestration/tasks">
    Submit and manage tasks.
  </Card>

  <Card title="Approvals" icon="user-check" href="/docs/orchestration/approvals">
    Handle plan review events.
  </Card>

  <Card title="Observability" icon="chart-line" href="/docs/observability/overview">
    Logs and metrics beyond a single task.
  </Card>

  <Card title="Tasks & Workflows" icon="sitemap" href="/docs/concepts/tasks-and-workflows">
    The lifecycle behind the events.
  </Card>
</CardGroup>

## Next steps

Explore the [Tool Gateway](/docs/tool-gateway/overview) to give your agents real-world actions.