> ## 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 API Reference

> Complete reference for research requests, streams, and saved runs

## Endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/automation/run-research` | `POST` | Start a research run and stream progress |
| `/v1/automation/run-research-async` | `POST` | Start asynchronously and return a run ID |
| `/v1/research-run/{research_run_id}/events` | `GET` | Attach or reconnect to progress |
| `/v1/research-run` | `GET` | List saved research runs |
| `/v1/research-run/{research_run_id}` | `GET` | Retrieve one saved run |
| `/v1/research-run/{research_run_id}/cancel` | `POST` | Cancel a running research run |

All endpoints use `https://agent.tinyfish.ai` and require the `X-API-Key` header.

> [!NOTE]
>
> Research must be enabled for the API key's account. `POST /v1/automation/run-research` returns `403` when it is not.

## Modes

| Mode | Best for | Typical time |
| - | - | - |
| `deep` | Broader coverage and synthesis | 5–20 minutes |
| `max` | Complex research | 5–45 minutes |

An omitted mode selects `deep`. Both modes research with search and static fetches.

## Request Body

| Field | Type | Required | Notes |
| - | - | - | - |
| `query` | `string` | Yes | Research question, 1–10,000 characters |
| `mode` | `deep \| max` | No | Defaults to `deep` |
| `stream` | `boolean` | No | Emits synthesis text through `synthesis_delta` |
| `output_language` | `string` | No | BCP 47 tag such as `en`, `ja`, or `pt-BR` |
| `domain_filter` | `object` | No | Prefer, require, or block specified domains |
| `prior_run_id` | `string` | No | Seed a run with a completed report |
| `session_id` | `UUID` | No | Continue an earlier research session |

