The response object | TwelveLabs

A response is 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 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.
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 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

{
  "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"
}