Guides

Live Search

The chat completion endpoint supports querying live data and considering those in generating responses. With this functionality, instead of orchestrating web search and LLM tool calls yourself, you can get chat responses with live data directly from the API.

Live search is available via the chat completions endpoint. It is turned off by default. Customers have control over the content they access, and we are not liable for any resulting damages or liabilities.

For more details, refer to search_parameters in API Reference - Chat completions.

For examples on search sources, jump to Data Sources and Parameters.

Live Search Pricing

Live Search costs $25 per 1,000 sources used. That means each source costs $0.025.

The number of sources used can be found in the response object, which contains a field called response.usage.num_sources_used.

Enabling Search

To enable search, you need to specify in your chat completions request an additional field search_parameters, with "mode" from one of "auto", "on", "off".

If you want to use Live Search with default values, you still need to specify an empty search_parameters.

Or if using xAI Python SDK:

The "mode" field sets the preference of data source:

"off": Disables search and uses the model without accessing additional information from data sources.
"auto" (default): Live search is available to the model, but the model automatically decides whether to perform live search.
"on": Enables live search.

The model decides which data source to use within the provided data sources, via the "sources" field in "search_parameters". If no "sources" is provided, live search will default to making web and X data available to the model.

For example, you can send the following request, where the model will decide whether to search in data:

Returning citations

The live search endpoint supports returning citations to the data sources used in the response in the form of a list of URLs. To enable this, you can set "return_citations": true in your search parameters. This field defaults to true.

Streaming behavior with citations

During streaming, you would get the chat response chunks as usual. The citations will be returned as a list of url strings in the field "citations" only in the last chunk. This is similar to how the usage data is returned with streaming.

Set date range of the search data

You can restrict the date range of search data used by specifying "from_date" and "to_date". This limits the data to the period from "from_date" to "to_date", including both dates.

Both fields need to be in ISO8601 format, e.g. "YYYY-MM-DD". If you're using the xAI Python SDK, the from_date and to_date fields can be passed as datetime.datetime objects to the SearchParameters class.

The fields can also be independently used. With only "from_date" specified, the data used will be from the "from_date" to today, and with only "to_date" specified, the data used will be all data till the "to_date".

Limit the maximum amount of data sources

You can set a limit on how many data sources will be considered in the query via "max_search_results". The default limit is 20.

Data sources and parameters

In "sources" of "search_parameters", you can add a list of sources to be potentially used in search. Each source is an object with source name and parameters for that source, with the name of the source in the "type" field.

If nothing is specified, the sources to be used will default to "web" and "x".

For example, the following enables web, X search, news and rss:

Overview of data sources and supported parameters

Data Source	Description	Supported Parameters
`"web"`	Searching on websites.	`"country"`, `"excluded_websites"`, `"allowed_websites"`, `"safe_search"`
`"x"`	Searching X posts.	`"included_x_handles"`, `"excluded_x_handles"`, `"post_favorite_count"`, `"post_view_count"`
`"news"`	Searching from news sources.	`"country"`, `"excluded_websites"`, `"safe_search"`
`"rss"`	Retrieving data from the RSS feed provided.	`"links"`

Parameter `"country"` (Supported by Web and News)

Sometimes you might want to include data from a specific country/region. To do so, you can add an ISO alpha-2 code of the country to "country" in "web" or "news" of the "sources".

Parameter `"excluded_websites"` (Supported by Web and News)

Use "excluded_websites"to exclude websites from the query. You can exclude a maximum of five websites.

This cannot be used with "allowed_websites" on the same search source.

Parameter `"allowed_websites"` (Supported by Web)

Use "allowed_websites"to allow only searching on these websites for the query. You can include a maximum of five websites.

This cannot be used with "excluded_websites" on the same search source.

Parameter `"included_x_handles"` (Supported by X)

Use "included_x_handles" to consider X posts only from a given list of X handles. The maximum number of handles you can include is 10.

This parameter cannot be set together with "excluded_x_handles".

Parameter `"excluded_x_handles"` (Supported by X)

Use "excluded_x_handles" to exclude X posts from a given list of X handles. The maximum number of handles you can exclude is 10.

This parameter cannot be set together with "included_x_handles".

To prevent the model from citing itself in its responses, the "grok" handle is automatically excluded by default. If you want to include posts from "grok" in your search, you must pass it explicitly in the "included_x_handles" parameter.