> [!NOTE]
>
> `session_id` and `prior_run_id` are mutually exclusive. See [continuation examples](https://docs.tinyfish.ai/tinyresearch/examples.md#continue-research).

## Errors

| HTTP | `error.code` | When |
| - | - | - |
| `400` | `INVALID_INPUT` | Body is not valid JSON, or a field such as `mode` or `query` is invalid |
| `402` | `INSUFFICIENT_CREDITS` | Wallet balance is empty; see [Limits](#limits) |
| `403` | `FORBIDDEN` | Research isn't enabled for this account, or `prior_run_id` belongs to another user |
| `404` | `NOT_FOUND` | `prior_run_id` or `session_id` does not exist |
| `429` | `RATE_LIMIT_EXCEEDED` | Maximum concurrent Research runs reached; see [Limits](#limits) |
| `503` | `SERVICE_BUSY` | Research is temporarily unavailable; retry shortly; see [Limits](#limits) |

## Event Stream

Accepted requests return `text/event-stream`, including when `stream` is omitted or false. Invalid input and other
pre-run failures return the standard JSON error body.

| Event | Purpose |
| - | - |
| `created` | Supplies the research run ID |
| `session` | Supplies a reusable conversation session ID |
| `plan_updated` | Reports current subquestions and searches |
| `sources_searched` | Lists candidate sources |
| `source_fetched` | Reports static source extraction |
| `partial_summary` | Supplies an intermediate synthesis |
| `synthesis_started` | Searching is over; the final report is being written |
| `synthesis_delta` | Streams report text when enabled |
| `synthesis_discarded` | Discard provisional content for the named checkpoint |
| `heartbeat` | Keep the long-running connection open |
| `evidence_snapshot` | Supplies the current evidence set |
| `final_result` | Supplies the report, citations, and termination reason |
| `run_stats` | Supplies final source and claim counts |
| `error` | Reports a pipeline failure |
| `done` | Terminates the stream |
| `run_status` | Reports the run's current status |
| `replay_complete` | Marks the end of replayed events on reconnect |
| `sources_searching` | Lists searches about to run |
| `sources_fetching` | Lists URLs about to be fetched |
| `site_mapped` | Reports links found on a mapped site |

Ignore event types you don't recognise; new ones may be added.

Ordered `synthesis_delta` values reconstruct their matching summary or final result. Discard a provisional partial
checkpoint after `synthesis_discarded`. Heartbeats keep long-running connections open.

Every stream response carries an `X-Research-Run-Id` header with the run ID. Retained progress events expire 1 hour
after they are written; after that, read saved results with `GET /v1/research-run/{research_run_id}`.

## Run Statuses

| Status | Meaning |
| - | - |
| `QUEUED` | Accepted and waiting for a research worker. |
| `RUNNING` | The run is in progress. |
| `COMPLETED` | The run finished and its report is saved. |
| `FAILED` | The pipeline failed before producing a report. |
| `CANCELLED` | The run was cancelled through the cancel endpoint. |
| `TIMED_OUT` | The run exceeded the 45-minute time budget. |

`COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT` are terminal. Both modes share the same 45-minute budget.

## List Saved Runs

`GET /v1/research-run` supports `status`, `query`, `created_after`, and `created_before`. Pagination uses `limit` from
1–100 (default 20), `sort_direction=asc|desc` (default `desc`), and the returned `next_cursor`. Reuse a cursor only with the same sort direction.

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/research-run?status=COMPLETED&limit=20" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "research_run_id": "019...",
      "status": "COMPLETED",
      "query": "Compare long-duration energy storage approaches",
      "quick_result": { "answer": "...", "citations": ["https://example.com"] },
      "quick_result_summary": "...",
      "deep_result": { "result": "...", "citations": ["https://example.com"] },
      "run_ids": [],
      "created_at": "2026-09-09T16:00:00.000Z",
      "completed_at": "2026-09-09T16:07:41.000Z"
    }
  ],
  "pagination": {
    "total": 34,
    "next_cursor": "eyJ...",
    "has_more": true
  }
}
```

`quick_result` holds answers from runs made before standard mode was removed; `deep_result` holds the report. Both are objects: read the
report from `deep_result.result`, not from `deep_result` itself. `quick_result_summary` is the one plain string.
`run_ids` lists the Agent runs a Max run started. Fields that do not apply to the run are `null`.

## Retrieve One Run

`GET /v1/research-run/{research_run_id}` returns the list fields plus the working state kept for the run.

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

| Field | Notes |
| - | - |
| `research_plan` | Subquestions and searches the run planned |
| `evidence` | Sources gathered, with the claims they support |
| `iterations` | Number of plan-search-synthesize iterations completed |

A run that does not exist returns HTTP `404`. A run owned by another user returns HTTP `403`. Any API key
of the user who started the run can read it.

## Completion Metadata

Saved reports can include `deep_result.termination_reason` and `deep_result.freshness_report`. Both fields are
optional on older runs. The SSE `final_result` event includes the termination reason; retrieve the saved run for
the freshness report.

| `termination_reason` | Meaning |
| - | - |
| `planner_done` | The agent finished researching and produced its report; this is not a quality score. |
| `max_iterations` | The research step budget was exhausted. |
| `deadline` | The research time budget was reached and available evidence was synthesized. |
| `synthesis_failed` | Final synthesis failed; the returned report contains interim findings. |
| `planner_no_queries`, `abort` | Compatibility values that may appear in saved results. |

`COMPLETED` describes the saved run status. Check the termination reason before treating the report as a full
final synthesis, especially when it is `synthesis_failed`.

| `freshness_report` field | Meaning |
| - | - |
| `latest_published_date` | Latest extracted publication date, when available; may contain only a year or month. |
| `sources_with_dates` | Usable evidence sources with an extracted publication date. |
| `sources_without_dates` | Usable evidence sources without an extracted publication date. |
| `fetched_at_latest` | Most recent source fetch timestamp; fetching today does not imply publication today. |
| `filter_applied` | Legacy search filters, when present on an older run. |
| `sources_in_requested_window` | Sources overlapping a requested date window; `0` when no window was requested. |

Freshness describes source-date coverage, not accuracy or credibility. Dates come from source metadata or extraction
and may be missing. Current requests do not accept date-window filters.

`deep_result.follow_up_suggestions` lists up to three short follow-up questions written from the report, for
runs started from the TinyFish app in ChatGPT or Claude. It is absent on other runs and when none could be generated.

For example, a saved `deep_result` can contain:

```json theme={null}
{
  "result": "The cited report...",
  "citations": ["https://example.com/source"],
  "termination_reason": "planner_done",
  "freshness_report": {
    "latest_published_date": "2026-11-02",
    "sources_with_dates": 16,
    "sources_without_dates": 11,
    "sources_in_requested_window": 0,
    "fetched_at_latest": "2026-11-04T18:06:15.312Z"
  }
}
```

## Cancel a Run

Call `POST /v1/research-run/{research_run_id}/cancel` to cancel a running research run. The response reports whether
this request changed the run to `CANCELLED` and includes its current status.

```json theme={null}
{
  "research_run_id": "019...",
  "status": "CANCELLED",
  "cancelled": true
}
```

Cancellation is idempotent. A run that is already terminal returns HTTP `200` with `cancelled: false` and its current
status. A missing run, or a run owned by another user, returns HTTP `404`.

## Limits

Limits apply per user across all your API keys, MCP, CLI, SDKs and the dashboard.

**Pricing.** Each completed run is charged to your wallet: `deep` costs $2 per run and `max` $3 per run. A run is
charged when it completes; failed, timed-out and cancelled runs are not charged.

**Follow-ups.** Each follow-up creates a new research run and costs the selected mode’s normal rate. Continuing a
session does not make the run free or discounted. See [continuation examples](https://docs.tinyfish.ai/tinyresearch/examples.md#continue-research).

**Concurrent runs.** You can have up to 5 runs in progress by default. Contact support if you need higher limits.

**Overdraft.** Admission checks your balance when a run starts; the charge happens when it completes.
Runs already admitted are never stopped. If several runs are in flight, all of them are charged even
if that takes your balance below zero.

Starts need a positive wallet balance. With a balance of zero or below, starts return HTTP `402` with
`error.code` set to `INSUFFICIENT_CREDITS` until you add funds at the [wallet page](https://agent.tinyfish.ai/wallet).
The body has no `details`.

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Your TinyFish wallet balance is empty. Add funds at https://agent.tinyfish.ai/wallet?utm_source=api&utm_medium=insufficient_funds&utm_campaign=research"
  }
}
```

Starting a run beyond the concurrent limit returns HTTP `429` with `error.code` set to `RATE_LIMIT_EXCEEDED` and a
`Retry-After: 30` header. No run is created. This check runs after the balance check, so a `402` takes precedence.
`details.active_research_run_ids` lists up to 10 of your queued or running runs, newest first, so you can poll them before starting another.

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Maximum of 5 concurrent Research runs reached",
    "details": {
      "active_count": 5,
      "limit": 5,
      "active_research_run_ids": ["01a17c7e-285d-7ada-b276-f40f816d69bc"]
    }
  }
}
```

HTTP `503` with `error.code` set to `SERVICE_BUSY` means billing or the concurrency store is temporarily unavailable;
retry after a short pause. If the billing check does not answer in time, the run starts and is billed normally when it
completes.

## Start asynchronously

Use `POST /v1/automation/run-research-async` to enqueue research and return immediately:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/automation/run-research-async \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare long-duration energy storage approaches","mode":"deep"}'
```

