---
title: "Initiate a research task"
method: POST
path: "/research"
---

# Initiate a research task

`POST /research`

Tavily Research performs comprehensive research on a given topic by conducting multiple searches, analyzing sources, and generating a detailed research report.

## Request body

- object
  - `input` string, 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
  - `stream` boolean — Whether to stream the research results as they are generated. When 'true', returns a Server-Sent Events (SSE) stream. See [Streaming documentation](/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.
    - `properties` object — An object containing property definitions. Each key is a property name, and each value is a property schema.
    - `required` string[] — An array of property names that are required. At least one key from the properties object must be included.
  - `citation_format` 'numbered' | 'mla' | 'apa' | 'chicago' — The format for citations in the research report.
  - `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.
  - `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.
  - `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.
  - `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.
    - `name` string, required — The filename, including its extension (`.txt`, `.md`, or `.json`).
    - `data` string, required — The base64-encoded file contents.
    - `type` 'base64' — The encoding of the `data` field.

## Response `201`

Research task queued successfully (when not streaming)

- object
  - `request_id` string, required — A unique identifier for the research task.
  - `created_at` string, required — Timestamp when the research task was created.
  - `status` string, required — The current status of the research task.
  - `input` string, required — The research task or question investigated.
  - `model` string, required — The model used by the research agent.
  - `response_time` integer, required — Time in seconds it took to complete the request.

## Other responses

- `400` — Bad Request - Your request is invalid.
- `401` — Unauthorized - Your API key is wrong or missing.
- `429` — Too many requests - Rate limit exceeded
- `432` — Key limit or Plan Limit exceeded
- `433` — PayGo limit exceeded
- `500` — Internal Server Error - We had a problem with our server.

---

[API](https://skmtc.net/tavily/apis/tavily-search-and-extract-api.md) · [All operations](https://skmtc.net/tavily/apis/tavily-search-and-extract-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tavily/tavily-search-and-extract-api/revisions/9126e7d2df75/schema)