Research

A source-backed research report. TinyFish plans sub-questions, searches, reads sources and writes a cited synthesis.

POST/api/v1/research200000 base units · 0.2 USDT

Price depends on mode: deep is 0.2 USDT, and max is 0.5 USDT. The 402 response quotes the exact amount for your request body.

Research takes 5–45 minutes, which is longer than an HTTP request can stay open. The paid call starts the run and returns its ID straight away, and you follow it on the free endpoints below. Payment settles when the run is accepted.

Body

Field	Type
`query`	string	Required. 1–2000 chars.
`mode`	`deep` \| `max`	Default `deep` (5–20 min). `max` takes 5–45 min.
`output_language`	string	BCP 47, e.g. `en`, `ja`, `pt-BR`.
`stream`	boolean	Emit report text as `synthesis_delta` events.
`weak_sources_enabled`	boolean	Allow relevant social and community sources.
`domain_type`	`web` \| `news` \| `research_paper`
`after_date` / `before_date` / `recency_minutes`		Same rules as Search.
`domain_filter`	`{ mode: "include" \| "exclusive", domains?, block? }`	Up to 150 entries each.

Response

json

{
  "research_run_id": "019a1234-1234-7000-8000-123456789abc",
  "status": "QUEUED",
  "mode": "deep",
  "poll_url": "/api/v1/research/019a1234-…",
  "events_url": "/api/v1/research/019a1234-…/events"
}

Follow the run (free)

Live events: GET /api/v1/research/{id}/events (SSE). Events include created, plan_updated, sources_searched, source_fetched, partial_summary, synthesis_delta, final_result (report, citations, termination reason), run_stats, error and done. Each stream connection closes after 5 minutes. Reconnect (optionally with Last-Event-ID) until you see done. Disconnecting does not cancel the run.

const run = await (await paidFetch(".../api/v1/research", { method: "POST", headers, body })).json();
const res = await fetch(`https://your-domain.com${run.events_url}`);
// parse SSE; stop at {"event":"final_result", "result": "...markdown...", "citations": [...]}

Poll: GET /api/v1/research/{id} returns status (QUEUED, RUNNING, COMPLETED, FAILED, CANCELLED or TIMED_OUT) and, once done, deep_result.result (the report) with citations. Events expire after an hour, but polling always works.