After durable dispatch, the endpoint returns HTTP `200` with:

```json theme={null}
{ "research_run_id": "019a1234-1234-7000-8000-123456789abc", "error": null }
```

This follows TinyFish's asynchronous automation convention. Poll by ID to retrieve current status and results; the
worker may already be running when you receive it.

* `GET /v1/research-run/{id}` returns current state and saved partial/final results.
* `GET /v1/research-run/{id}/events` streams progress; reconnect with `Last-Event-ID`.
* `POST /v1/research-run/{id}/cancel` explicitly cancels work.

States are `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT`. The last four are terminal; stop
polling when one is returned. Partial results can exist on unsuccessful runs, so inspect `status` before treating a
report as complete. Disconnecting an event stream does not cancel the job. Retained progress events expire; polling
remains the durable source for saved results.

For a single-request stream, keep using `POST /v1/automation/run-research`. The request field `stream` controls
synthesis text deltas, not async versus SSE delivery. Both start endpoints accept the same research parameters and
limits.

Polling responses also include `error`: `null` for queued, running, or completed runs, otherwise `{code, message}` with
`TASK_FAILED`, `CANCELLED`, or `TIMEOUT`. These describe the persisted terminal outcome, not a
detailed provider failure. Existing result fields remain available, including partial reports.

Async starts are not idempotent. Retrying a POST after a timeout can create a
second run and incur additional usage. Keep the returned `research_run_id` and
poll or reconnect to that run. If no ID was received, the run may still have been
accepted; check your run list before starting another.

Incompatible optional fields in older saved runs return `null` and are logged;
other valid report fields remain readable.


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