Generate responses that cite public web sources. Jockey can search the public web for information that supports its answer and cite the sources it uses. This guide shows you how to enable web search and read the url_citation annotations it returns.

Prerequisites

• You’ve already uploaded your videos and images, and the assets have reached the ready status. See the Upload content page for details.
• You’ve already created a knowledge store. See the Create a knowledge store page for details.
• You’ve already added at least one asset to the knowledge store, and the item has reached the ready status. See the Add assets to a knowledge store page for details.
• You’ve already read the Create a response page and understand the basic request and response format.

Enable web search

Include { "type": "jockey:web_search" } in the tools array to allow web search. Jockey decides whether to use an available tool, so enabling web search does not guarantee a search. To make a search more likely, explicitly tell Jockey what information to look up in input or instructions. A prompt that asks Jockey to search the web does not enable web search by itself. If you omit tools or pass [], Jockey cannot search public web sources, even when the prompt requests it.

The tools setting applies to each request on its own, including requests that continue a session.

Example

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

from twelvelabs import TwelveLabs
client = TwelveLabs(api_key="<YOUR_API_KEY>")
response = client.responses.create(
    knowledge_store_id="<YOUR_KNOWLEDGE_STORE_ID>",
    input=[{"type": "message", "role": "user", "content": "Identify a main theme in these videos and images, then search the web for recent information about that theme and cite your sources."}],
    tools=[{"type": "jockey:web_search"}],
)
# Read the response
for item in response.output or []:
    if item.type == "message":
        for part in item.content or []:
            print(part.text)
            for annotation in part.annotations:
                span = part.text[annotation.start_index : annotation.end_index + 1]
                print(f"  {span} -> {annotation.type} {annotation.url or ''}")

Code explanation

Example response

The message in the output array contains the answer text with its citations. This response cites a public web source and a moment from a video in the knowledge store:

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

The web citation covers Super Bowl LVIII, a span of ordinary text. The video citation covers the [1] marker. Both bounds are inclusive and count Unicode code points.

Common pitfalls

• Treat unknown citation types as un-displayable, not as errors. The platform can add new citation types. When you encounter a type you do not recognize, keep the response text and display the citations you do recognize.
• Retry without an unavailable tool. If a requested tool is unavailable, the request fails with HTTP 422 and code parameter_invalid. Remove the unavailable tool from the tools array and retry. For web search, remove the entry with type: "jockey:web_search".

Next steps

• Create a response - customize Jockey’s behavior with instructions, restrict the request to specific items with selections, and inspect intermediate reasoning steps
• Streaming - receive tokens in real time; citations arrive with the completed content part
• Multi-turn sessions - maintain conversation context across requests; tools applies to each request on its own