> This page is for version v1.3 (default).
> For other versions, use one of these documentation indexes:
> - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt

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

# The response object

> Response object schema.

A response is [Jockey](/v1.3/agents/concepts/jockey)'s reply to a request, generated by reasoning over the content in a knowledge store.

The object is composed of the following fields:

* `id`: A string representing the unique identifier of the response.
* `knowledge_store_id`: A string representing the unique identifier of the knowledge store the response was generated against.
* `session_id`: A string representing the session identifier for the conversation. Pass it in subsequent requests to continue the multi-turn conversation.
* `type`: A string representing the object type. The value is always `response`.
* `object`: A string with the same value as `type`. Only the response itself has an `object` field; output items, annotations, and stream events are identified by `type` alone and have no `object` field.
* `status`: A string representing the status of the response. See the [Response statuses](#response-statuses) section for the meaning of each value.
* `output`: An array of output items. By default, only the final message is included. To also receive function call items, set `include` to `["intermediate_outputs"]` in the request. Each message item has a `phase` field whose value is `commentary` for intermediate output or `final_answer` for the answer; a message without `phase` is the final answer. The `text` field of each content part may contain citation markers, each a number in square brackets such as `[1]`. The `annotations` array of the part contains the citations. Each citation identifies a span of the `text` field and the source it cites. Media citations use the markers, and a web citation (`url_citation`) can cover text that is not a marker. The `annotations` array is always present and may be empty. For the full list of fields on each citation, see [Create a response](/v1.3/api-reference/responses/create).
* `incomplete_details`: The reason the response was truncated before the answer was complete. Always present; contains a value only when `status` is `incomplete`, and `null` on every other status. See the [Incomplete responses](#incomplete-responses) section.
* `billing`: The billing information for this response. Its `amount` field is the cost of the response in US dollars, as a decimal string with six decimal places, and its `currency` field is `USD`. The amount is the list price, before any discount on your account. An incomplete response counts the work done before it stopped, and `amount` is `null` when the cost could not be determined at the time the response finished; your invoice shows the charge. A request that fails is not charged. Only a finished response carries `billing`: the last event of a stream (`response.completed` or `response.failed`) and the non-streamed response. Earlier stream events do not. This amount is informational: it is the list price, before your plan and any discount on your account. Your invoice is the authoritative record of charges.
* `created_at`: A string representing the date and time, in the RFC 3339 format, when the response was created.

## Response statuses

The `status` field of a response has one of the following values:

* `in_progress`: The response is being generated.
* `completed`: The response has been generated successfully.
* `incomplete`: The response ended before the answer was complete. Read `incomplete_details.reason` to find out why.
* `failed`: The response generation has failed.

## Incomplete responses

The `incomplete_details` field is always present and is `null` on every status except `incomplete`,
so `null` means the answer was not truncated, not that the platform does not report the
reason. When it contains a value, its `reason` says what stopped the answer:

* `max_output_tokens`: the answer reached the output token limit. The text in `output`
  is an incomplete answer, not the full one.

Treat a value you do not recognize as an incomplete answer for an unknown reason, not as
an error.

## Citations

Each citation identifies a span of the answer text and the source that supports it. Media citations point to knowledge store items and collections, and web citations point to public web sources.

The platform can add new citation types. If you encounter a citation type you do not recognize, keep the response text and display the citations you do recognize.

Citation offsets count Unicode code points, and both bounds are inclusive. Use the offsets of an annotation to locate the text it covers. When multiple annotations cover the same text, keep the source of each one.

## Example

```json
{
  "id": "resp_019f4f2a-b69e-7812-b20f-6ea6d644ceff",
  "type": "response",
  "object": "response",
  "status": "completed",
  "incomplete_details": null,
  "session_id": "sess_019f4f2a-b69b-7a01-9018-cc51681121ea",
  "knowledge_store_id": "ks_019ebcf4-7e08-7201-b69c-69e0c1e6ae56",
  "output": [
    {
      "type": "message",
      "id": "msg_sess_019f4f2a-b69b-7a01-9018-cc51681121ea_0",
      "status": "completed",
      "role": "assistant",
      "phase": "final_answer",
      "content": [
        {
          "type": "output_text",
          "text": "The video captures a heated sideline moment during Super Bowl LVIII: after a fumble, Travis Kelce approaches head coach Andy Reid, visibly frustrated, and briefly bumps him before being restrained by a teammate [1].",
          "annotations": [
            {
              "type": "url_citation",
              "start_index": 51,
              "end_index": 66,
              "url": "https://example.com/news/super-bowl-lviii",
              "title": "Super Bowl LVIII recap"
            },
            {
              "type": "video_citation",
              "start_index": 211,
              "end_index": 213,
              "item_id": "ksi_069e9870-3c4d-7abc-9012-3456789abcde",
              "start_sec": 0.0,
              "end_sec": 9.0,
              "title": "Super Bowl LVIII sideline",
              "thumbnail_url": "https://example.com/thumbnail.jpg",
              "hls_url": "https://example.com/stream.m3u8"
            }
          ]
        }
      ]
    }
  ],
  "billing": {
    "amount": "0.020912",
    "currency": "USD"
  },
  "created_at": "2026-07-11T03:13:57Z"
}
```