Skip to main content

Web search

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.
For web search with models such as qwen3.7-max, use the web search feature of the Responses API.
  • OpenAI-compatible: Responses API
  • OpenAI-compatible: Chat Completions API
  • DashScope
  • Anthropic-compatible
Add the 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. 
# Import dependencies and create a client...
response = client.responses.create(
    model="qwen3.8-max",
    input="Hangzhou weather",
    tools=[
        {"type": "web_search"},
        {"type": "web_extractor"},
        {"type": "code_interpreter"}
    ],
    extra_body={"enable_thinking": True}
)

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. 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. 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.
Calling the multimodal models above with Generation (the text-generation endpoint) returns 400 url error, please check url. Use MultiModalConversation (the multimodal-generation endpoint) instead.In the Java SDK, MultiModalConversationParam provides enableSearch(true) to enable web search, but does not provide a searchOptions() method. Inject the search strategy and other options through the generic parameter("search_options", ...) method. In Python, MultiModalConversation.call accepts search_options directly.Web search on multimodal models requires streaming calls (use streamCall in Java, or set stream=True in Python); otherwise the request returns a Non-streaming mode does not support Web Search error.
Python
import os
import dashscope
from dashscope import MultiModalConversation
# The following uses the Singapore region. Replace {WorkspaceId} with your actual workspace ID; the configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
responses = MultiModalConversation.call(
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # Use a multimodal model that supports web search.
    model="qwen3.5-plus",
    messages=[{"role": "user", "content": [{"text": "What is the weather in Hangzhou today?"}]}],
    # The multimodal API accepts enable_search and search_options directly.
    enable_search=True,
    search_options={
        # The qwen3.5-omni series requires agent. On the multimodal API the Qwen3.8 series does not support agent; keep the default.
        "search_strategy": "agent",
        "enable_source": True,
    },
    # Streaming is required when web search is enabled for multimodal models.
    stream=True,
    incremental_output=True,
)
for response in responses:
    print(response.output.choices[0].message.content)

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.
  • Singapore
  • China (Beijing)
  • 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: agent is not supported; for agent-style retrieval, use the web_search tool 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-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)
  • 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

The following examples show how to query stock information using web search.
  • OpenAI compatible
  • DashScope
Set 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.
The OpenAI-compatible protocol does not support returning search sources in the response.
  • Python
  • Node.js
  • curl
import os
from openai import OpenAI

client = OpenAI(
    # If the environment variable is not set, provide your Model Studio API key directly, for example: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # The following configuration is for the Asia Pacific SE 1 (Singapore) region. Replace {WorkspaceId} with your workspace ID. Configurations differ by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the stock price of Alibaba?"},
    ],
    extra_body={
        "enable_search": True,
        "search_options": {
            # Specify the web search strategy. Only 'agent' is supported.
            "search_strategy": "agent"
        }
    }
)
print(completion.choices[0].message.content)
Sample response 
According to the latest market data, Alibaba's stock price in different markets is as follows:

*   US Stock (BABA): The latest price is approximately 159.84 USD.
*   Hong Kong Stock (09988.HK): The latest price is approximately 158.00 HKD.

Please note that stock prices fluctuate in real time, and this information is for reference only.

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.
When enabled through the web_search tool, the model performs agent-style multi-turn retrieval — it can autonomously call web_search (and optionally web_extractor / code_interpreter) multiple times within a single response.
qwen3.8-max, qwen3.8-max-0902, qwen3.8-flash, qwen3.8-2.4t-a95b, and qwen3.8-27b do not support the agent value of search_strategy on the Chat Completions API. To use agent-style multi-turn retrieval with Qwen3.8, use the Responses API web_search tool documented in this section.
The Responses API does not use the search_strategy parameter. Whether web search is triggered — and whether the model performs multiple search rounds — is determined solely by attaching the web_search tool and by the model's own decisions. A search_options.search_strategy value passed to the Responses API is silently ignored and does not trigger a search.
For models that support these tools, enable web_search, web_extractor, and code_interpreter together. For qwen3.8-omni-flash, the only supported built-in tool is web_search.
For usage instructions, code examples, and migration guides for the Responses API, see OpenAI-compatible - Responses. 
from openai import OpenAI
import os

