Skip to main content
QwenCloud home page
Docs
Tool calling

Web search

Ground model responses in real-time web data

The training data for large language models has a knowledge cutoff date, preventing them from answering real-time questions. Enabling web search lets a model retrieve real-time data from the internet and accurately answer time-sensitive questions, such as stock prices, weather forecasts, and breaking news. Get an API key and set it as an environment variable.
  • OpenAI compatible
  • Responses API
  • DashScope
Set enable_search: true and optionally pass search_options to choose a strategy.
The OpenAI compatible Chat Completions endpoint does not return search sources. Use the Responses API or DashScope if you need citations.
import os
from openai import OpenAI

client = OpenAI(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  base_url="https://dashscope-intl.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
  model="qwen3-max",
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "How is Alibaba's stock price?"},
  ],
  extra_body={
    "enable_search": True,
    "search_options": {
      "search_strategy": "agent"
    }
  }
)
print(completion.choices[0].message.content)

Web search with multimodal models

Models such as qwen3.5-plus, qwen3.5-flash, and the qwen3.5-omni series 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.
  • 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.
import os
import dashscope
from dashscope import MultiModalConversation
dashscope.base_http_api_url = "https://dashscope-intl.aliyuncs.com/api/v1"
responses = MultiModalConversation.call(
  api_key=os.getenv("DASHSCOPE_API_KEY"),
  model="qwen3.5-plus",
  messages=[{"role": "user", "content": [{"text": "What is the weather in Hangzhou today?"}]}],
  enable_search=True,
  search_options={
    "search_strategy": "agent",
    "enable_source": True,
  },
  stream=True,
  incremental_output=True,
)
for response in responses:
  print(response.output.choices[0].message.content)

Supported models

Web search supports two search strategies: agent (standard search) and agent_max (search + full-page reading).
Model familyThinking modeNon-thinking modeNotes
Qwen3.8 Max (qwen3.8-max)agent, agent_maxagent, agent_max
Qwen3.7 Max (qwen3.7-max, qwen3.7-max-preview, qwen3.7-max-2026-05-17 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.7 Plus (qwen3.7-plus, qwen3.7-plus-2026-05-26 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.6 Plus (qwen3.6-plus, qwen3.6-plus-2026-04-02 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.5 Plus (qwen3.5-plus, qwen3.5-plus-2026-02-15 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.7 Flash (qwen3.7-flash, qwen3.7-flash-2026-07-15 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.6 Flash (qwen3.6-flash, qwen3.6-flash-2026-04-16 and later snapshots)agent, agent_maxagent, agent_max
Qwen3.5 Flash (qwen3.5-flash, qwen3.5-flash-2026-02-23 and later snapshots)agent, agent_maxagent, agent_max
Qwen3 Max (qwen3-max, qwen3-max-2026-01-23)agent, agent_maxagentagent_max requires thinking mode
Qwen3.8 open-source (qwen3.8-2.4t-a95b)agent, agent_maxagent, agent_max
Qwen-Plus character (qwen-plus-character)agentagentRole-playing
Qwen-Flash character (qwen-flash-character)agentagentRole-playing
DeepSeek (deepseek-v4-pro-0813, deepseek-v4-flash, deepseek-v4-flash-0731, deepseek-v4-pro)——Responses API only
GLM (glm-5.2)——Responses API only

Search strategies

Control how aggressively the model searches via the search_strategy field inside search_options:
  • agent -- The model decides when and how often to search. Suitable for most queries. One search call is billed per invocation.
  • agent_max -- The model may search multiple times and, when supported, use the web extractor tool to read full pages. Best for research-heavy prompts that need deep or cross-referenced information. Requires thinking mode on Qwen3 Max.
If you omit search_strategy, the default is agent.

Read search results

When you set enable_source: true (DashScope only), the response includes a search_info.search_results array. Each entry contains:
FieldDescription
indexCitation number referenced in the response text
titlePage title of the source
urlURL of the source
Use these fields to render inline citations or a references list in your application. The model's response text may reference sources by index (e.g., "according to source [1]").

Billing

Billing involves two aspects:
  • Model call fees: The web content from the web search is added to the prompt, which increases the number of input tokens for the model. You are charged based on the standard pricing of the model. For more information about pricing, see Pricing.
  • Search call fees (per 1,000 calls):
    When using the Responses API, the web search tool is billed at the same rate as the agent strategy.
    The prices listed below are list prices. For current promotions and discounted pricing, visit the Model Marketplace.
    Strategy (search_strategy)What it doesFee
    agent (default)Model searches the web as needed$10.00
    agent_maxSearches + reads full pages via web extractor$10.00 for search; web extractor is free for a limited time

Error codes

If a call fails, see Error messages.