Maintain conversation context across multiple requests. Use multi-turn sessions when you want to ask follow-up questions, explore your videos and images iteratively, or build a chat interface that preserves context across turns. This guide covers how to start a session, continue it with follow-up messages, and build a reusable chat pattern.

Key concepts

Session: A server-side conversation state that Jockey maintains across requests. You do not need to resend previous messages. The session retains the full conversation history. Each response includes a session identifier that you pass on subsequent requests to continue the conversation.

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 # Step 1: Start a session by omitting session_id
6 response = client.responses.create(
7     knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
8     input=[{"type": "message", "role": "user", "content": "What are the main themes in these videos and images?"}],
9 )
10 session_id = response.session_id
11 print(f"Session started: {session_id}")
12 
13 # Step 2: Continue the conversation with the session_id from the previous response
14 response = client.responses.create(
15     knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
16     session_id=session_id,
17     input=[{"type": "message", "role": "user", "content": "Which items best represent the first theme?"}],
18 )

Code explanation

Python

Node.js

Start a session

Omit the session_id field on the first request. Jockey creates a new session and returns its identifier in the response.
Function call: You call the responses.create method.
Parameters:

knowledge_store_id: The unique identifier of the knowledge store to reason over.
input: An array of input items. Each item is a message you send to Jockey.

Return value: An object of type ResponseObject. Read the session_id field and store it to continue the conversation.

Continue the conversation

Pass the session_id from the previous response to send a follow-up message. Jockey uses the full conversation history, so you do not resend earlier messages.
Function call: You call the responses.create method.
Parameters:

knowledge_store_id: The unique identifier of the knowledge store. Keep it the same across turns.
session_id: The session identifier from the previous response.
input: An array of input items. Each item is a message you send to Jockey.

Return value: An object of type ResponseObject. Reuse the same session_id for later turns.

Build a reusable chat function

For chat UIs or interactive applications, wrap the session logic in a function. The function creates a new session on the first call and reuses it for subsequent calls.

1 session_id = None
2 
3 def chat(message, store_id):
4     global session_id
5 
6     response = client.responses.create(
7         knowledge_store_id=store_id,
8         session_id=session_id,
9         input=[{"type": "message", "role": "user", "content": message}],
10     )
11     session_id = response.session_id
12 
13     # Extract text from response
14     for output in response.output:
15         if output.type == "message":
16             for content in output.content:
17                 return content.text

Common pitfalls

Store the session identifier. Without the session_id value you cannot continue a conversation, and must start a new one.
Query the same knowledge store across turns. A session is tied to one store; pass the same knowledge_store_id on every turn.
Do not resend conversation history. The session stores it server-side.

Next steps

Streaming - combine multi-turn sessions with real-time streaming
Structured output - receive typed JSON responses within a session
Create a response - review the basic request and response format

Multi-turn sessions