> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TinyResearch

> Create source-backed research reports and stream their progress

TinyResearch 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.

```bash theme={null}
POST https://agent.tinyfish.ai/v1/automation/run-research
```

## Before You Start

**1. Get your API key**

Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).

**2. Store it in your environment**

```bash theme={null}
export TINYFISH_API_KEY="your_api_key_here"
```

All requests require the `X-API-Key` header. See [Authentication](https://docs.tinyfish.ai/authentication.md) for setup and troubleshooting.

## Your First Request

```python Python theme={null}
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)
```

```typescript TypeScript theme={null}
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);
```

```bash cURL theme={null}
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.

```text theme={null}
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.

## Read Next

> [card] [Research reference](https://docs.tinyfish.ai/tinyresearch/reference.md)
>
> Request fields, modes, stream events, limits, and retrieval

> [card] [Research examples](https://docs.tinyfish.ai/tinyresearch/examples.md)
>
> Filtering, continuations, and saved runs

> [card] [MCP research tools](https://docs.tinyfish.ai/mcp-integration.md#deep-research)
>
> Run deep research from Claude, ChatGPT, Cursor, and other MCP clients

> [card] [CLI research commands](https://docs.tinyfish.ai/cli/commands.md#tinyfish-research-run)
>
> Start, watch, and manage research runs from your terminal


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.