Multi-turn sessions | TwelveLabs

Maintain conversation context across multiple requests. Use multi-turn sessions when you want to ask follow-up questions, explore a video collection 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 - Jockey remembers the full conversation history within a session. Each response includes a session_id that you pass on subsequent requests to continue the conversation.

Prerequisites

You’ve already uploaded your content, and the asset has 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 page for details.
You’ve already read the Create a response page and understand the basic request and response format.

Start a session

Omit session_id on your first request. Jockey creates a new session and returns its ID in the response. Store this ID for follow-up requests.

1 import requests
2 
3 HEADERS = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}
4 BASE_URL = "https://api.twelvelabs.io/v1.3"
5 
6 # First message - starts a new session
7 response = requests.post(
8     f"{BASE_URL}/responses",
9     headers=HEADERS,
10     json={
11         "model": "jockey1.0",
12         "input": [
13             {"type": "message", "role": "user", "content": "What are the main themes in these videos?"}
14         ],
15         "tools": [
16             {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
17         ]
18     }
19 )
20 
21 result = response.json()
22 session_id = result["session_id"]
23 print(f"Session started: {session_id}")

Continue the conversation

Pass the session_id from the previous response to send follow-up messages. Jockey uses the full conversation history to inform its answers, so you can reference earlier results without repeating context.

1 # Second message - drills into the first theme
2 response = requests.post(
3     f"{BASE_URL}/responses",
4     headers=HEADERS,
5     json={
6         "model": "jockey1.0",
7         "session_id": session_id,
8         "input": [
9             {"type": "message", "role": "user", "content": "Which videos best represent the first theme?"}
10         ],
11         "tools": [
12             {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
13         ]
14     }
15 )
16 
17 # Third message - requests specific details
18 response = requests.post(
19     f"{BASE_URL}/responses",
20     headers=HEADERS,
21     json={
22         "model": "jockey1.0",
23         "session_id": session_id,
24         "input": [
25             {"type": "message", "role": "user", "content": "Give me timestamps for the key moments in those videos"}
26         ],
27         "tools": [
28             {"type": "knowledge_store", "knowledge_store_id": "your_store_id"}
29         ]
30     }
31 )

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     payload = {
7         "model": "jockey1.0",
8         "input": [
9             {"type": "message", "role": "user", "content": message}
10         ],
11         "tools": [
12             {"type": "knowledge_store", "knowledge_store_id": store_id}
13         ]
14     }
15 
16     if session_id:
17         payload["session_id"] = session_id
18 
19     response = requests.post(
20         f"{BASE_URL}/responses",
21         headers=HEADERS,
22         json=payload
23     )
24 
25     result = response.json()
26     session_id = result["session_id"]
27 
28     # Extract text from response
29     for output in result["output"]:
30         if output["type"] == "message":
31             for content in output["content"]:
32                 return content["text"]

Common pitfalls

Store the session_id. If you lose it, you cannot continue the conversation. Start a new session instead.
Use the same knowledge store. Keep the same knowledge_store_id across turns for consistent results.
Session state is server-side. You do not need to resend conversation history - Jockey tracks it for you.

Next steps

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

Jupyter notebook

Download the notebook to run this guide interactively.

API reference

POST /responses