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
}

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

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