> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/v1.3/agents/guides/create-a-response/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.twelvelabs.io/_mcp/server.

# Create a response

This guide shows you how to generate a response from a knowledge store and customize [Jockey](/v1.3/agents/concepts/jockey)'s behavior for a specific domain. You can also use this endpoint for [agentic search](/v1.3/agents/recipes/agentic-search): have Jockey reason over your content to find and explain matches. For direct, single-call retrieval of ranked clips and images, use [Search a knowledge store](/v1.3/agents/guides/search-a-knowledge-store).

**Key features**:

* **Corpus-level reasoning**: Answers questions by reasoning across every item in a knowledge store.
* **Domain-specific behavior**: Adapts responses to your domain or task through per-request instructions.
* **Multi-turn sessions**: Maintains conversation context across follow-up requests.
* **Streaming**: Returns tokens in real time instead of waiting for the full response.
* **Structured output**: Returns typed JSON responses when you provide a JSON Schema.
* **Intermediate outputs**: Returns Jockey's reasoning steps alongside the final answer.

**Use cases**:

* **Corpus overview**: Generate responses that reason across all your videos and images.
* **Entity extraction**: Identify people, places, objects, and other entities across a knowledge store.
* **Search and discovery**: Find moments in videos and matching images by describing what you want in natural language.
* **Content organization**: Categorize videos and images by themes, topics, formats, or other useful dimensions.
* **Cross-video tracking**: Track a subject across multiple videos and reconstruct a timeline of appearances.
* **Content enrichment**: Analyze existing content through a specific domain lens or schema.

# Key concepts

* **Knowledge store**: A persistent store of your videos and images plus the understanding the platform derives from them - spatiotemporal context, a typed ontology, and embeddings - that together enable corpus-level reasoning.
* **Instructions**: A system-level prompt that shapes Jockey's behavior for a specific domain or task. Same endpoint, different results depending on the instructions you provide.

# Prerequisites

* You've already uploaded your content, and the asset has reached the `ready` status. See the [Upload content](/v1.3/agents/guides/upload-content) page for details.
* You've already created a knowledge store. See the [Create a knowledge store](/v1.3/agents/guides/create-a-knowledge-store) page for details.
* You've already added at least one asset to a knowledge store, and the knowledge store item has reached the `ready` status. See the [Add assets to a knowledge store](/v1.3/agents/guides/add-assets) page for details.

# Example

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

**`Python`**

```python Python maxlines=22
from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

# Create a response
response = client.responses.create(
    knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
    input=[{"type": "message", "role": "user", "content": "What are the main themes across these videos and images?"}],
    # session_id=...,  # Optional. Continue a multi-turn conversation. See Multi-turn sessions.
    # instructions=...,  # Optional. Add a per-request system prompt. See Customize behavior with instructions.
    # include=...,  # Optional. Return intermediate reasoning steps. See Inspect intermediate outputs.
    # selections=...,  # Optional. Restrict the request to specific items or item collections.
    # text=...,  # Optional. Return typed JSON output. See Structured output.
)

# Read the response
print(f"ID: {response.id}")
print(f"Session: {response.session_id}")

for output in response.output:
    if output.type == "message":
        for content in output.content:
            print(content.text)
            # The end_index field is inclusive, so slice to end_index + 1.
            for annotation in content.annotations:
                marker = content.text[annotation.start_index : annotation.end_index + 1]
                print(f"  {marker} -> {annotation.type} {annotation.title or ''}")

print(f"Tokens: {response.usage}")
```

**`Node.js`**

```javascript Node.js maxlines=22
import { TwelveLabs } from "twelvelabs-js";

const client = new TwelveLabs({ apiKey: "<YOUR_API_KEY>" });

// Create a response
const response = await client.responses.create({
  knowledgeStoreId: "<YOUR_KNOWLEDGE_STORE_ID>",
  input: [{ type: "message", role: "user", content: "What are the main themes across these videos and images?" }],
  // sessionId: ...,  // Optional. Continue a multi-turn conversation. See Multi-turn sessions.
  // instructions: ...,  // Optional. Add a per-request system prompt. See Customize behavior with instructions.
  // include: ...,  // Optional. Return intermediate reasoning steps. See Inspect intermediate outputs.
  // selections: ...,  // Optional. Restrict the request to specific items or item collections.
  // text: ...,  // Optional. Return typed JSON output. See Structured output.
});

// Read the response
console.log(`ID: ${response.id}`);
console.log(`Session: ${response.sessionId}`);

for (const output of response.output ?? []) {
  if (output.type === "message") {
    for (const content of output.content ?? []) {
      console.log(content.text);
      // The endIndex field is inclusive, so slice to endIndex + 1.
      for (const annotation of content.annotations) {
        const marker = content.text.slice(annotation.startIndex, annotation.endIndex + 1);
        console.log(`  ${marker} -> ${annotation.type} ${annotation.title ?? ""}`);
      }
    }
  }
}

console.log(`Tokens: ${JSON.stringify(response.usage)}`);
```

