How to Use TinyResearch for Cited Reports from the Live Web

TinyResearch searches the web, reads sources, and turns a plain-English question into a Markdown report with numbered citations. You can use it in the TinyFish playground or through the deep research API. This guide covers the playground workflow, research modes, API examples, source controls, and beta limits.

It's been in public beta since Sept. 29, 2026, open to every TinyFish account. The playground and the API still call it "Research."

TinyResearch vs TinySearch

• TinySearch returns ranked links and snippets for source discovery. Use it when you want search results to work with.
• TinyResearch searches across multiple sources and synthesizes a cited report. Use it when you would otherwise run several searches, read the pages, and write the summary yourself.

More in our guide on which TinyFish API to use.

How to Use TinyResearch in the Playground

1. Sign in at agent.tinyfish.ai and open Playground, then Research.

2. Type a question (up to 2,000 characters) or click an example. Ours is "Compare Stripe vs Braintree for a SaaS startup: fees, coverage and developer experience."

3. Click the mode selector beside the gauge icon to choose a research mode and output language. The Sites menu next to it pins or blocks domains: "include" prefers your pinned sites, "exclusive" reads only those.

4. Review the plan. TinyResearch shows the subquestions it intends to answer. If one is off, type a note like "focus on US pricing" and click Refine plan. Otherwise click Approve & start research.

💡Plan review is the part we like most. If you do nothing, it approves itself after two minutes.

5. Let it run. The feed shows searches and page reads as they happen, and an interim summary fills in as evidence arrives.

6. Read the report: inline citations like [3], a numbered source list and an outline.

TinyResearch Modes and Run Times

💡 A Deep run usually takes 10-15 minutes, so go do something else and come back.

Follow-Up Research, Sharing, and PDF Export

• Follow-ups run as new research runs in the same session, so each one counts toward your daily limit.
• Share lets you add people by email (they sign in to view) or open it to anyone with the link.
• PDF export lives on the shared page, so share first, then click Export PDF.

How to Use the TinyResearch Deep Research API

The API runs the same research without plan review, so runs start the moment you send them. Create a key at agent.tinyfish.ai/api-keys and pass it as X-API-Key.

Stream Research Progress with Server-Sent Events

POST /v1/automation/run-research streams progress as server-sent events:

curl --no-buffer https://agent.tinyfish.ai/v1/automation/run-research \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "Compare Stripe vs Braintree for a SaaS startup", "mode": "standard"}'

data: {"event":"created","research_run_id":"019..."}
data: {"event":"plan_updated","subquestions":[...],"search_queries":[...]}
data: {"event":"source_fetched", ...}
data: {"event":"final_result","result":"<markdown report>","citations":["https://..."]}
data: {"event":"done"}

A heartbeat arrives every 15 seconds. Add "stream": true if you want the report text as it's written.

Start an Asynchronous Research Run

Most backends shouldn't hold a connection open for minutes. The async endpoint returns a run ID right away:

import os, time, httpx

API = "https://agent.tinyfish.ai"
HEADERS = {"X-API-Key": os.environ["TINYFISH_API_KEY"]}

start = httpx.post(f"{API}/v1/automation/run-research-async", headers=HEADERS,
                   json={"query": "Map humanoid robot deployments in 2026", "mode": "deep"})
run_id = start.json()["research_run_id"]

while True:
    run = httpx.get(f"{API}/v1/research-run/{run_id}", headers=HEADERS).json()
    if run["status"] in {"COMPLETED", "FAILED", "CANCELLED", "TIMED_OUT"}:
        break
    time.sleep(30)

if run["status"] == "COMPLETED":
    print(run["deep_result"]["result"])  # Standard runs return quick_result instead

⚠️ Async starts aren't idempotent, so don't retry blindly. Keep the ID and poll it

• Live progress - attach to GET /v1/research-run/{id}/events and reconnect with Last-Event-ID. Disconnecting doesn't cancel the run.
• Audit - the single-run response includes the plan and evidence.
• Cancel - POST /v1/research-run/{id}/cancel stops a run and is safe to call twice.

Filter Research Sources with the API

The API adds controls the playground doesn't have: date windows, source type and community sources.

{
  "query": "What changed in EU AI Act enforcement guidance this year?",
  "mode": "deep",
  "domain_type": "news",
  "after_date": "2026-01-01",
  "domain_filter": { "mode": "include", "domains": ["europa.eu"], "block": [] },
  "output_language": "de"
}

• domain_type is web, news or research_paper. Date filters don't apply to papers.
• Use either after_date/before_date or recency_minutes, not both.
• Domain lists take up to 150 entries.
• weak_sources_enabled: true lets in social and community sources.
• output_language takes any BCP 47 language tag.
• For follow-ups, pass session_id in Standard or prior_run_id in Deep and Max, never both.

See the TinyResearch API reference for the full field list.

TinyResearch Beta Limits

• Failed, cancelled and timed-out runs don't count against the daily limit.
• Hitting either limit returns a 429 with Retry-After.
• We can raise limits if you ask.

Current TinyResearch Limitations

• No MCP tool, SDK method or CLI. Just the playground and REST.
• No completion notifications or schedules. Over the API, you can poll for completion or follow the event stream. For recurring checks on a page or topic, TinyMonitor is the better fit.
• Public web only. Nothing behind a login.
• Markdown out. You get a cited report, not JSON fields you define.

TinyResearch Use Cases

• Market maps - "where are humanoid robots being deployed, and by whom?" Rerun next quarter with prior_run_id to see what moved.
• Vendor comparisons - each fee and coverage claim cites its page, so procurement can check the number before anyone signs.
• Background before a call - what a company launched this year and how it prices.
• Regulation comparisons - how two rule sets differ, like the EU AI Act vs the Colorado AI Act.

We also wrote up how we built our deep research system. Run your first research question in the TinyFish playground, or integrate the deep research API using the TinyResearch documentation.