How do you enable xAI's Live Search in a Grok chat completions request?

## What Live Search is Most providers make retrieval your problem: you fetch documents, you stuff them into the prompt. xAI's differentiator is that live retrieval is a **first-class request parameter**. You ask for an answer and, in the same call, tell the server it may go and read the live web, X, news feeds or specified RSS links before answering. There is no separate search endpoint to orchestrate and no second round trip in your code. ## The request shape Search is off unless you opt in by sending a `search_parameters` object alongside the usual `model` and `messages`. The fields that matter: - **`mode`** — `"on"` searches on every request; `"auto"` lets the model judge whether the question needs fresh information; `"off"` disables it. `auto` is the sane default for a mixed workload, because most conversational turns do not need the web and every avoided search is money not spent. - **`sources`** — a list of objects each with a `type`: `web`, `x`, `news`, or `rss`. Leaving it out uses xAI's defaults; setting it explicitly is how you keep a support bot on documentation sites, or a social-listening tool on X. Individual source types accept their own narrowing options, such as excluding particular websites, restricting to named X handles, or listing RSS links. - **`from_date` / `to_date`** — an ISO date window that bounds how old retrieved material may be. Essential for "what happened this week" workloads and for reproducibility when you re-run an evaluation. - **`max_search_results`** — the ceiling on sources consulted for the call. This is your primary cost lever. - **`return_citations`** — controls whether the URLs behind the answer come back. Because none of this exists in OpenAI's schema, a typed OpenAI client cannot take it as a named argument: in Python it goes into `extra_body`, and over raw HTTP it is just another key in the JSON body. ## The response shape Two additions matter. First, a **`citations`** array of the URLs the model actually consulted — surface these in your UI, both because users trust cited answers more and because they are how you debug a wrong answer sourced from a bad page. Second, the **`usage`** object gains **`num_sources_used`**, the count of sources this request is billed for. ## The billing model This is the part candidates miss. Live Search is priced **per source consulted**, separately from input and output tokens. Two requests with identical token counts can differ several-fold in cost because one of them read a dozen pages. Practical consequences: - Log `num_sources_used` per request next to your token counts, and alert on its moving average. Token dashboards alone will silently under-report Live Search spend. - Prefer `mode: "auto"` over `"on"` unless the workload is definitionally about current events. - Set `max_search_results` deliberately rather than accepting the default; it is a hard ceiling on the per-request blast radius. - Retrieved content also enters the prompt, so searching inflates input tokens too — the cost is per-source plus the tokens those sources contribute. ## Operational caveats **Latency.** A searching request is slower by however long retrieval takes, and the variance is much wider than a pure generation call. Timeouts tuned for non-search traffic will start firing; size them per route, and stream so the user sees progress. **Non-determinism.** The live web changes. The same prompt at `temperature=0` can return different answers on different days because different pages were read. For evaluation suites, either disable search or pin `from_date`/`to_date` and accept that you are testing the pipeline, not a fixed corpus. **Trust and injection.** Retrieved pages are untrusted input. A page can contain text engineered to steer the model. Keep the model's tool permissions minimal on searching routes, never let a searched answer flow straight into a privileged action, and show citations so a human can sanity-check the provenance. **Do not confuse it with client-side tools.** Live Search is executed server-side by xAI; you neither implement nor see a tool-call round trip for it. If you also define your own function tools on the same request, those still come back as ordinary tool calls for your code to execute — the two mechanisms coexist but are not the same thing.