# Code explanation

#### Python

To generate a response, call the [`responses.create`](/v1.3/sdk-reference/python/responses#create-a-response) method with a natural-language message in the `input` array and the knowledge store to reason over. This example prints the response identifier, session identifier, generated text, and token usage to the standard output.\

**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](/v1.3/agents/guides/create-a-response/multi-turn-sessions) page.
* *(Optional)* `instructions`: Adds a per-request system prompt that shapes Jockey's behavior for your domain or task. See the [Customize behavior with instructions](#customize-behavior-with-instructions) 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 [Inspect intermediate outputs](#inspect-intermediate-outputs) section 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](/v1.3/agents/guides/create-a-response/structured-output) page for details.\


**Return value**: An object of type `ResponseObject` containing, among other information, the following fields:

* `id`: The unique identifier of the response.
* `session_id`: The session identifier. Pass it in a follow-up request to continue the conversation. See the [Multi-turn sessions](/v1.3/agents/guides/create-a-response/multi-turn-sessions) page for details.
* `status`: The status of the response. The possible values are `completed`, `failed`, `in_progress`, and `incomplete`.
* `output`: The response output items. Iterate the array and read the `text` field of each content part in a `message` item to extract the generated text. The text may contain citation markers, each a number in square brackets such as `[1]`. Each content part also has an `annotations` array that resolves these markers; the array is always present and may be empty.
* `usage`: Token usage statistics, including the `input_tokens` and `output_tokens` fields.

To stream the response as it is generated, call the `create_stream` method instead. See the [Streaming](/v1.3/agents/guides/create-a-response/streaming) page for details.

#### Node.js

To generate a response, call the [`responses.create`](/v1.3/sdk-reference/node-js/responses#create-a-response) method with a natural-language message in the `input` array and the knowledge store to reason over. You pass all parameters as properties of a single object. This example prints the response identifier, session identifier, generated text, and token usage to the standard output.\

**Parameters**:

* `knowledgeStoreId`: 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)* `sessionId`: Continues a multi-turn conversation. Pass the identifier from a previous response. See the [Multi-turn sessions](/v1.3/agents/guides/create-a-response/multi-turn-sessions) page.
* *(Optional)* `instructions`: Adds a per-request system prompt that shapes Jockey's behavior for your domain or task. See the [Customize behavior with instructions](#customize-behavior-with-instructions) 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 [Inspect intermediate outputs](#inspect-intermediate-outputs) section 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](/v1.3/agents/guides/create-a-response/structured-output) page for details.\


**Return value**: An `HttpResponsePromise` that resolves to an object of type `ResponseObject` containing, among other information, the following fields:

* `id`: The unique identifier of the response.
* `sessionId`: The session identifier. Pass it in a follow-up request to continue the conversation. See the [Multi-turn sessions](/v1.3/agents/guides/create-a-response/multi-turn-sessions) page for details.
* `status`: The status of the response. The possible values are `completed`, `failed`, `in_progress`, and `incomplete`.
* `output`: The response output items. Iterate the array and read the `text` field of each content part in a `message` item to extract the generated text. The text may contain citation markers, each a number in square brackets such as `[1]`. Each content part also has an `annotations` array that resolves these markers; the array is always present and may be empty.
* `usage`: Token usage statistics, including the `inputTokens` and `outputTokens` fields.

To stream the response as it is generated, call the `createStream` method instead. See the [Streaming](/v1.3/agents/guides/create-a-response/streaming) page for details.

# Example response

The response object contains the generated text along with the session identifier and token usage:

```json
{
  "id": "resp_abc123",
  "session_id": "sess_xyz789",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "phase": "final_answer",
      "content": [{"type": "output_text", "text": "The main themes across your videos and images include...", "annotations": []}]
    }
  ],
  "usage": {"input_tokens": 1250, "output_tokens": 340}
}
```

