Deep Research

Deep Research provides AI-powered research workflows with both blocking and streaming APIs. It supports pro and pro_plus modes and can incorporate internal tools.

Non-Streaming Research

result = client.deep_research.research(
    "Compare RAG architectures for enterprise knowledge bases",
    mode="pro",
    max_iterations=15,
)
 
print(result.content)
print(result.mode)
print(len(result.citations))
print(result.tool_calls_count)

Streaming Research

for event in client.deep_research.research_stream(
    "Latest developments in AI agents 2026",
    mode="pro_plus",
    max_iterations=20,
):
    match event.type:
        case "status":
            print(event.data.get("message"))
        case "planning":
            print(event.data.get("plan"))
        case "searching":
            print(event.data.get("query"))
        case "reading":
            print(event.data.get("url"))
        case "synthesizing":
            print("Synthesizing...")
        case "complete":
            print(event.data.get("content", "")[:500])
        case "error":
            print(event.data)

Durable Research Jobs

For very long runs (e.g. quality_profile="expert"), start a durable job — it executes on the platform's worker fleet and survives client disconnects, HTTP timeouts, and restarts.

job = client.deep_research.create_job(
    "Map the competitive landscape for vector databases",
    mode="pro_plus",
    max_iterations=20,
)
 
# Resumable progress stream (pass the last _seq as cursor to resume)
for event in client.deep_research.job_events(job.job_id):
    print(event.type)
 
job = client.deep_research.wait_for_job(job.job_id, poll_interval=5.0)
print(job.status)
result = job.research_result()
 
# Or poll / cancel explicitly
job = client.deep_research.get_job(job.job_id)
client.deep_research.cancel_job(job.job_id)

Research with Internal Tools

result = client.deep_research.research(
    "Analyze our Q1 2026 sales trends and compare with industry benchmarks",
    mode="pro",
    available_tools=[
        {
            "tool_id": "conn_sales_db",
            "name": "Sales Database",
            "description": "Production sales database with order and revenue data",
        }
    ],
)

Models and Tools

models = client.deep_research.models()
all_tools = client.deep_research.tools()
pro_tools = client.deep_research.tools(mode="pro")

Method	Return Type	Description
`research(query, ...)`	`ResearchResult`	Blocking research (returns the finished report)
`research_stream(query, ...)`	`Iterator[ResearchEvent]`	Streaming SSE research
`create_job(query, ...)`	`ResearchJob`	Start a durable research job
`get_job(job_id)`	`ResearchJob`	Job status (and result once completed)
`job_events(job_id, cursor=...)`	`Iterator[ResearchEvent]`	Resumable progress stream
`wait_for_job(job_id, ...)`	`ResearchJob`	Poll until the job is terminal
`cancel_job(job_id)`	`dict`	Request cancellation
`redeliver(job_id, output=...)`	`ResearchJob`	Retry or add a Knowledge Base delivery
`tools(mode=...)`	`dict`	Available tools
`models()`	`dict`	Available models

Use the non-streaming API when you need a single completed report. Use the streaming API when you want progress events for UI or agent orchestration.

Multimodal Perception Data Search