Multi-turn sessions

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 to a knowledge store 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
        "knowledge_store_id": "your_store_id"
16
    }
17
)
18
19
result = response.json()
20
session_id = result["session_id"]
21
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
        "knowledge_store_id": "your_store_id"
12
    }
13
)
14
15
# Third message - requests specific details
16
response = requests.post(
17
    f"{BASE_URL}/responses",
18
    headers=HEADERS,
19
    json={
20
        "model": "jockey1.0",
21
        "session_id": session_id,
22
        "input": [
23
            {"type": "message", "role": "user", "content": "Give me timestamps for the key moments in those videos"}
24
        ],
25
        "knowledge_store_id": "your_store_id"
26
    }
27
)

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