Research API

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 stream, including when stream is omitted or false. Invalid input and other failures before a run starts return the standard JSON error body.

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.

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.

{
  "domain_filter": {
    "mode": "exclusive",
    "domains": ["who.int", "cdc.gov"],
    "block": []
  }
}

Read the event stream

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.

{
  "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.

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.

Start Here

Agent API

Search API

Fetch API

Browser API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Research API

Start a research run

Modes

Request body

Domain filtering

Read the event stream

Continue prior research

Retrieve saved runs

​Start a research run

​Modes

​Request body

​Domain filtering

​Read the event stream

​Continue prior research

​Retrieve saved runs

Start a research run

Modes

Request body

Domain filtering

Read the event stream

Continue prior research

Retrieve saved runs