---
title: "Start research asynchronously"
method: POST
path: "/v1/automation/run-research-async"
tags: ["Research"]
---

# Start research asynchronously

`POST /v1/automation/run-research-async`

## Request

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

Enqueue research and return its ID after durable dispatch. Poll GET /v1/research-run/{id} or attach to its events endpoint.

## 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`

Research queued. Poll by research_run_id for status and results.

- object
  - `research_run_id` string, uuid, required
  - `error` object, nullable, required: Error details. Null if successful.
    - `code` string, required: Machine-readable error code
    - `message` string, required: Error message if run creation failed

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - Invalid or missing API key
- `402`: Research admission refused; no new run was accepted.
- `403`: Research admission refused; no new run was accepted.
- `404`: Research admission refused; no new run was accepted.
- `429`: Research admission refused; no new run was accepted.
- `500`: Internal server error
- `503`: Research admission refused; no new run was accepted.

---

[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)