> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Stream run events

> Stream real-time events from agent runs using Server-Sent Events (SSE).

When you create a run, you can stream its progress in real time using Server-Sent Events (SSE). The stream delivers events as the agent starts, produces state updates, and finishes.

## Connecting to the stream

To stream events for a run, make a `GET` request to the stream endpoint after creating the run:

```bash
curl -N \
  -H "Authorization: Bearer $MIDDESK_API_KEY" \
  -H "Accept: text/event-stream" \
  https://api.middesk.com/v1/runs/{run_id}/stream
```

The response uses the `text/event-stream` content type and keeps the connection open until the run completes.

## Event format

Events are emitted in [AG-UI](https://docs.ag-ui.com) format. Each event is delivered as a standard SSE message:

```
event: RUN_STARTED
data: {"run_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab", ...}

event: STATE_SNAPSHOT
data: {"run_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab", "snapshot": {...}, ...}

event: RUN_FINISHED
data: {"run_id": "c1d2e3f4-5678-90ab-cdef-1234567890ab", ...}
```

## Event types

| Event            | Description                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `RUN_STARTED`    | Emitted when the agent begins execution.                                                                |
| `STATE_SNAPSHOT` | Emitted as the agent progresses, containing the current state of the run including steps and artifacts. |
| `RUN_FINISHED`   | Emitted when the agent completes execution. The connection closes after this event.                     |

## Handling the stream

A typical integration connects to the stream immediately after creating a run:

#### Create a run

Create a run via `POST /v1/runs` with the agent type and context. See [Run agents](/work-with-agents/run-agents).

#### Connect to the stream

Use the returned run `id` to open an SSE connection to `GET /v1/runs/{id}/stream`.

#### Process events

Listen for `RUN_STARTED`, `STATE_SNAPSHOT`, and `RUN_FINISHED` events. Use `STATE_SNAPSHOT` events to update your UI or track progress as the agent works.

> **Info**
>
> If a run has already completed, the stream replays all events from the beginning and closes once the final event is delivered. Connect promptly after creating the run — stream data is retained for a limited time after completion.

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.