# 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)
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/basics/streaming.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.