Skip to navigation
Agents (Jockey)Responses

The response object

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. 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.
  • 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.
  • 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

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