Research API Reference

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

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.

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.

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

Start Here

Agent API

Search API

Fetch API

Browser API

Research API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Endpoints

Modes

Request Body

Event Stream

List Saved Runs

Cancel a Run

Limits

​Endpoints

​Modes

​Request Body

​Event Stream

​List Saved Runs

​Cancel a Run

​Limits

Endpoints

Modes

Request Body

Event Stream

List Saved Runs

Cancel a Run

Limits