Create Research Task

Tavily Research performs comprehensive research on a given topic by conducting multiple searches, analyzing sources, and generating a detailed research report.

POST /research

Python SDK

Python

from tavily import TavilyClient

tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = tavily_client.research("What are the latest developments in AI?")

print(response)

201

{
  "request_id": "123e4567-e89b-12d3-a456-426614174111",
  "created_at": "2025-01-15T10:30:00Z",
  "status": "pending",
  "input": "What are the latest developments in AI?",
  "model": "mini",
  "response_time": 1.23
}

Authorizations

Authorization · string · header · required

Bearer authentication header in the form Bearer , where is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).

Body

application/json

Parameters for the Tavily Research request.

input · string · required

The research task or question to investigate.

Example:

"What are the latest developments in AI?"

model · enum<string> · default: auto

The model used by the research agent. "mini" is optimized for targeted, efficient research and works best for narrow or well-scoped questions. "pro" provides comprehensive, multi-angle research and is suited for complex topics that span multiple subtopics or domains

Available options: mini, pro, auto

stream · boolean · default: false

Whether to stream the research results as they are generated. When 'true', returns a Server-Sent Events (SSE) stream. See Streaming documentation for details.

output_schema · object

A JSON Schema object that defines the structure of the research output. When provided, the research response will be structured to match this schema, ensuring a predictable and validated output shape. Must include a 'properties' field, and may optionally include 'required' field.

Show child attributes

Example:

{
  "properties": {
    "company": {
      "type": "string",
      "description": "The name of the company"
    },
    "key_metrics": {
      "type": "array",
      "description": "List of key performance metrics",
      "items": { "type": "string" }
    },
    "financial_details": {
      "type": "object",
      "description": "Detailed financial breakdown",
      "properties": {
        "operating_income": {
          "type": "number",
          "description": "Operating income for the period"
        }
      }
    }
  },
  "required": ["company"]
}

citation_format · enum<string> · default: numbered

The format for citations in the research report.

Available options: numbered, mla, apa, chicago

include_domains · string[]

Soft preference for sources. The research agent prioritizes these domains, but URLs from other domains can still appear in the final report. Matching is host-based and includes subdomains (e.g., sec.gov matches sec.gov and data.sec.gov). Maximum 20 entries.

Maximum array length: 20

Example:

["sec.gov", "ec.europa.eu"]

exclude_domains · string[]

Hard blocklist. No URL from a listed domain or any of its subdomains appears in the response. Subdomain matching is downward only — blocking medium.com also blocks blog.medium.com, but blocking blog.medium.com leaves medium.com itself allowed. Maximum 20 entries.

Maximum array length: 20

Example:

["reddit.com", "quora.com"]

output_length · enum<string> · default: standard

Typed control over response size. Ranges are targets, not hard caps — individual responses can fall outside when the question requires it.

Available options: short, standard, long

Response

201

application/json

Research task queued successfully (when not streaming)

request_id · string · required

A unique identifier for the research task.

Example:

"123e4567-e89b-12d3-a456-426614174111"

created_at · string · required

Timestamp when the research task was created.

Example:

"2025-01-15T10:30:00Z"

status · string · required

The current status of the research task.

Example:

"pending"

input · string · required

The research task or question investigated.

Example:

"What are the latest developments in AI?"

model · string · required

The model used by the research agent.

Example:

"mini"

response_time · integer · required

Time in seconds it took to complete the request.

Example:

1.23