v1

latestOpenAPI 3.0.32026-07-267263.7 KB

Initiate a 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

Request body

inputstring required

The research task or question to investigate.

model'mini' | 'pro' | '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

streamboolean

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

citation_format'numbered' | 'mla' | 'apa' | 'chicago'

The format for citations in the research report.

include_domainsstring[]

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.

exclude_domainsstring[]

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.

output_length'short' | 'standard' | 'long'

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

Example request

{
  "input": "What are the latest developments in AI?",
  "output_schema": {
    "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"
    ]
  },
  "include_domains": [
    "sec.gov",
    "ec.europa.eu"
  ],
  "exclude_domains": [
    "reddit.com",
    "quora.com"
  ],
  "files": [
    {
      "name": "q1-report.md",
      "data": "<base64-encoded file contents>",
      "type": "base64"
    }
  ]
}

Response

Research task queued successfully (when not streaming)

request_idstring required

A unique identifier for the research task.

created_atstring required

Timestamp when the research task was created.

statusstring required

The current status of the research task.

inputstring required

The research task or question investigated.

modelstring required

The model used by the research agent.

response_timeinteger required

Time in seconds it took to complete the request.

Example 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"
}