Research Examples

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

Stream the Final Report

Set stream: true and concatenate synthesis_delta values for live report text. The final assembled report is also included in final_result.

import json
import os
import httpx

payload = {"query": "What changed in battery recycling this year?", "mode": "deep", "stream": True}

with httpx.stream(
    "POST",
    "https://agent.tinyfish.ai/v1/automation/run-research",
    headers={"X-API-Key": os.environ["TINYFISH_API_KEY"]},
    json=payload,
    timeout=2700,
) as response:
    response.raise_for_status()
    for line in response.iter_lines():
        if not line.startswith("data: "):
            continue
        event = json.loads(line[6:])
        if event["event"] == "synthesis_delta":
            print(event["delta"], end="", flush=True)
        elif event["event"] == "done":
            break

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

const client = new TinyFish();
const stream = await client.research.stream({
  query: "What changed in battery recycling this year?",
  mode: "deep",
  stream: true,
});
for await (const event of stream) {
  if (event.event === "synthesis_delta") {
    process.stdout.write(String(event["delta"]));
  }
}

Reconnect to a Run

events() attaches to a run that is already running, replays its saved events, and follows it until done. Pass the last event id you saw to resume without replaying. Stopping the loop detaches without cancelling the run.

from tinyfish import TinyFish

client = TinyFish()
with client.research.events(research_run_id) as stream:
    for event in stream:
        print(event.event)

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

const client = new TinyFish();
const stream = await client.research.events(researchRunId);
for await (const event of stream) {
  console.log(event.event);
}

Restrict Research to Trusted Domains

Use include to prioritize domains while retaining other results. Use exclusive to restrict results to the allowlist. Blocked domains are always removed. Each list accepts at most 150 entries.

{
  "query": "Compare current public-health recommendations",
  "domain_filter": {
    "mode": "exclusive",
    "domains": ["who.int", "cdc.gov"],
    "block": []
  }
}

Continue Research

Use the session_id emitted by a run to continue its conversation.

{
  "query": "Which conclusion has the strongest primary-source support?",
  "mode": "deep",
  "session_id": "019..."
}

Use prior_run_id instead to seed a new run with a completed report and its evidence.

{
  "query": "Update this report with developments from the last week",
  "mode": "deep",
  "prior_run_id": "019..."
}

Retrieve Saved Runs

from tinyfish import TinyFish

client = TinyFish()
page = client.research.list(status="COMPLETED", limit=20)
for run in page.data:
    print(run.research_run_id, run.query)

run = client.research.get(research_run_id)
if run.deep_result:
    print(run.status, run.deep_result.result)

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

const client = new TinyFish();
const page = await client.research.list({
  status: "COMPLETED",
  limit: 20,
});
for (const run of page.data) {
  console.log(run.research_run_id, run.query);
}

const run = await client.research.get(researchRunId);
console.log(run.status, run.deep_result?.result);

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

curl "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Pass page.pagination.next_cursor as cursor to get the next page.

Cancel a Running Run

result = client.research.cancel(research_run_id)
print(result.status, result.cancelled)

const result = await client.research.cancel(researchRunId);
console.log(result.status, result.cancelled);

curl -X POST \
  "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID/cancel" \
  -H "X-API-Key: $TINYFISH_API_KEY"

{
  "research_run_id": "019...",
  "status": "CANCELLED",
  "cancelled": true
}

A run that already finished returns its status with cancelled: false.

Start Here

Agent API

Search API

Monitor

Fetch API

Browser API

Research API (Beta)

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Stream the Final Report

Reconnect to a Run

Restrict Research to Trusted Domains

Continue Research

Retrieve Saved Runs

Cancel a Running Run

​Stream the Final Report

​Reconnect to a Run

​Restrict Research to Trusted Domains

​Continue Research

​Retrieve Saved Runs

​Cancel a Running Run

Stream the Final Report

Reconnect to a Run

Restrict Research to Trusted Domains

Continue Research

Retrieve Saved Runs

Cancel a Running Run