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)
{
  "id": "1984e2b0-660d-48ab-8fb5-1c7d3derb4a9",
  "object": "chat.completion.chunk",
  "model": "mini",
  "created": 1764796274,
  "choices": [
    {
      "delta": {
        "role": "assistant",
        "tool_calls": {
          "type": "tool_call",
          "tool_call": [
            {
              "name": "WebSearch",
              "id": "fc_634b5932-e66c-4523-931a-04a7b79f2578",
              "arguments": "Executing 5 search queries"
            }
          ]
        }
      }
    }
  ]
}
This API is currently in private beta and is subject to change. Sign up for early access at https://deepresearch.tavily.com/ to preview new capabilities and provide early feedback.

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

​
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 results returned successfully (when streaming)

Server-Sent Events stream containing research progress and results. Each chunk follows this structure:

​
id
string
required

Unique identifier for the stream event.

Example:

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

​
object
string
required

Object type, typically 'chat.completion.chunk'.

Example:

"chat.completion.chunk"

​
model
string
required

The model used by the research agent.

Example:

"mini"

​
created
integer
required

Unix timestamp when the event was created.

Example:

1705329000

​
choices
object[]
required

Array containing the delta with event details.