> ## 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 > Create source-backed research reports and stream their progress The Research API searches, evaluates sources, and synthesizes a cited report from a natural-language query. Use it for questions that need evidence across several sources rather than a single search result or webpage. ## Start a research run All requests require an `X-API-Key` header. Accepted requests use a [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) stream, including when `stream` is omitted or `false`. Invalid input and other failures before a run starts return the standard JSON error body. ```bash theme={null} curl --no-buffer https://agent.tinyfish.ai/v2/automation/run-research \ -H "X-API-Key: $TINYFISH_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "Compare the latest approaches to long-duration energy storage", "mode": "deep", "stream": true, "domain_type": "web" }' ``` Each SSE message is a `data:` line containing JSON. Save the `research_run_id` from the `created` event and stop reading after `done`. ```text theme={null} data: {"event":"created","research_run_id":"..."} data: {"event":"plan_updated","iteration":1,...} data: {"event":"final_result","result":"...","citations":[...],"termination_reason":"planner_done"} data: {"event":"done"} ``` ## Modes | Mode | Best for | Typical time | Browser agents | | ---------- | --------------------------------------- | ------------ | -------------- | | `standard` | Fast, source-backed answers | 2–10 minutes | No | | `deep` | Broader coverage and stronger 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 | Streams synthesis text through `synthesis_delta` events | | `output_language` | `string` | No | BCP 47 language 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 or require specified domains and block others | | `prior_run_id` | `string` | No | Seed a new run with a completed report | | `session_id` | `UUID` | No | Continue a standard-mode research session | Do not combine `recency_minutes` with `after_date` or `before_date`. Date and recency filters are unavailable for `research_paper` searches. `session_id` and `prior_run_id` are mutually exclusive. ### Domain filtering Use `include` to prioritize listed domains while retaining other results. Use `exclusive` to restrict results to the allowlist. Blocked domains are always removed. Each list accepts at most 150 entries. ```json theme={null} { "domain_filter": { "mode": "exclusive", "domains": ["who.int", "cdc.gov"], "block": [] } } ``` ## Read the event stream ```python theme={null} import json import os import httpx payload = {"query": "What changed in battery recycling this year?", "mode": "deep", "stream": True} headers = {"X-API-Key": os.environ["TINYFISH_API_KEY"]} with httpx.stream( "POST", "https://agent.tinyfish.ai/v2/automation/run-research", headers=headers, json=payload, timeout=2700, ) as response: response.raise_for_status() for line in response.iter_lines(): if not line.startswith("data: "): continue event = json.loads(line[6:]) if event["event"] == "synthesis_delta": print(event["delta"], end="", flush=True) elif event["event"] == "final_result": citations = event["citations"] elif event["event"] == "done": break ``` Important events include: | Event | Purpose | | ------------------------------------------- | ------------------------------------------------------------ | | `created` | Supplies the research run ID | | `session` | Supplies the reusable conversation session ID | | `plan_updated` | Reports the current subquestions and searches | | `sources_searched` | Lists candidate sources | | `source_fetched` | Reports static source extraction | | `agent_run_started` / `agent_run_completed` | Reports browser-agent work in Max mode | | `partial_summary` | Supplies a completed intermediate synthesis | | `synthesis_delta` | Streams partial or final report text when enabled | | `evidence_snapshot` | Supplies the current evidence set | | `final_result` | Supplies the final report, citations, and termination reason | | `run_stats` | Supplies final iteration, source, agent, and claim counts | | `error` | Reports a pipeline failure | | `done` | Always terminates the stream | Ordered `synthesis_delta` values for a checkpoint reconstruct its matching summary or final result. If `synthesis_discarded` appears, discard the provisional partial checkpoint. Heartbeats keep long-running connections open. ## Continue prior research Pass `prior_run_id` to seed a new session with a completed report and its evidence. To continue an existing standard-mode conversation, pass the `session_id` emitted by the earlier run. ```json theme={null} { "query": "Which conclusion has the strongest primary-source support?", "mode": "standard", "session_id": "019..." } ``` ## Retrieve saved runs Fetch one run with `GET /v1/research-run/{research_run_id}`. List runs with `GET /v1/research-run`; supported filters are `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. ```bash theme={null} curl "https://agent.tinyfish.ai/v1/research-run?status=COMPLETED&limit=20" \ -H "X-API-Key: $TINYFISH_API_KEY" ``` Research creation is limited by both concurrent runs and completed runs per Pacific calendar day. A limit response uses HTTP `429`; daily-limit responses include `Retry-After` and `X-RateLimit-*` headers. `/v1/automation/run-research` remains available for compatibility. New integrations should use v2.