Research API

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

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.

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

from tinyfish import TinyFish

client = TinyFish()
run = client.research.run(
    query="Compare long-duration energy storage approaches",
    mode="deep",
)
print(run.status)
if run.deep_result:
    print(run.deep_result.result)
else:
    print(run.error)

import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();
const run = await client.research.run({
  query: "Compare long-duration energy storage approaches",
  mode: "deep",
});
console.log(run.status);
console.log(run.deep_result?.result ?? run.error);

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": "deep"
  }'

Research usually takes several minutes. run() waits for the run to finish and returns the saved run, with the report and its citations in deep_result. To start a run and check it later, use queue(), then get() with the returned research_run_id. Install the SDK with pip install tinyfish or npm install @tiny-fish/sdk.

What Success Looks Like

With cURL, each Server-Sent Events message is a data: line containing JSON. Save the run ID from created and stop reading after done. The SDKs’ stream() yields the same events as typed objects.

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

MCP research tools

Run deep research from Claude, ChatGPT, Cursor, and other MCP clients

CLI research commands

Start, watch, and manage research runs from your terminal

Start Here

Agent API

Search API

Monitor

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

MCP research tools

CLI research commands

​Before You Start

​Your First Request

​What Success Looks Like

​When to Use Research vs the Other APIs

​Read Next

Research reference

Research examples

MCP research tools

CLI research commands

Before You Start

Your First Request

What Success Looks Like

When to Use Research vs the Other APIs

Read Next