The training data for large language models has a knowledge cutoff date, preventing them from answering real-time questions. Enabling web search lets the model retrieve real-time data and accurately answer time-sensitive questions, such as stock prices, weather forecasts, and breaking news.
Usage
You can enable web search using the four API calls below, each requiring different parameters.
Some models, such as glm-5.2 and kimi-k3, support web search only through the Responses API.
- OpenAI-compatible: Responses API
- OpenAI-compatible: Chat Completions API
- DashScope
- Anthropic-compatible
web_search tool to the tools parameter to enable web search.The Responses API supports only some models. For the supported models, see Web search with Responses API.
Web search with multimodal models
The Qwen3.8 Max, Flash, and open-source series, Qwen3.7-Flash, Qwen3.7-Plus, the Qwen3.6 series, and the Qwen3.5 series (including qwen3.5-plus, qwen3.5-flash, the qwen3.5-omni series, and Qwen open-source models) accept multimodal input (images, video) and are multimodal models. Call these models through the multimodal API (the multimodal-generation endpoint): use MultiModalConversation in both Python and Java, not Generation (the text-generation endpoint), which is for text-only models. For the basics of calling multimodal models, see the Visual reasoning and Image and video understanding topics.
Search strategy support varies by series: the qwen3.5-omni series supports only the agent strategy; qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, and qwen3.8-27b do not support the agent strategy on the multimodal API (use the default turbo or max)—to run Qwen3.8 with agent-style retrieval, use Web search with the Responses API; other models listed in this section support the turbo, max, and agent strategies.
Calling the multimodal models above withGeneration(thetext-generationendpoint) returns400 url error, please check url. UseMultiModalConversation(themultimodal-generationendpoint) instead.In the Java SDK,MultiModalConversationParamprovidesenableSearch(true)to enable web search, but does not provide asearchOptions()method. Inject the search strategy and other options through the genericparameter("search_options", ...)method. In Python,MultiModalConversation.callacceptssearch_optionsdirectly.Web search on multimodal models requires streaming calls (usestreamCallin Java, or setstream=Truein Python); otherwise the request returns aNon-streaming mode does not support Web Searcherror.
Supported models
The following models support web search. Models with multimodal input (the Qwen3.8 series, Qwen3.7-Flash/Plus, the Qwen3.6 series, the Qwen3.5 series, and Qwen open-source models) must be called through the multimodal API. See Web search with multimodal models.
- China (Beijing)
- Singapore
- Global
-
Qwen
- Qwen3.8 series: qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b (
search_strategy: agentis not supported; for agent-style retrieval, use theweb_searchtool through the Responses API) - Qwen3.7 series: qwen3.7-max, qwen3.7-max-preview, qwen3.7-max-2026-05-17 and later snapshots, qwen3.7-plus, qwen3.7-plus-2026-05-26 and later snapshots, qwen3.7-flash, qwen3.7-flash-2026-07-15 and later snapshots
- Qwen3.6 series: qwen3.6-plus, qwen3.6-plus-2026-04-02 and later snapshots, qwen3.6-flash, qwen3.6-flash-2026-04-16 and later snapshots, qwen3.6-27b, qwen3.6-35b-a3b
- Qwen3.5 series: qwen3.5-plus, qwen3.5-plus-2026-02-15 and later snapshots, qwen3.5-flash, qwen3.5-flash-2026-02-23 and later snapshots, qwen3.5-27b, qwen3.5-35b-a3b, qwen3.5-122b-a10b, qwen3.5-397b-a17b
- Qwen-Max: qwen-max and later snapshots
- Qwen-Plus: qwen-plus, qwen-plus-latest, qwen-plus-2025-07-14 and later snapshots
- Qwen-Flash: qwen-flash, qwen-flash-2025-07-28 and later snapshots
- Qwen-Omni: qwen3.8-omni-flash, qwen3.5-omni-plus, qwen3.5-omni-plus-2026-03-15, qwen3.5-omni-flash, qwen3.5-omni-flash-2026-03-15 (the search strategy must be set to
agent) - Qwen-Omni-Realtime: qwen3.8-omni-flash-realtime, qwen3.5-omni-plus-realtime, qwen3.5-omni-plus-realtime-2026-03-15, qwen3.5-omni-flash-realtime, qwen3.5-omni-flash-realtime-2026-03-15 (the search strategy must be set to
agent) - Role-playing: qwen-plus-character, qwen-flash-character, qwen-flash-character-2026-02-26 (the
agentstrategy is not supported)
- Qwen3.8 series: qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, qwen3.8-27b (
-
Third-party models
- DeepSeek: deepseek-v4-pro, deepseek-v4-pro-0813, deepseek-v4-flash-0731 (the deepseek-v4 series also supports the Responses API)
- GLM: glm-5.2 (supported only by the Responses API)
- Kimi: kimi-k3 (supported only by the Responses API)
Quick start
This example shows how to query weather information using web search.
- OpenAI compatible
- DashScope
enable_search=True to enable web search. For qwen3.8-omni-flash, also set search_options={"search_strategy": "agent"}. When using the Responses API, configure tools=[{"type": "web_search"}] instead. See Web search with the Responses API.- Python
- Node.js
- Curl
Sample response
Core features
In addition to basic search, web search supports advanced features such as forced search, search policy settings, and returning search sources. The DashScope protocol supports all of these features. By contrast, the OpenAI-compatible protocol does not support returning search sources or superscript annotation. The table below details these differences.
Feature | DashScope | OpenAI compatible: Chat completions | OpenAI compatible: Responses |
|---|---|---|---|
basic web search | Supported | Supported | Supported |
forced web search | Supported | Supported | Not supported |
search volume strategy | Supported | Supported | Not supported |
domain-specific search | Supported | Supported | Not supported |
search timeliness | Supported | Supported | Not supported |
source site restriction | Supported | Supported | Not supported |
natural language scope control | Supported | Supported | Not supported |
search source citation | Supported | Not supported | Not supported |
citation markers | Supported | Not supported | Not supported |
early source return | Supported | Not supported | Not supported |
mixed text and image output | Supported | Supported | Not supported |
Search strategy
Use the search_strategy parameter to balance cost, quality, and response speed.
Valid values for search_strategy:
-
turbo(default): Balances response speed and search quality. Suitable for most scenarios. -
max: Uses a more comprehensive search strategy that queries multiple search engines for more detailed results but may increase response time. -
agent: Integrates information over multiple rounds by repeatedly calling the web search tool and the large model.This strategy is applicable to the Qwen3.5 series (including open-source and Omni models), the Qwen3.6 series, and the Qwen3.7 series. Streaming calls are required when using the text endpoint. Qwen3.8-Omni-Flash also supports this strategy through Chat Completions.
qwen3.8-max,qwen3.8-max-0902,qwen3.8-flash,qwen3.8-2.4t-a95b, andqwen3.8-27bdo not supportsearch_strategy: agenton Chat Completions or DashScope, but they can achieve equivalent agent-style multi-turn retrieval through theweb_searchtool on the Responses API. Role-playing models do not support theagentstrategy.When this strategy is enabled, only return search sources (
enable_source: true) is supported. Other web search features are unavailable.Enabling this strategy incurs an additional fee per call. For more information, see billing.
-
agent_max: Expands on theagentstrategy by adding support for the web extractor. For more information, see web extractor.When this strategy is enabled, only return search sources (
enable_source: true) is supported. Other web search features are unavailable.Enabling this strategy incurs an additional fee per call. For more information, see billing.
turbo strategy for routine queries. For high-precision tasks like research or report generation that require multi-source cross-validation, choose the max or agent strategy. The agent strategy is particularly effective for queries in English.
- OpenAI compatible
- DashScope
- Python
- Node.js
- curl
Sample response
Forced web search
By default, the model decides whether to perform a web search. For use cases that rely on real-time information, you can set the forced_search parameter to true to force a web search.
Valid values for forced_search:
true: Forces a web search.false(default): The model decides whether to perform a web search.
- OpenAI compatible
- DashScope
- Python
- Node.js
- Curl
enable_search in extra_body. For the Node.js SDK, pass it as a top-level parameter.Sample response
Source citations
You can configure web search to include source links and citation markers in responses to make information easier to trace.
-
Return sources: Set
enable_source: true. Thesearch_infofield in the response will then contain a list of search results. -
Enable citation markers: When
enable_sourceis set totrue, setenable_citation: trueto include citation markers, such as[1], in the response. -
Set the citation style: Use the
citation_formatparameter. Available options include:"[<number>]"(default): The style is[1]."[ref_<number>]": The style is[ref_1].
Models such as glm-5.2 and kimi-k3 support only the web search feature of the Responses API. With the Responses API, search sources are returned automatically in the response (see Get search sources), but the enable_citation citation markers are not supported (no [1] markers are inserted into the response content).
- Python
- Java
- curl
Sample response
Domain-specific search
Queries in vertical domains such as weather and stocks require high data accuracy, and general web search results may not be precise enough.
When domain-specific search is enabled, the model prioritizes vertical data sources to return more accurate results.
Set enable_search_extension to true to enable this feature.
Valid values:
true: Enable.false(default): Disable.
Domain | Description | Sample query |
|---|---|---|
Exchange rate | Provides the latest exchange rates between multiple currencies and supports standard currency codes. | What is the exchange rate between CNY and USD? |
Weather | Provides real-time, future, and historical weather data. | Hangzhou weather |
Stocks | Supports A-shares, Hong Kong stocks, and US stocks. You can retrieve real-time stock prices, previous trading day closing prices, historical trends, 30-day closing prices, and prices for stock tickers or indices. | What was the closing price of the Shanghai Composite Index yesterday? |
Gas price | Provides daily updates on gasoline and diesel prices in various regions. | What is the gas price in Hangzhou? |
Perpetual calendar | For a specified date, provides information including the lunar calendar, solar terms, holidays, and traditional almanac guidance on auspicious and inauspicious activities. | What is today's lunar date? |
Gold price | Provides real-time quotes, including the latest price, opening price, high, and low. | What is the price of gold now? |
Silver price | Provides real-time quotes, including the latest price, opening price, high, and low. | What is the price of silver now? |
Lottery | Supports mainstream lottery types such as Double Color Ball, Super Lotto, Permutation 3, Permutation 5, 7-Star Lottery, Happy 8, and 3D. | What are the latest Double Color Ball results? |
TV series | Provides information on TV series from mainstream platforms. | What TV series are trending? |
Movies | Provides the latest information from mainstream movie platforms. | What movies have been released recently? |
License plate restrictions | Checks the driving restrictions for the current day based on a license plate number. | ZheAxxxxxx, are there driving restrictions in Hangzhou today? |
Soccer matches | Provides schedules and standings for leagues such as the Premier League, La Liga, Bundesliga, Serie A, Ligue 1, Chinese Super League, and Scottish Premiership. | Which team is currently ranked first in the Premier League? |
- OpenAI
- DashScope
- Python
- Node.js
- curl
Sample response
Search freshness
For time-sensitive queries, such as recent news or updates, use the freshness parameter to restrict the search time range and filter out outdated results.
Valid values:
7: Retrieves content from the last 7 days.30: Retrieves content from the last 30 days.180: Retrieves content from the last 180 days.365: Retrieves content from the last 365 days.- Not set (default): The search is not restricted by time.
- Effective only for
search_strategy: turbo. - Supported models: qwen-plus, qwen-flash, qwen-plus-character, qwen-flash-character, qwen-flash-character-2026-02-26
- OpenAI compatible
- DashScope
Restrict search sites
To restrict a search to specific websites, such as official sites or trusted media sources, use the assigned_site_list parameter. When enabled, the search is limited to the sites you specify.
Limitations:
-
This setting applies only when
search_strategyis set toturbo. -
Supported models:
- Qwen Plus Series:
qwen-plus - Qwen Flash Series:
qwen-flash - Character model:
qwen-plus-character,qwen-flash-character,qwen-flash-character-2026-02-26
- Qwen Plus Series:
- You can specify up to 25 sites.
assigned_site_list parameter defaults to [], which means the search is unrestricted.
If no relevant content is found on the specified sites, the search may return empty results. In this case, the model will answer using its own knowledge.
- OpenAI compatible
- DashScope
Control search scope with natural language
Use the prompt_intervene parameter to define the search scope with natural language. This lets you target content about a specific topic or from a particular region.
Supported models: qwen-plus, qwen-flash, qwen-plus-character, qwen-flash-character, qwen-flash-character-2026-02-26
- OpenAI compatible
- DashScope
Early return of search sources
In streaming mode, a delay of 0.5 seconds or more can occur between when search results are ready and when the first data packet is sent. You can reduce the time to first token (TTFT) by returning search sources immediately after the search completes. To enable this feature, set prepend_search_result to true.
Valid values:
true: The first data packet contains only the search sources. Subsequent data packets contain the model response.false(default): The first data packet contains both the search sources and the initial part of the model response.
- Python
- curl
Sample response
Mixed text and image output
Set enable_text_image_mixed: true to enable mixed text and image output. With this feature enabled, the model embeds relevant images in its responses.
Example:

<img> tags. To display them on the front end, you can render the HTML directly or convert it to Markdown.
- OpenAI compatible
- DashScope
Web search with thinking models
In the previous examples, the model provides a direct response after retrieving search results. This approach is suitable for simple, time-sensitive, and fact-based queries, such as "What is the weather in Hangzhou tomorrow?". However, for complex tasks like industry trend analysis, multi-source information synthesis, or report generation, this approach often falls short. For these scenarios, you can use a thinking model. After retrieving content, a thinking model first reasons over the information before generating a response, significantly improving the answer quality for complex tasks.
The thinking process is visible, so you can understand how the response is derived from the retrieved information.
The following models support both web search and deep thinking capabilities:
-
Qwen
- Qwen-Plus:
qwen-plus,qwen-plus-latest, and snapshot versions fromqwen-plus-2025-07-14or later - Qwen-Flash:
qwen-flash, and snapshot versions fromqwen-flash-2025-07-28or later
- Qwen-Plus:
-
DeepSeek:
deepseek-v4-pro
For more details on thinking models, see Deep Thinking.
- OpenAI compatible
- DashScope
- Python
- Node.js
- HTTP
Sample code
Response
Web search with Responses API
You can enable web search by adding the web_search tool to the tools array of the tools parameter.
This feature is supported only for the following models: the Qwen3.8 Max, Flash, and open-source series, and qwen3.8-omni-flash; the Qwen3.7 and Qwen3.5 series models (including open-source models, but not Omni models), the Qwen3.6-Plus and Qwen3.6-Flash series, and qwen3.6-35b-a3b; deepseek-v4-flash-0731, deepseek-v4-pro, deepseek-v4-pro-0813; glm-5.2; and kimi-k3.
qwen3.8-max,qwen3.8-max-0902,qwen3.8-flash,qwen3.8-2.4t-a95b, andqwen3.8-27bdo not support theagentvalue ofsearch_strategyon the Chat Completions API. To use agent-style multi-turn retrieval with Qwen3.8, use the Responses APIweb_searchtool documented in this section — the model can autonomously callweb_searchmultiple times within a single response.
The Responses API does not use thesearch_strategyparameter. Whether web search is triggered — and whether the model performs multiple search rounds — is determined solely by attaching theweb_searchtool and by the model's own decisions. Asearch_options.search_strategyvalue passed to the Responses API is silently ignored and does not trigger a search.
For models that support these tools, enableweb_search,web_extractor, andcode_interpretertogether. Forqwen3.8-omni-flash, the only supported built-in tool isweb_search.
For usage instructions, code examples, and migration guides for the Responses API, see OpenAI-compatible - Responses.
Sample response output (agent-style multi-turn retrieval)
Sample response output (agent-style multi-turn retrieval)
output array contains multiple web_search_call (and optionally web_extractor_call) items interleaved with reasoning and the final message:web_search_call items and x_tools.web_search.count > 1 confirms agent-style multi-turn retrieval — the model decided on its own to refine the query and search again.Get search sources
After a web search runs, the search sources are returned in the response. They appear in the element whose type is web_search_call within the output array, and its action.sources field is the list of source links. You can extract them from the response in the example above as follows:
The Responses API does not support theenable_source,enable_citation, orcitation_formatparameters, and does not insert[1]citation markers into the response content. To use citation markers, use the DashScope API.
Billing
- model call fees: The web search feature appends retrieved web content to the prompt, increasing the number of input tokens. These tokens are billed at the model's standard rate. For pricing details, see the Model Studio console. When you use the Responses API or the Anthropic-compatible method, the web search tool is billed at the same rate as the agent policy.
-
search policy fees:
- turbo and max policies: Standard billing applies starting from 00:00 on February 27, 2026. The fee is CNY 3 per 1,000 calls for the turbo policy and CNY 4 per 1,000 calls for the max policy. This pricing applies only to the China (Beijing) region.
-
agent policy:
-
The fee per 1,000 calls is as follows:
- For the China (Beijing), US (Virginia), China (Hong Kong), Japan (Tokyo), and Germany (Frankfurt) regions: CNY 4.
- For the Singapore region: CNY 73.392381.
-
The fee per 1,000 calls is as follows:
-
agent_max policy (Limited-time offer):
This policy covers both the web search and the web extractor tool.
-
Fee per 1,000 calls for the web search tool:
- For the China (Beijing), US (Virginia), China (Hong Kong), Japan (Tokyo), and Germany (Frankfurt) regions: CNY 4.
- For the Singapore region: CNY 73.392381.
- The web extractor tool is free for a limited time.
-
Fee per 1,000 calls for the web search tool:
Rate limit
The rate limit for web search is 15 requests per second (RPS) per Alibaba Cloud account. This limit applies to the total requests from all API keys under the account, regardless of the model. If the limit is exceeded, the API call will not trigger the search step and will not return an error.
FAQ
Q: Why doesn't the model perform a web search after I enable it?
A: This can happen for the following reasons:
- The model determines a search is unnecessary: The model may decide that the query can be answered using its internal knowledge and does not require real-time information. To force a web search, set
forced_search: truein thesearch_optionsparameter. - The rate limit is exceeded: Your account's request frequency has surpassed 15 RPS. The API does not return an error but silently skips the web search step. To resolve this, reduce your request frequency.
- Unsupported model: The model you are using does not support web search. See Supported models.
Q: How can I determine if a search was performed?
A: The method depends on the API you are using:
-
DashScope
- If a search was performed, the response includes a
search_infofield, and theusageobject contains apluginsfield. - If a search is not performed, the response does not contain the
search_infofield, and theusageobject does not contain thepluginsfield.
- If a search was performed, the response includes a
-
OpenAI-compatible
The response provides no explicit indicator. You can infer that a search occurred by comparing the input token count in the
usageobject. A count significantly higher than your original prompt's token count suggests a web search was performed. For example, a query like "What's the weather in Hangzhou?" might use 10 input tokens without a search, but 1,953 input tokens with a search.
Q: Why does web search fail for English queries?
A: We are continuously optimizing the search-triggering logic for English queries. For now, we recommend either asking questions in Chinese or forcing a web search when using English input.
Q: Is my original prompt sent to external search engines?
A: No. Your original prompt is not sent directly to a search engine. Instead, the system analyzes your query's intent, applies multiple layers of data masking, and extracts only key, non-sensitive information fragments for retrieval. The system rewrites the query multiple times before sending it to the search engine to ensure no sensitive data is exposed in plaintext. Alibaba Cloud uses data encryption and privacy protection measures to ensure security. For details, see the Service Agreement.
Q: Can my original text be reconstructed from the search vectors?
A: No. A vector is a high-dimensional mathematical representation of data and is not human-readable. It is computationally infeasible for an external system to reverse-engineer the original text from its vector. Furthermore, the vector matching process occurs within a secure, trusted environment and is never exposed to public search engines.
Q: How does the system decide whether to perform a web search?
A: The system first determines whether a search is necessary. It typically triggers a search for time-sensitive or encyclopedic queries, as these are less likely to contain confidential information. Conversely, it generally does not perform a search for queries unrelated to current events. The system rewrites the query multiple times before performing any search.
Q: Why does the model reply "I cannot answer this question" or fail to respond when web search is enabled?
A: Web search results may contain regulated content that triggers the content moderation rules, causing the API to return a DataInspectionFailed error (HTTP 400) and the model to reply "Sorry, I cannot answer this question." To troubleshoot, disable web search and resend the same query. If the model responds normally, the search results triggered the interception. This interception is non-deterministic: it depends on the specific content returned by the search, and not all queries on sensitive topics trigger it.
Q: Web search returns a stock price on a non-trading day. How do I handle this?
A: Use qwen3.7-max or a later model. qwen3.7-max can reason about dates: it recognizes a non-trading day and reports that no closing price is available. qwen-max lacks date reasoning and returns the stock price retrieved from search results. Neither enable_search_extension nor prompt_intervene resolves this issue.
Q: How do I make a Kimi model perform a web search?
A: Kimi models (kimi-k3) support web search only through the web_search tool of the Responses API; the enable_search parameter is not supported. For more flexible retrieval, you can also create an agent application in the Model Studio console and add a web search MCP tool, such as bailian_web_search, under Tools > MCP services. The Web Search MCP service and the built-in web search are two independent features that are billed separately. For more information, see Connect Harness tools.