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

# Research API

> Create source-backed research reports and stream their progress

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.

<Info>**Beta:** The Research API is currently in beta.</Info>

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

## Before You Start

<Steps>
  <Step title="Get your API key">
    Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
  </Step>

  <Step title="Store it in your environment">
    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for setup and troubleshooting.

## Your First Request

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

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

  ```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": "standard"
    }'
  ```
</CodeGroup>

## 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`.

```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

<CardGroup cols={2}>
  <Card title="Research reference" icon="code" href="/research-api/reference">
    Request fields, modes, stream events, limits, and retrieval
  </Card>

  <Card title="Research examples" icon="flask" href="/research-api/examples">
    Filtering, continuations, and saved runs
  </Card>
</CardGroup>