Research API

The TinyFish Research API searches, evaluates sources, and synthesizes a cited report from a natural-language query. Use it when a question needs evidence across several sources rather than one search result or webpage.

Beta: The Research API is currently in beta.

POST https://agent.tinyfish.ai/v1/automation/run-research

Before You Start

Get your API key

Create an API key at agent.tinyfish.ai/api-keys.

Store it in your environment

export TINYFISH_API_KEY="your_api_key_here"

All requests require the X-API-Key header. See Authentication for setup and troubleshooting.

Your First Request

import os
import httpx

with httpx.stream(
    "POST",
    "https://agent.tinyfish.ai/v1/automation/run-research",
    headers={"X-API-Key": os.environ["TINYFISH_API_KEY"]},
    json={"query": "Compare long-duration energy storage approaches", "mode": "standard"},
    timeout=2700,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if line.startswith("data: "):
            print(line[6:])

const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-research", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TINYFISH_API_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "Compare long-duration energy storage approaches",
    mode: "standard",
  }),
});

for await (const chunk of response.body!) {
  process.stdout.write(new TextDecoder().decode(chunk));
}

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 long-duration energy storage approaches",
    "mode": "standard"
  }'

What Success Looks Like

Each Server-Sent Events message is a data: line containing JSON. Save the run ID from created and stop reading after done.

data: {"event":"created","research_run_id":"..."}
data: {"event":"plan_updated","iteration":1,...}
data: {"event":"final_result","result":"...","citations":[...]}
data: {"event":"done"}

When to Use Research vs the Other APIs

Use Research for a cited synthesis across multiple sources.
Use Search for ranked links, snippets, and source discovery.
Use Fetch when you already know which pages to extract.
Use Agent when TinyFish should interact with websites.
Use Browser when you need direct Playwright or CDP control.

Research reference

Request fields, modes, stream events, limits, and retrieval

Research examples

Filtering, continuations, and saved runs

Start Here

Agent API

Search API

Monitor (Beta)

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Before You Start

Your First Request

What Success Looks Like

When to Use Research vs the Other APIs

Read Next

Research reference

Research examples

​Before You Start

​Your First Request

​What Success Looks Like

​When to Use Research vs the Other APIs

​Read Next

Research reference

Research examples

Before You Start

Your First Request

What Success Looks Like

When to Use Research vs the Other APIs

Read Next