Skip to main content
More Models

Qwen-Deep-Research API reference

Request and response parameters for calling the Qwen-Deep-Research model through the DashScope API.

Related documentation: Deep research (Qwen-Deep-Research)
Qwen-Deep-Research is available only in the China (Beijing) region. You must use an API key from the China (Beijing) region.
The model currently supports only the Python DashScope SDK. The Java SDK and the OpenAI-compatible interface are not supported.

DashScope

Before you begin, get an API key and set it as an environment variable. To use the DashScope SDK, you must also install the SDK.

Request body

modelstring(Required)Supported value: qwen-deep-research.messagesarray(Required)Conversation history, in chronological order.

Message types

User messageobject(Required)A user message sends questions, instructions, or context to the model. In the two-step call flow of Qwen-Deep-Research, user messages serve different purposes:
  • Step 1 (Clarifying question): The user message initiates the research request with a broad topic.
  • Step 2 (Deep research): The user message answers the model's clarifying question to narrow the model's research scope for a more targeted analysis.
contentstring(Required)The message content.rolestring(Required)Must be user.
Assistant message object(Optional)The model's reply to a user message. For Step 2 (Deep research), pass the model's clarifying question from Step 1 to produce a more targeted analysis.contentstring(Optional)The message content.rolestring(Required)Must be assistant.
output_formatstring(Optional)Format and detail level of the research report. Valid values:
  • model_detailed_report (Default) Complete report (~6,000 tokens) for in-depth analysis.
  • model_summary_report Concise summary (~1,500–2,000 tokens) with key findings.
Python
import os
import dashscope
# The following is the base_url for the Beijing region. Replace WorkspaceId with your actual workspace ID. Configurations vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# Step 1: Get the clarifying question from the model.
messages = [{'role': 'user', 'content': 'Research the applications of artificial intelligence in education'}]

responses = dashscope.Generation.call(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-deep-research",
    messages=messages,
    stream=True
)

# Collect the model's clarifying question.
step1_content = ""
for response in responses:
    if hasattr(response, 'output') and response.output:
        message = response.output.get('message', {})
        content = message.get('content', '')
        if content:
            step1_content += content
            print(content, end='', flush=True)

# Step 2: Start the deep research.
messages = [
    {'role': 'user', 'content': 'Research the applications of artificial intelligence in education'},
    {'role': 'assistant', 'content': step1_content},
    {'role': 'user', 'content': 'I want to focus on personalized learning and intelligent assessment.'}
]

responses = dashscope.Generation.call(
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-deep-research",
    messages=messages
)

# Stream the research results.
for response in responses:
    if hasattr(response, 'output') and response.output:
        message = response.output.get('message', {})
        content = message.get('content', '')
        if content:
            print(content, end='', flush=True)

Response object

status_codestringThe HTTP status code for the request. 200 indicates success; other values indicate an error.
On failure, the thrown exception contains status_code and message.
request_idstringThe unique identifier for the request.codestringThe error code. This field is empty on success.
This parameter is returned only by the Python SDK.
message stringThe error message. This field is empty on success.outputobjectThe result of the call.
textstringThis parameter is always null.finish_reasonstringThe reason the model stopped generating content. Possible values:
  • null: Generation is in progress.
  • stop: Generation ended naturally.
  • length: The maximum content length was reached.
choicesarrayA list of output choices from the model.
finish_reasonstringPossible values:
  • null: Generation is in progress.
  • stop: Generation ended naturally.
  • length: The maximum content length was reached.
messageobjectThe message object from the model.
PropertiesphasestringCurrent phase. Possible values:
  • answer
  • ResearchPlanning
  • WebResearch
  • KeepAlive
rolestringMust be assistant.contentstringThe output content from the model.extra arrayWeb search results and references gathered by the model.deep_researchobjectRetrieved web search and reference information is included only in the answer and WebResearch stages, and is null in all other stages.researchobjectDetails of the research process.
researchGoalstringThe research goal.querystringSearch query used during research.idintegerThe search round number, in the range of [1, 15].learningMapobjectContent summarized from tool calls, associated with the tool usage.referencesobjectCitations for the generated answer. This field appears only in the Answer phase.
icon stringThe favicon URL for the referenced content.index_number integerThe index of the referenced content.descriptionstringA short description of the referenced content.titlestringThe title of the referenced web page.url stringThe URL of the referenced content.
webSitesobjectContent referenced during research. Included only in the Web Research phase.
icon stringThe favicon URL for the referenced content.index_number integerThe index of the referenced content.descriptionstringA short description of the referenced content.titlestringThe web page title of the referenced content.url stringThe URL of the referenced content.
statusstringThe status of a specific phase during streaming:
  • typing: The model is generating content for the current phase.
  • finished: The current phase is complete.
  • streamingQueries: The model is generating research goals and search queries.
  • streamingWebResult: Web search, page reading, and code execution are in progress.
  • WebResultFinished: The web search phase is complete.
fininshedbooleanWhether the stream is complete. Possible values:
  • false: Streaming in progress.
  • true: Final message.
fininshed_reason stringThe reason the streaming output ended. Possible values:
  • null: Generation is in progress.
  • stop: The stream completed normally.
usageobjectThe number of tokens used in this request.
input_tokens integerThe number of input tokens.output_tokens integerThe number of output tokens.
{
  "status_code": 200,
  "request_id": "2a6187f0-7e7b-40bb-a87e-xxx",
  "code": "",
  "message": "",
  "output": {
        "text": null,
        "finish_reason": null,
        "choices": null,
        "message": {
            "phase": "ResearchPlanning",
            "role": "assistant",
            "content": "",
            "extra": {
                "deep_research": {}
            },
            "status": "typing"
        },
        "fininshed": false,
        "fininshed_reason": "null"
    },
    "usage": {
        "input_tokens": 694,
        "output_tokens": 0
    },
    "request_id": "2a6187f0-7e7b-40bb-xxx"
}