> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Research API Reference

> Complete reference for research requests, streams, and saved runs

## Endpoints

| Endpoint                                    | Method | Purpose                                  |
| ------------------------------------------- | ------ | ---------------------------------------- |
| `/v1/automation/run-research`               | `POST` | Start a research run and stream progress |
| `/v1/research-run`                          | `GET`  | List saved research runs                 |
| `/v1/research-run/{research_run_id}`        | `GET`  | Retrieve one saved run                   |
| `/v1/research-run/{research_run_id}/cancel` | `POST` | Cancel a running research run            |

All endpoints use `https://agent.tinyfish.ai` and require the `X-API-Key` header.

## Modes

| Mode       | Best for                       | Typical time | Browser agents |
| ---------- | ------------------------------ | ------------ | -------------- |
| `standard` | Fast, source-backed answers    | 2–10 minutes | No             |
| `deep`     | Broader coverage and synthesis | 5–20 minutes | No             |
| `max`      | Complex or dynamic research    | 5–45 minutes | On by default  |

`auto` and an omitted mode currently select `standard`. Set `browser_enabled: false` to keep Max mode to search and
static fetches. `browser_enabled: true` is accepted only in Max mode.

## Request Body

| Field                  | Type                              | Required | Notes                                             |
| ---------------------- | --------------------------------- | -------- | ------------------------------------------------- |
| `query`                | `string`                          | Yes      | Research question, 1–2,000 characters             |
| `mode`                 | `auto \| standard \| deep \| max` | No       | Defaults to `standard`                            |
| `stream`               | `boolean`                         | No       | Emits synthesis text through `synthesis_delta`    |
| `output_language`      | `string`                          | No       | BCP 47 tag such as `en`, `ja`, or `pt-BR`         |
| `browser_enabled`      | `boolean`                         | No       | Max only; defaults to `true` in Max mode          |
| `weak_sources_enabled` | `boolean`                         | No       | Allows relevant social and community sources      |
| `domain_type`          | `web \| news \| research_paper`   | No       | Defaults to `web`                                 |
| `after_date`           | `YYYY-MM-DD`                      | No       | Include results on or after this date             |
| `before_date`          | `YYYY-MM-DD`                      | No       | Include results on or before this date            |
| `recency_minutes`      | `integer`                         | No       | Include results from the last 1–5,256,000 minutes |
| `domain_filter`        | `object`                          | No       | Prefer, require, or block specified domains       |
| `prior_run_id`         | `string`                          | No       | Seed a run with a completed report                |
| `session_id`           | `UUID`                            | No       | Continue a standard-mode session                  |

<Note>
  Do not combine `recency_minutes` with date filters. Date and recency filters are unavailable for `research_paper`.
  `session_id` and `prior_run_id` are mutually exclusive.
</Note>

## Event Stream

Accepted requests return `text/event-stream`, including when `stream` is omitted or false. Invalid input and other
pre-run failures return the standard JSON error body.

| Event                                       | Purpose                                                |
| ------------------------------------------- | ------------------------------------------------------ |
| `created`                                   | Supplies the research run ID                           |
| `session`                                   | Supplies a reusable conversation session ID            |
| `plan_updated`                              | Reports current subquestions and searches              |
| `sources_searched`                          | Lists candidate sources                                |
| `source_fetched`                            | Reports static source extraction                       |
| `agent_run_started` / `agent_run_completed` | Reports Max-mode browser work                          |
| `partial_summary`                           | Supplies an intermediate synthesis                     |
| `synthesis_delta`                           | Streams report text when enabled                       |
| `synthesis_discarded`                       | Discard provisional content for the named checkpoint   |
| `heartbeat`                                 | Keep the long-running connection open                  |
| `evidence_snapshot`                         | Supplies the current evidence set                      |
| `final_result`                              | Supplies the report, citations, and termination reason |
| `run_stats`                                 | Supplies final source, agent, and claim counts         |
| `error`                                     | Reports a pipeline failure                             |
| `done`                                      | Terminates the stream                                  |

Ordered `synthesis_delta` values reconstruct their matching summary or final result. Discard a provisional partial
checkpoint after `synthesis_discarded`. Heartbeats keep long-running connections open.

## List Saved Runs

`GET /v1/research-run` supports `status`, `query`, `created_after`, and `created_before`. Pagination uses `limit` from
1–100, `sort_direction=asc|desc`, and the returned `next_cursor`. Reuse a cursor only with the same sort direction.

## Cancel a Run

Call `POST /v1/research-run/{research_run_id}/cancel` to cancel a running research run. The response reports whether
this request changed the run to `CANCELLED` and includes its current status.

```json theme={null}
{
  "research_run_id": "019...",
  "status": "CANCELLED",
  "cancelled": true
}
```

Cancellation is idempotent. A run that is already terminal returns HTTP `200` with `cancelled: false` and its current
status. A missing run, or a run owned by another API key, returns HTTP `404`.

## Limits

Research creation is limited by concurrent runs and completed runs per Pacific calendar day. Limit responses use HTTP
`429`; daily-limit responses include `Retry-After` and `X-RateLimit-*` headers.