Skip to main content
POST
/
research
Python SDK
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)
{
  "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
}

​
Files

Attach files to a research request and the agent uses their contents as a source alongside the web. Add a files array to the request body, where each entry carries a filename and its base64-encoded contents. The agent reads the relevant parts of each file, grounds its answer in them, and cites any file it draws from. Supported file types: .txt, .md, .json Up to 5 files per request.

​
Full Request

{
  "input": "Summarize the key risks in the attached report and compare them to recent industry coverage.",
  "files": [
    {
      "name": "q1-report.md",
      "data": "<base64-encoded file contents>",
      "type": "base64"
    }
  ]
}

​
Limits

LimitValue
Max files per request5
Max size per text file (.txt, .md, .json)80,000 words
Max combined size of all files80,000 words

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.

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

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