# Streaming

Subscribe to `GET /v1/runs/{runId}/sse` to observe behavior in real time.

Include optional query parameter `includeToolCalls`  if you want to have detailed request/response to be included for **step** event types.

### Event Format

```json
id: <sequential_int>
event: <event_name>
data: <json>
```

Special heartbeat:

```json
event: keepalive
data: null
```

A `keepalive` is emitted every 20 s while at least one client is connected.

### Data Events

<table><thead><tr><th width="151.92578125">Event</th><th>Description</th></tr></thead><tbody><tr><td><code>start</code></td><td>The run begins execution.</td></tr><tr><td><code>step</code></td><td>A step inside the run finishes. Can be used for giving updates to end user about how run is progressing.</td></tr><tr><td><code>authentication</code></td><td>The run needs user authentication (status transitions to <code>AUTH_REQUIRED</code>) or reports its outcome.</td></tr><tr><td><code>run_approval</code></td><td>The run requires manual approval before proceeding (Emitted if Create Run request has approval strategy set).</td></tr><tr><td><code>run_action</code></td><td>Records the approval decision made by the user (approved or denied).</td></tr><tr><td><code>status</code></td><td>Any other status change (e.g. <code>QUEUED</code>, <code>PAUSED</code>).</td></tr><tr><td><code>end</code></td><td>The run finishes (<code>SUCCESS</code>, <code>FAILED</code>, or <code>CANCELED</code>).</td></tr></tbody></table>

Every data event contains:

```
{
    runId: string
    runStatus: "QUEUED" | "RUNNING" | "SUCCESS" | "FAILED" | "CANCELED" | "AUTH_REQUIRED" | "PAUSED"
    timestamp: (ISO-8601 string)
}
```

### Payload reference

#### `start`

```
{
  "runId": string,
  "runStatus": "RUNNING",
  "timestamp": ISO-8601 string
}
```

#### `step`

```
{
  "runId": string,
  "runStatus": "RUNNING" | "PAUSED",
  "timestamp": ISO-8601 string,
  "step": {
    "reason": string,
    "approval": "APPROVED" | "DENIED" | "PENDING" | "NOT_REQUIRED",
    "approvalActions"?: [{
      "action": "approve" | "deny",
      "url": string
    }],
    "toolCalls"?: [{
      "toolCallId": string,
      "toolName": string,
      "toolParameters": object,
      "toolResult"?: {
          "approvalResult": { "status": string, "text": string },
          "executionResult": object
      }
    }],
    "text"?: string
  }
}
```

#### `authentication`

```
{
  "runId": string,
  "runStatus": "AUTH_REQUIRED" | "RUNNING" | "FAILED",
  "timestamp": ISO-8601 string,
  "auth":
    | { "status": "required", "url": string, "integrationName": string }
    | { "status": "success" }
    | { "status": "denied" }
}
```

#### `run_approval`

```
{
  "runId": string,
  "runStatus": "PAUSED",
  "timestamp": ISO-8601 string,
  "approvalActions": [{
      "action": "approve" | "deny",
      "url": string
    }]

}
```

#### `run_action`

```
{
  "runId": string,
  "runStatus": "RUNNING" | "CANCELED",
  "timestamp": ISO-8601 string,
  "action": "approved" | "denied"
}
```

#### `status` (queued / paused)

```
{
  "runId": string,
  "runStatus": "QUEUED" | "PAUSED",
  "timestamp": ISO-8601 string,
  "reason"?: string
}
```

#### `end`

```
{
  "runId": string,
  "runStatus": "SUCCESS" | "FAILED" | "CANCELED",
  "timestamp": ISO-8601 string,
  "result": {
    "text": string,
    "structuredOutput"?: (user provided output schema)
  }
}
```