Research API Reference

Beta: The Research API is available to everyone while in beta. Contact support if you encounter any bugs.

Endpoints

Endpoint	Method	Purpose
`/v1/automation/run-research`	`POST`	Start a research run and stream progress
`/v1/automation/run-research-async`	`POST`	Start asynchronously and return a run ID
`/v1/research-run/{research_run_id}/events`	`GET`	Attach or reconnect to 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.

Research must be enabled for the API key’s account. POST /v1/automation/run-research returns 403 when it is not.

Modes

Mode	Best for	Typical time
`deep`	Broader coverage and synthesis	5–20 minutes
`max`	Complex research	5–45 minutes

An omitted mode selects deep. Both modes research with search and static fetches.

Request Body

Field	Type	Required	Notes
`query`	`string`	Yes	Research question, 1–2,000 characters
`mode`	`deep \| max`	No	Defaults to `deep`
`stream`	`boolean`	No	Emits synthesis text through `synthesis_delta`
`output_language`	`string`	No	BCP 47 tag such as `en`, `ja`, or `pt-BR`
`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 an earlier research 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
`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 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.

Run Statuses

Status	Meaning
`QUEUED`	Accepted and waiting for a research worker.
`RUNNING`	The run is in progress.
`COMPLETED`	The run finished and its report is saved.
`FAILED`	The pipeline failed before producing a report.
`CANCELLED`	The run was cancelled through the cancel endpoint.
`TIMED_OUT`	The run exceeded the time budget for its mode.

COMPLETED, FAILED, CANCELLED, and TIMED_OUT are terminal.

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.

curl "https://agent.tinyfish.ai/v1/research-run?status=COMPLETED&limit=20" \
  -H "X-API-Key: $TINYFISH_API_KEY"

{
  "data": [
    {
      "research_run_id": "019...",
      "status": "COMPLETED",
      "query": "Compare long-duration energy storage approaches",
      "quick_result": { "answer": "...", "citations": ["https://example.com"] },
      "quick_result_summary": "...",
      "deep_result": { "result": "...", "citations": ["https://example.com"] },
      "run_ids": [],
      "created_at": "2026-09-09T16:00:00.000Z",
      "completed_at": "2026-09-09T16:07:41.000Z"
    }
  ],
  "pagination": {
    "total": 34,
    "next_cursor": "eyJ...",
    "has_more": true
  }
}

quick_result holds answers from runs made before standard mode was removed; deep_result holds the report. Both are objects: read the report from deep_result.result, not from deep_result itself. quick_result_summary is the one plain string. run_ids lists the Agent runs a Max run started. Fields that do not apply to the run are null.

Retrieve One Run

GET /v1/research-run/{research_run_id} returns the list fields plus the working state kept for the run.

curl "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Field	Notes
`research_plan`	Subquestions and searches the run planned
`evidence`	Sources gathered, with the claims they support
`iterations`	Number of plan-search-synthesize iterations completed

A run that does not exist returns HTTP 404. A run owned by another API key returns HTTP 403.

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 is limited by concurrent runs (5 per account by default) and by a daily free allowance of runs (5 per day by default) that resets at 00:00 UTC. A run counts against the allowance when it completes; runs that fail, time out, or are cancelled do not count. Contact support if you need higher limits. Starting a run beyond the concurrent limit returns HTTP 429 with error.code set to RATE_LIMIT_EXCEEDED. While Research is in beta it does not charge your wallet: once the day’s allowance is used, starts return HTTP 402 with error.code set to FREE_ALLOWANCE_EXHAUSTED until the allowance resets. When Research charges the wallet, runs beyond the allowance need a positive wallet balance instead; with a balance of zero or below, starts return HTTP 402 with INSUFFICIENT_CREDITS until you add funds or the allowance resets.

{
  "error": {
    "code": "FREE_ALLOWANCE_EXHAUSTED",
    "message": "Daily free Research allowance used; it resets at 00:00 UTC."
  }
}

If billing is temporarily unavailable, the request returns HTTP 503 with error.code set to SERVICE_BUSY; retry after a short pause. If the billing check itself does not answer in time, the run starts.

Start asynchronously

Use POST /v1/automation/run-research-async to enqueue research and return immediately:

curl -X POST https://agent.tinyfish.ai/v1/automation/run-research-async \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare long-duration energy storage approaches","mode":"deep"}'

After durable dispatch, the endpoint returns HTTP 200 with:

{ "research_run_id": "019a1234-1234-7000-8000-123456789abc", "error": null }

This follows TinyFish’s asynchronous automation convention. Poll by ID to retrieve current status and results; the worker may already be running when you receive it.

GET /v1/research-run/{id} returns current state and saved partial/final results.
GET /v1/research-run/{id}/events streams progress; reconnect with Last-Event-ID.
POST /v1/research-run/{id}/cancel explicitly cancels work.

States are QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED, and TIMED_OUT. The last four are terminal; stop polling when one is returned. Partial results can exist on unsuccessful runs, so inspect status before treating a report as complete. Disconnecting an event stream does not cancel the job. Retained progress events expire; polling remains the durable source for saved results. For a single-request stream, keep using POST /v1/automation/run-research. The request field stream controls synthesis text deltas, not async versus SSE delivery. Both start endpoints accept the same research parameters and limits. Polling responses also include error: null for queued, running, or completed runs, otherwise {code, message} with TASK_FAILED, CANCELLED, or TIMEOUT. These describe the persisted terminal outcome, not a detailed provider failure. Existing result fields remain available, including partial reports. Async starts are not idempotent. Retrying a POST after a timeout can create a second run and incur additional usage. Keep the returned research_run_id and poll or reconnect to that run. If no ID was received, the run may still have been accepted; check your run list before starting another. Incompatible optional fields in older saved runs return null and are logged; other valid report fields remain readable.

Start Here

Agent API

Search API

Monitor

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Endpoints

Modes

Request Body

Event Stream

Run Statuses

List Saved Runs

Retrieve One Run

Cancel a Run

Limits

Start asynchronously

​Endpoints

​Modes

​Request Body

​Event Stream

​Run Statuses

​List Saved Runs

​Retrieve One Run

​Cancel a Run

​Limits

​Start asynchronously

Endpoints

Modes

Request Body

Event Stream

Run Statuses

List Saved Runs

Retrieve One Run

Cancel a Run

Limits

Start asynchronously