> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.twelvelabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://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. Each content part's `text` field may contain citation markers, each a number in square brackets such as `[1]`. The part's `annotations` array contains the citations that resolve these markers, in order of appearance; the 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.
* `usage`: An object containing token usage statistics, with `input_tokens` and `output_tokens` fields.
* `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

`incomplete_details` 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.

## 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": "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"
            }
          ]
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 12625,
    "output_tokens": 289
  },
  "created_at": "2026-07-11T03:13:57Z"
}
```