Receive response text in real time as it is generated, instead of waiting for the complete response. Use streaming to display text as it arrives, show progress for long responses, or reduce perceived latency in a chat interface. This guide shows how to stream a response and read the events it returns.

Key concepts

Streaming: Delivers Jockey’s response incrementally, as it is generated, instead of returning the complete response in a single reply. The SDK manages the underlying connection, so you handle each update as it arrives.
Events: The stream arrives as a series of events. Most carry a small fragment of the generated text, which you concatenate to build the full response; a final event marks the end of the stream.

Prerequisites

You’ve already uploaded your videos and images, and the assets have reached the ready status. See the Upload content page for details.
You’ve already created a knowledge store. See the Create a knowledge store page for details.
You’ve already added at least one asset to the knowledge store, and the item has reached the ready status. See the Add assets to a knowledge store page for details.
You’ve already read the Create a response page and understand the basic request and response format.

Example

Copy and paste the code below, replacing the placeholders surrounded by <> with your values.

1 from twelvelabs import TwelveLabs
2 
3 client = TwelveLabs(api_key="<YOUR_API_KEY>")
4 
5 stream = client.responses.create_stream(
6     knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
7     input=[{"type": "message", "role": "user", "content": "Describe what these videos and images show"}],
8     # session_id=...,  # Optional. Continue a multi-turn conversation. See Multi-turn sessions.
9     # instructions=...,  # Optional. Add a per-request system prompt. See Create a response.
10     # include=...,  # Optional. Return intermediate reasoning steps. See Create a response.
11     # selections=...,  # Optional. Restrict the request to specific items or item collections.
12     # text=...,  # Optional. Return typed JSON output. See Structured output.
13 )
14 
15 for event in stream:
16     if event.type == "response.output_text.delta":
17         print(event.delta, end="", flush=True)

Code explanation

Python

Node.js

To stream a response as it is generated, call the responses.create_stream method and iterate over the events it returns. It accepts the same parameters as the responses.create method. This example writes each incremental text fragment to the standard output as it arrives.
Parameters:

knowledge_store_id: The unique identifier of the knowledge store to reason over. Every request requires exactly one.
input: An array of input items. Each item is a message you send to Jockey.
(Optional) session_id: Continues a multi-turn conversation. Pass the identifier from a previous response. See the Multi-turn sessions page.
(Optional) instructions: Adds a per-request system prompt that shapes Jockey’s behavior for your domain or task. See the Create a response section for details.
(Optional) include: An array of extra items to include in the response. Pass intermediate_outputs to return Jockey’s reasoning steps in the output array. See the Create a response page.
(Optional) selections: An array that restricts the request to specific knowledge store items or item collections. Omit to run against every item.
(Optional) text: An object that specifies the response format. Provide a JSON Schema to return typed JSON output. See the Structured output page for details.

Return value: A stream of typed events. Iterate the stream: each response.output_text.delta event contains an incremental text fragment in its delta field, and a response.completed event marks the end of the stream. Concatenate the deltas to build the full response.

Example response

Each response.output_text.delta event contains a fragment of the generated text in its delta field:

1 {"type": "response.output_text.delta", "delta": "The main"}

Events arrive incrementally. Concatenate the deltas to build the full response.

Common pitfalls

Iterate to completion. Consume the full stream so the connection closes cleanly and you receive every text fragment.
Concatenate the deltas. Each response.output_text.delta event contains a fragment of the generated text; concatenate them in arrival order to build the full response.
Reconnect manually if the stream drops. If the stream ends before completion, start a new request. Reconnection is not built in for this endpoint.

Next steps

Structured output - receive typed JSON by providing a schema
Multi-turn sessions - maintain conversation context across requests
Create a response - review the basic request and response format