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 you how to stream a response and read the events it returns.

Key concepts

Events: The stream arrives as a series of events. Most contain a small fragment of the generated text, which you concatenate to build the full response; a final event marks the end of the stream. The SDK manages the underlying connection, so you handle each event as it arrives.

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.

from twelvelabs import TwelveLabs
client = TwelveLabs(api_key="<YOUR_API_KEY>")
stream = client.responses.create_stream(
    knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
    input=[{"type": "message", "role": "user", "content": "Describe what these videos and images show"}],
    # session_id=...,  # Optional. Continue a multi-turn conversation. See Multi-turn sessions.
    # instructions=...,  # Optional. Add a per-request system prompt. See Create a response.
    # include=...,  # Optional. Request activity summaries. See below.
    # selections=...,  # Optional. Restrict the request to specific items or item collections.
    # text=...,  # Optional. Return typed JSON output. See Structured output.
)
for event in stream:
    if event.type == "response.output_text.delta":
        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 activity_summaries for live activity summaries. See Choose what to include for details.
(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. Citations come later than the text: the annotations array is empty while a content part is being generated, and the response.content_part.done event contains the completed part with all of its citations.

Example response

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

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

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

The response.content_part.done event marks the point where a content part is complete. It contains the full text and all citations:

{"type": "response.content_part.done", "item_id": "msg_abc123", "output_index": 0, "content_index": 0, "part": {"type": "output_text", "text": "...", "annotations": []}}

Show activity summaries

Set stream to true and include to ["activity_summaries"] to receive short progress labels while Jockey works. For SDK streaming methods, pass include=["activity_summaries"] in Python or include: ["activity_summaries"] in Node.js; the streaming method sets stream for you. Requesting activity_summaries without streaming returns HTTP 400 with error code parameter_invalid before the stream starts. Do not combine activity_summaries with intermediate_outputs.

{
  "knowledge_store_id": "<YOUR_KNOWLEDGE_STORE_ID>",
  "input": [{"type": "message", "role": "user", "content": "Find clips showing bicycles"}],
  "stream": true,
  "include": ["activity_summaries"]
}

Activity events arrive alongside the answer stream:

event: jockey:activity
data: {"type":"jockey:activity","sequence_number":7,"activity":{"id":"step_1","revision":1,"status":"completed","summary":"Finding relevant footage"}}

Statuses are in_progress (running), completed (finished), incomplete (stopped before finishing), or failed. Activity status is independent of response status; a failed activity does not necessarily fail the response.

Activities are stream-only and are not included in the response’s output array or saved message history. Consume the stream until response.completed or response.failed; do not infer response completion from an activity status.

Legacy intermediate outputs

include: ["intermediate_outputs"] is deprecated. It retains its existing behavior: sanitized intermediate messages, function calls, and function-call results are emitted through output-item events and included in the final output. Non-streaming requests also retain these items. For a progress display, migrate to activity_summaries and consume jockey:activity events instead. The two include options cannot be combined.

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

Streaming