# Customize behavior with instructions

Add the `instructions` field to specialize Jockey for your domain. Same endpoint, different results depending on what you provide.

**`Python`**

```python Python maxlines=12
response = client.responses.create(
    knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
    instructions="You are a sports analyst. Focus on player performance, tactics, and key moments.",
    input=[{"type": "message", "role": "user", "content": "Summarize the key plays from this game"}],
)
```

**`Node.js`**

```javascript Node.js maxlines=12
const response = await client.responses.create({
  knowledgeStoreId: "<YOUR_KNOWLEDGE_STORE_ID>",
  instructions: "You are a sports analyst. Focus on player performance, tactics, and key moments.",
  input: [{ type: "message", role: "user", content: "Summarize the key plays from this game" }],
});
```

Swap the `instructions` field to reshape Jockey for different contexts:

| Domain     | Example instructions                                                                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------- |
| Security   | "You are a security analyst. Prioritize temporal accuracy and flag low-confidence identifications."               |
| Media      | "You are an editorial assistant. Focus on visual quality, pacing, and narrative arc."                             |
| Compliance | "You are a compliance reviewer. Identify claims, disclaimers, and required disclosures."                          |
| Education  | "You are a learning designer. Analyze pedagogical effectiveness, teaching methods, and assessment opportunities." |

# Inspect intermediate outputs

Jockey performs multi-step reasoning internally: searching, analyzing, and synthesizing across your videos and images. Add `"intermediate_outputs"` to the `include` array to see these reasoning steps alongside the final answer. This is useful for debugging or understanding how Jockey produced the answer.

**`Python`**

```python Python maxlines=12
response = client.responses.create(
    knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
    input=[{"type": "message", "role": "user", "content": "What are the main themes?"}],
    include=["intermediate_outputs"],
)
```

**`Node.js`**

```javascript Node.js maxlines=12
const response = await client.responses.create({
  knowledgeStoreId: "<YOUR_KNOWLEDGE_STORE_ID>",
  input: [{ type: "message", role: "user", content: "What are the main themes?" }],
  include: ["intermediate_outputs"],
});
```

# Capabilities

The Responses API handles many tasks through the same endpoint. These examples are not exhaustive.

| Capability           | Example prompt                                                         | Recipe                                                                           |
| -------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Corpus overview      | "Give me a comprehensive overview of these videos and images"          | [Generate a corpus overview](/v1.3/agents/recipes/get-a-corpus-overview)         |
| Entity extraction    | "List every person, place, and object across all videos and images"    | [Extract entities](/v1.3/agents/recipes/extract-entities)                        |
| Search and discovery | "Find all moments where someone is presenting to an audience"          | [Agentic search](/v1.3/agents/recipes/agentic-search)                            |
| Content organization | "What are the best ways to organize these videos and images?"          | [Find organization axes](/v1.3/agents/recipes/find-organization-axes)            |
| Cross-video tracking | "Track the person in the blue jacket across all footage"               | [Cross-video entity tracking](/v1.3/agents/recipes/track-entities-across-videos) |
| Content enrichment   | "Analyze these videos and images through the lens of brand perception" | [Enrich content](/v1.3/agents/recipes/enrich-content)                            |

# Common pitfalls

* **Index at least one item before you query.** A knowledge store with no items in the `ready` state has no content for the request to draw on.
* **Include the knowledge store identifier.** Every request must include the `knowledge_store_id` field.

# Next steps

* [Streaming](/v1.3/agents/guides/create-a-response/streaming) - receive tokens in real time instead of waiting for the full response
* [Structured output](/v1.3/agents/guides/create-a-response/structured-output) - receive typed JSON by providing a schema
* [Multi-turn sessions](/v1.3/agents/guides/create-a-response/multi-turn-sessions) - maintain conversation context across requests

# Jupyter notebook

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/jockey/guides/querying.ipynb)

## Docs

- [Streaming](https://docs.twelvelabs.io/agents/guides/create-a-response/streaming.md)
- [Structured output](https://docs.twelvelabs.io/agents/guides/create-a-response/structured-output.md)
- [Multi-turn sessions](https://docs.twelvelabs.io/agents/guides/create-a-response/multi-turn-sessions.md)