---
title: "Run research with SSE streaming"
method: POST
path: "/v1/automation/run-research"
tags: ["Research"]
---

# Run research with SSE streaming

`POST /v1/automation/run-research`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/automation/run-research`
- Auth: API key in header `X-API-Key`

Search, evaluate sources, and synthesize a cited report from a natural-language query. Accepted requests always return a Server-Sent Events stream, including when stream is false.

## Request body

- object
  - `query` string, required: Research question
  - `mode` 'deep' | 'max': Depth of research. Omitted selects deep.
  - `stream` boolean: Emit report text through synthesis_delta events as it is written
  - `output_language` string: BCP 47 language tag for the report
  - `weak_sources_enabled` boolean: Allow relevant social and community sources
  - `domain_type` 'web' | 'news' | 'research_paper': Source pool to research over
  - `after_date` string, date: Include results on or after this date (YYYY-MM-DD)
  - `before_date` string, date: Include results on or before this date (YYYY-MM-DD)
  - `recency_minutes` integer: Include results from the last 1-5,256,000 minutes. Not combinable with date filters.
  - `domain_filter` object: Domain preferences. Each list accepts at most 150 entries.
    - `mode` 'include' | 'exclusive', required: include prioritizes the domains; exclusive restricts results to them
    - `domains` string[]: Domains to prefer or require
    - `block` string[]: Domains to always remove
  - `prior_run_id` string: Seed this run with a completed report and its evidence
  - `session_id` string, uuid: Continue a research session. Mutually exclusive with prior_run_id.

## Response `200`

Server-Sent Events stream. Save the run ID from created and stop reading after done. See the Research API reference for the full event catalog.

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - Invalid or missing API key
- `402`: Payment required - wallet balance too low to start a run
- `403`: Forbidden - Research is not enabled for this account
- `404`: Not found - unknown session_id or prior_run_id
- `429`: Concurrent-run or daily-completion limit reached
- `500`: Internal server error
- `503`: Research is temporarily unavailable

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/6c73a54df35c?raw)