client = OpenAI(
    # If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # This configuration is for the Singapore region. Replace {WorkspaceId} with your actual workspace ID. Configurations vary by region.
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1"
)

response = client.responses.create(
    model="qwen3.8-max",
    input="What is the weather in Singapore tomorrow?",
    tools=[
        {"type": "web_search"},
        {"type": "web_extractor"},
        {"type": "code_interpreter"}
    ],
    extra_body={"enable_thinking": True}
)

print("="*20 + "Response content" + "="*20)
print(response.output_text)

print("="*20 + "Tool call trace" + "="*20)
# Agent-style multi-turn retrieval: the model may call web_search multiple times
for item in response.output:
    t = getattr(item, "type", None)
    if t == "web_search_call":
        q = getattr(getattr(item, "action", None), "query", "")
        print(f"[web_search_call] query={q}")
    elif t == "web_extractor_call":
        print(f"[web_extractor_call]")

print("="*20 + "Source citations" + "="*20)
for item in response.output:
    if getattr(item, "type", None) == "message":
        for part in item.content:
            for ann in getattr(part, "annotations", []) or []:
                if getattr(ann, "type", None) == "url_citation":
                    print(f"- {ann.title}: {ann.url}")

print("="*20 + "Tool call count" + "="*20)
usage = response.usage
if hasattr(usage, "x_tools") and usage.x_tools:
    print(f"Web search count: {usage.x_tools.get('web_search', {}).get('count', 0)}")
For a query such as "What is the weather in Singapore tomorrow?", the model performs multiple retrieval rounds within a single response. The output array contains multiple web_search_call (and optionally web_extractor_call) items interleaved with reasoning and the final message:
{
    "output": [
        { "type": "reasoning", "..." : "..." },
        { "type": "web_search_call", "action": { "query": "Singapore weather tomorrow" } },
        { "type": "reasoning", "..." : "..." },
        { "type": "web_extractor_call", "..." : "..." },
        { "type": "web_search_call", "action": { "query": "Singapore 7-day forecast" } },
        { "type": "reasoning", "..." : "..." },
        { "type": "message", "content": [ /* final answer with url_citation annotations */ ] }
    ],
    "usage": {
        "x_tools": { "web_search": { "count": 2 } }
    }
}
The presence of multiple 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 the enable_source, enable_citation, or citation_format parameters, and does not insert [1] citation markers into the response content. To use citation markers, use the DashScope API. 
# Extract search sources from the response above
print("=" * 20 + "Search sources" + "=" * 20)
for item in response.output:
    if item.type == "web_search_call":
        for i, source in enumerate(item.action.sources, start=1):
            print(f"[{i}] {source.url}")

Billing

The web search described in this topic refers to the model's built-in web search feature, which is billed as described below and does not include a free call quota. It is separate from the Web Search MCP service offered in the Model Studio MCP marketplace, and the two are billed independently: the Web Search MCP service provides a free quota of 2,000 calls for all users, after which it is billed at CNY 29 per 1,000 calls. For more information, see Add web search MCP.
Charges for web search consist of two components:
  • 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:
    • 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: $0.573411.
        • For the Singapore region: $10.00.
    • 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: $0.573411.
        • For the Singapore region: $10.00.
      • The web extractor tool is free for a limited time.

Error messages

To troubleshoot errors, see Error codes.
Get Started
Billing
Token Plan
Model Playground
Clients and Developer Tools
Model Inference
Fine-tuning
Evaluation
Statistics and Monitoring
Asset Center
Security and Compliance
Best Practices
Support
Changelog