> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/streaming-api-events-and-client-handling.md).

# Streaming API Events and Client Handling

The inference API can stream an answer while the workflow runs. Parse complete events, update the displayed answer, and check the final run state. A closed stream does not by itself mean that the workflow succeeded.

![Request standard SSE frames](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F3kouPfJRIh9CqJyPnchd%2Fstreaming-api-events-and-client-handling.png?alt=media)

Use the project’s generated legacy-inference input contract in input.json. With delta=false, replace displayed output with each full snapshot. Inspect the final state and error; a closed connection alone is not success.

<details>

<summary>Copy the example</summary>

```bash
curl -N -X POST \
  "$STACKAI_BASE_URL/inference/v0/run/$ORG_ID/$PROJECT_ID?prefix=true&verbose=true&delta=false" \
  -H "Authorization: Bearer $STACKAI_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  --data-binary @input.json
```

</details>

## Before you begin

A client that supports the endpoint’s documented streaming format.

## Streaming concepts

| Term                 | Definition                                                                                                                                                               |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Streaming            | Delivery of incremental events or text while work is running. Updates are not the same as a completed answer.                                                            |
| Full output snapshot | With `delta=false`, a frame carries the latest complete output values. Replace the displayed value rather than appending it.                                             |
| Completion marker    | A frame with `metadata.done=true` marks the end of the stream. Its `state` and `error` determine the outcome; its message alone does not establish success.              |
| Terminal state       | Legacy inference uses `COMPLETED`, `FAILED`, or `CANCELLED` for finished runs. `PAUSED` needs a human response and can end the current stream without finishing the run. |
| Timeout              | A limit on how long a particular client or operation waits. It does not always establish that execution or an external write stopped.                                    |

## Consume streaming API events

1. Call `/inference/v0/run/{org_id}/{flow_id}` from your backend with `Accept: text/event-stream`. Use `prefix=true` for standard SSE `data:` frames, `verbose=true` for run metadata, and `delta=false` for full output snapshots.
2. Buffer incomplete frames and parse their `data` JSON. Save the `run_id` and display values from the project’s output IDs. Keep the API key on your backend.
3. For full snapshots, replace the prior displayed output. Do not append it. Ignore the `outputs.type=stream_complete` control marker when rendering the answer.
4. Read the completion frame’s `state` and `error`. A `COMPLETED` state means success; `FAILED` or `CANCELLED` means the answer did not complete normally. For `PAUSED`, store the pause payload securely and obtain the person’s response before using the resume endpoint.
5. If the connection drops, read `/inference/v0/runs/{org_id}/{run_id}` to inspect that execution. Do not automatically start another run to recover the connection.

The client displays progress without losing the distinction between partial and completed output.

## Behavior and limitations

Network chunks do not necessarily align with event boundaries. Keep incomplete data until a full event arrives. A dropped connection does not guarantee cancellation. The inference API does not document replay from an SSE `Last-Event-ID`. Legacy streaming and v2 run polling use different response shapes and status names; v2 success is `succeeded`, while inference success is `COMPLETED`. Keep resume tokens out of browser events and logs.

## Related resources

API Versions and Compatibility

[Streaming request, event frames, and client examples](https://docs.stackai.com/stackai-api/stackai-api-developer-guide/legacy-inference-streaming-and-analytics.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/streaming-api-events-and-client-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
