1# Research API Reference
2 
3## Table of Contents
4 
5- [Overview](#overview)
6- [Prompting Best Practices](#prompting-best-practices)
7- [Model Selection](#model-selection)
8- [Key Parameters](#key-parameters)
9- [Basic Usage](#basic-usage)
10- [Streaming vs Polling](#streaming-vs-polling)
11- [Structured Output vs Report](#structured-output-vs-report)
12- [Response Fields](#response-fields)
13- [Summary](#summary)
14 
15---
16 
17## Overview
18 
19The Research API conducts comprehensive research on any topic with automatic source gathering, analysis, and response generation with citations. It's an end-to-end solution when you need AI-powered research without building your own pipeline.
20 
21---
22 
23## Prompting Best Practices
24 
25Define a **clear goal** with all **details** and **direction**.
26 
27**Guidelines:**
28- **Be specific when you can.** Include known details: target market, competitors, geography, constraints
29- **Stay open-ended only for discovery.** Make it explicit: "tell me about the most impactful AI innovations in healthcare in 2025"
30- **Avoid contradictions.** Don't include conflicting constraints or goals
31- **Share what's already known.** Include prior assumptions so research doesn't repeat existing knowledge
32- **Keep prompts clean and directed.** Clear task + essential context + desired output format
33 
34### Example Queries
35 
36**Company research:**
37```
38Research the company ____ and its 2026 outlook. Provide a brief overview
39of the company, its products, services, and market position.
40```
41 
42**Competitive analysis:**
43```
44Conduct a competitive analysis of ____ in 2026. Identify their main
45competitors, compare market positioning, and analyze key differentiators.
46```
47 
48**With prior context:**
49```
50We're evaluating Notion as a potential partner. We already know they
51primarily serve SMB and mid-market teams, expanded their AI features
52significantly in 2025, and most often compete with Confluence and ClickUp.
53Research Notion's 2026 outlook, including market position, growth risks,
54and where a partnership could be most valuable. Include citations.
55```
56 
57---
58 
59## Model Selection
60 
61| Model | Best For |
62|-------|----------|
63| `pro` | Comprehensive, multi-agent research for complex, multi-domain topics |
64| `mini` | Targeted, efficient research for narrow or well-scoped questions |
65| `auto` | When unsure how complex research will be (default) |
66 
67### Pro Model
68 
69Multi-agent research suited for complex topics spanning multiple subtopics or domains. Use for deeper analysis, thorough reports, or maximum accuracy.
70 
71```python
72result = client.research(
73    input="Analyze the competitive landscape for ____ in the SMB market, "
74          "including key competitors, positioning, pricing models, customer "
75          "segments, recent product moves, and defensible advantages or risks "
76          "over the next 2-3 years.",
77    model="pro"
78)
79```
80 
81### Mini Model
82 
83Optimized for targeted, efficient research. Best for narrow or well-scoped questions where you still benefit from agentic searching and synthesis.
84 
85```python
86result = client.research(
87    input="What are the top 5 competitors to ____ in the SMB market, and how do they differentiate?",
88    model="mini"
89)
90```
91 
92---
93 
94## Key Parameters
95 
96### research()
97 
98| Parameter | Type | Default | Description |
99|-----------|------|---------|-------------|
100| `input` | string | Required | The research topic or question |
101| `model` | enum | `"auto"` | `"mini"`, `"pro"`, or `"auto"` |
102| `stream` | boolean | false | Enable streaming responses |
103| `output_schema` | object | null | JSON Schema for structured output |
104| `citation_format` | enum | `"numbered"` | `"numbered"`, `"mla"`, `"apa"`, `"chicago"` |
105 
106### get_research()
107 
108| Parameter | Type | Description |
109|-----------|------|-------------|
110| `request_id` | string | Task ID from `research()` response |
111 
112---
113 
114## Basic Usage
115 
116Research tasks are two-step: initiate with `research()`, retrieve with `get_research()`.
117 
118```python
119import time
120from tavily import TavilyClient
121 
122client = TavilyClient()
123 
124# Step 1: Start research task
125result = client.research(
126    input="Latest developments in quantum computing and their practical applications",
127    model="pro"
128)
129request_id = result["request_id"]
130 
131# Step 2: Poll until completed
132response = client.get_research(request_id)
133while response["status"] not in ["completed", "failed"]:
134    print(f"Status: {response['status']}... polling again in 10 seconds")
135    time.sleep(10)
136    response = client.get_research(request_id)
137 
138# Step 3: Handle result
139if response["status"] == "failed":
140    raise RuntimeError(f"Research failed: {response.get('error', 'Unknown error')}")
141 
142report = response["content"]
143sources = response["sources"]
144```
145 
146---
147 
148## Streaming vs Polling
149 
150**Streaming** — Best for user interfaces where you want real-time updates.
151**Polling** — Best for background processes where you check status periodically.
152 
153### Streaming
154 
155Enable real-time progress monitoring with `stream=True`.
156 
157```python
158stream = client.research(
159    input="Latest developments in quantum computing",
160    model="pro",
161    stream=True
162)
163 
164for chunk in stream:
165    print(chunk.decode('utf-8'))
166```
167 
168### Event Types
169 
170| Event Type | Description |
171|------------|-------------|
172| **Tool Call** | Agent initiates action (Planning, WebSearch, etc.) |
173| **Tool Response** | Results after tool execution with sources |
174| **Content** | Research report streamed as markdown (or JSON with `output_schema`) |
175| **Sources** | Complete list of sources, emitted after content |
176| **Done** | Signals completion |
177 
178### Tool Types
179 
180| Tool | Description | Models |
181|------|-------------|--------|
182| `Planning` | Initializes research strategy | mini, pro |
183| `WebSearch` | Executes web searches | mini, pro |
184| `Generating` | Creates final report | mini, pro |
185| `ResearchSubtopic` | Deep research on subtopics | pro only |
186 
187### Typical Flow
188 
1891. `Planning` tool_call → tool_response
1902. `WebSearch` tool_call → tool_response (with sources)
1913. `ResearchSubtopic` cycles (Pro mode only)
1924. `Generating` tool_call → tool_response
1935. `Content` chunks (markdown or structured JSON)
1946. `Sources` event
1957. `Done` event
196 
197See [streaming cookbook](https://github.com/tavily-ai/tavily-cookbook/blob/main/cookbooks/research/streaming.ipynb) and [polling cookbook](https://github.com/tavily-ai/tavily-cookbook/blob/main/cookbooks/research/polling.ipynb) for complete examples.
198 
199---
200 
201## Structured Output vs. Report
202 
203| Format | Best For |
204|--------|----------|
205| **Report** (default) | Reading, sharing, or displaying verbatim (chat interfaces, briefs, newsletters) |
206| **Structured Output** | Data enrichment, pipelines, or powering UIs with specific fields |
207 
208## Structured Output
209 
210Use `output_schema` to receive research in a predefined JSON structure.
211 
212```python
213schema = {
214    "properties": {
215        "summary": {
216            "type": "string",
217            "description": "Executive summary of findings"
218        },
219        "key_points": {
220            "type": "array",
221            "items": {"type": "string"},
222            "description": "Main takeaways from the research"
223        },
224        "metrics": {
225            "type": "object",
226            "properties": {
227                "market_size": {"type": "string", "description": "Total market size"},
228                "growth_rate": {"type": "number", "description": "Annual growth percentage"}
229            }
230        }
231    },
232    "required": ["summary", "key_points"]
233}
234 
235result = client.research(
236    input="Electric vehicle market analysis 2024",
237    output_schema=schema
238)
239```
240 
241### Schema Best Practices
242 
243- **Write clear field descriptions.** 1-3 sentences explaining what the field should contain
244- **Match the structure you need.** Use arrays, objects, enums appropriately (e.g., `competitors: string[]`, not `"A, B, C"`)
245- **Avoid duplicate fields.** Keep each field unique and specific
246- **Use `required` arrays** to enforce mandatory fields at any nesting level
247 
248**Supported types:** `object`, `string`, `integer`, `number`, `array`
249 
250### Streaming with Structured Output
251 
252When `output_schema` is provided, content arrives as structured JSON:
253 
254```python
255stream = client.research(
256    input="AI agent frameworks comparison",
257    model="mini",
258    stream=True,
259    output_schema={
260        "properties": {
261            "summary": {"type": "string", "description": "Executive summary"},
262            "key_points": {"type": "array", "items": {"type": "string"}}
263        },
264        "required": ["summary", "key_points"]
265    }
266)
267 
268for chunk in stream:
269    data = chunk.decode('utf-8')
270    print(data)  # Content chunks will be structured JSON
271```
272 
273---
274 
275## Response Fields
276 
277### research() Response
278 
279| Field | Description |
280|-------|-------------|
281| `request_id` | Unique identifier for tracking |
282| `created_at` | Timestamp when task was created |
283| `status` | Initial status |
284| `input` | The research topic submitted |
285| `model` | Model used by research agent |
286 
287### get_research() Response
288 
289| Field | Description |
290|-------|-------------|
291| `status` | `"pending"`, `"processing"`, `"completed"`, `"failed"` |
292| `content` | Generated research report (when completed) |
293| `sources` | Array of source citations |
294| `response_time` | Time in seconds |
295 
296### Source Object
297 
298| Field | Description |
299|-------|-------------|
300| `url` | Source URL |
301| `title` | Source title |
302| `citation` | Formatted citation string |
303 
304---
305 
306## Summary
307 
3081. **Be specific in prompts** — Include known details: target market, competitors, geography, constraints
3092. **Share prior context** — Include what you already know to avoid repetition
3103. **Choose the right model** — `mini` for focused queries, `pro` for comprehensive multi-domain analysis
3114. **Use streaming for UX** — Display real-time progress during long research tasks
3125. **Use structured output for pipelines** — Define schemas for consistent, parseable responses
3136. **Use reports for reading** — Default format is best for chat interfaces and sharing
314 
315For more examples, see the [Tavily Cookbook](https://github.com/tavily-ai/tavily-cookbook/tree/main/research) and [live demo](https://chat-research.tavily.com/).
316