---
source_url: "https://docs.tavily.com/documentation/api-reference/endpoint/research"
title: Create Research Task - Tavily Docs
mirrored_at: 2026-08-08T01:31:46.520Z
host: docs.tavily.com
cited_in_42a: true
mirror_canonical: "https://index.42a.ai/docs.tavily.com/documentation/api-reference/endpoint/research"
---

> **Original source:** https://docs.tavily.com/documentation/api-reference/endpoint/research

Python SDK

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](https://docs.tavily.com/documentation/api-reference/endpoint/research-streaming) 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:

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:

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:

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`

files

object\[\]

Attach files to the research request and the agent uses their contents as a source alongside the web. 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`.

Limits: up to 5 files per request; max 80,000 words per text file; max 80,000 words combined across all files.

Maximum array length: `5`

Show child attributes

Example:

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`