For Coding Agents

This page is the shortest high-signal context dump for coding agents integrating TinyFish. Always use the official SDKs — they handle authentication, SSE streaming, retries, and typed responses so you don’t have to.

For complete API reference in a single file, use llms-full.txt (218KB, includes all code examples). Note that llms.txt is just an index — agents should use llms-full.txt for full context.

MCP Server (Recommended for AI Assistants)

If you’re running inside an MCP-compatible host (Codex, Claude Code, Claude Desktop, Cursor, Windsurf, ChatGPT), connect via MCP instead of the REST API — no API key management needed, OAuth handles auth automatically.

Codex
Claude Code
ChatGPT

codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp

npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code

https://agent.tinyfish.ai/mcp/chatgpt

See the MCP Integration guide for all supported clients and available tools.

Install the SDK

pip install -U tinyfish

npm install @tiny-fish/sdk@latest

API	Typical Latency	Suggested Timeout
Agent (sync)	15-60s	120s
Agent (SSE)	15-60s (streaming)	N/A (SSE)
Search	1-3s	10s
Fetch	1-20s	150s
Browser (create)	10-30s	60s

Fetch: backend timeout is 110s per URL; requests are also subject to a 120s CDN ceiling. Set client timeout to 150s to receive timeout errors cleanly.

Authentication

Set your API key (get one from agent.tinyfish.ai/api-keys):

export TINYFISH_API_KEY="your_api_key_here"

Both SDKs read TINYFISH_API_KEY from the environment automatically. See Authentication for more details.

Choose the Right TinyFish API

API	Use it when	Docs
Agent	You want TinyFish to execute a goal on a real website	Agent reference
Search	You want ranked web results for a query	Search overview
Fetch	You want extracted page content from one or more URLs	Fetch overview
Browser	You want a remote browser session for direct Playwright/CDP control	Browser overview

Quick Decision Tree

Need data from a URL? — Agent API (goal-based extraction) or Fetch API (raw page content)
Need search results? — Search API
Need browser control? — Browser API (direct Playwright/CDP access)
Need logged-in state across recurring runs? — Create a Browser Context Profile, then run with use_profile: true

Authenticated or Recurring Runs

When a task should reuse a login session, use Browser Context Profiles first. Do not make the agent log in from scratch every run unless the task explicitly needs a fresh browser. Browser Context Profiles are saved browser state for a site or account. They are different from browser_profile: "lite" | "stealth", which only chooses the browser runtime mode.

Create and set up a profile

Use the Browser Context Profiles API to create a profile, start a setup session, connect to cdp_url with Playwright/Puppeteer/CDP, sign in, and save with session_id. The dashboard setup UI is a manual helper.

Run with saved state

Pass use_profile: true to use the default profile, or add profile_id for a specific profile.

Repair stale sessions with Vault

For long-lived workflows, pair profiles with use_vault: true so TinyFish can sign in again when cookies expire.

result = client.agent.run(
    url="https://app.example.com/dashboard",
    goal="Summarize the account health dashboard.",
    use_profile=True,
    use_vault=True,
)

const run = await client.agent.run({
  url: "https://app.example.com/dashboard",
  goal: "Summarize the account health dashboard.",
  use_profile: true,
  use_vault: true,
});

use_profile: true uses the default Browser Context Profile. Use profile_id when the user names a specific Browser Context Profile; profile_id requires use_profile: true:

result = client.agent.run(
    url="https://app.example.com/dashboard",
    goal="Download the latest invoice.",
    use_profile=True,
    profile_id="prof_abc123def4567890",
)

const run = await client.agent.run({
  url: "https://app.example.com/dashboard",
  goal: "Download the latest invoice.",
  use_profile: true,
  profile_id: "prof_abc123def4567890",
});

SDK Examples

Agent — Streaming (Recommended)

from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    url="https://scrapeme.live/shop",
    goal="Extract the first 2 product names and prices. Return as JSON.",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print(event.result_json)

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

const client = new TinyFish();

const stream = await client.agent.stream({
  url: "https://scrapeme.live/shop",
  goal: "Extract the first 2 product names and prices. Return as JSON.",
});

for await (const event of stream) {
  if (event.type === "COMPLETE") {
    console.log(event.result);
  }
}

Agent — Synchronous

from tinyfish import TinyFish, RunStatus

client = TinyFish()

result = client.agent.run(
    url="https://scrapeme.live/shop",
    goal="Extract the first 2 product names and prices. Return as JSON.",
)
if result.status == RunStatus.COMPLETED:
    print(result.result)

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

const client = new TinyFish();

const run = await client.agent.run({
  url: "https://scrapeme.live/shop",
  goal: "Extract the first 2 product names and prices. Return as JSON.",
});

if (run.status === RunStatus.COMPLETED) {
  console.log(run.result);
}

Search

result = client.search.query("web automation tools", location="US", language="en")
print(result)

const result = await client.search.query({
  query: "web automation tools",
  location: "US",
  language: "en",
});
console.log(result);

Use recency_minutes for a freshness window, after_date / before_date for calendar date filters, and domain_type for content category:

recency_minutes: integer 1..5256000
after_date / before_date: YYYY-MM-DD
domain_type: "web" (default) | "news" | "research_paper"
pub_year_min / pub_year_max: integer 0..9999, inclusive; only supported for domain_type=research_paper
do not combine recency_minutes with date filters
if both dates are present, after_date <= before_date
if both pub_year bounds are present, pub_year_min <= pub_year_max
after_date, before_date, and recency_minutes are not supported for domain_type=research_paper — use pub_year_min / pub_year_max instead

Fetch

result = client.fetch.get_contents(urls=["https://www.tinyfish.ai/"])
print(result)

const result = await client.fetch.getContents({
  urls: ["https://www.tinyfish.ai/"],
});
console.log(result);

Omit ttl for the default cache behavior. Add ttl only when freshness matters: set it to 0 when you want a live fetch, or to a positive number of seconds to accept cached entries younger than that window.

Anti-Detection Mode

For sites with bot protection, add stealth mode and a proxy:

from tinyfish import TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode

client = TinyFish()

result = client.agent.run(
    url="https://protected-site.com",
    goal="Extract pricing data. Return as JSON.",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
)

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

const client = new TinyFish();

const run = await client.agent.run({
  url: "https://protected-site.com",
  goal: "Extract pricing data. Return as JSON.",
  browser_profile: BrowserProfile.STEALTH,
  proxy_config: {
    enabled: true,
    country_code: ProxyCountryCode.US,
  },
});

Expected Latency

API	Typical Latency	Suggested Timeout
Agent (sync)	15-60s	120s
Agent (SSE)	15-60s (streaming)	N/A (SSE)
Search	1-3s	10s
Fetch	1-20s	150s
Browser (create)	10-30s	60s

Prompting

Goal quality determines success rate. Vague goals like “get the data” fail; crafted goals with explicit fields, output format, and edge-case handling succeed consistently.

See the full Prompting Guide for tested patterns, templates, and examples.

Common Gotchas

Browser API session creation takes 10-30s — set timeout=60 on your HTTP client.
TypeScript needs "type": "module" in package.json for top-level await, or wrap code in async function main() { ... }; main().
COMPLETED status does not mean the goal succeeded — always check result_json for failure signals like “captcha”, “blocked”, or “access denied”.
Fetch API has a 110s per-URL backend timeout — requests are also subject to a 120s CDN ceiling for the full batch. Set your client timeout to at least 150s.

Raw API Endpoints (cURL)

If you can’t use the SDKs, here are the raw endpoints. All use the X-API-Key header for authentication.

Agent

curl -N -X POST https://agent.tinyfish.ai/v1/automation/run-sse \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://scrapeme.live/shop",
    "goal": "Extract the first 2 product names and prices. Return JSON."
  }'

Search

curl "https://api.search.tinyfish.ai?query=web+automation+tools&location=US&language=en" \
  -H "X-API-Key: $TINYFISH_API_KEY"

Fetch

curl -X POST https://api.fetch.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://www.tinyfish.ai/"]}'

Browser

curl -X POST https://api.browser.tinyfish.ai \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.tinyfish.ai"}'

Agent reference

Goal-based automation, endpoint choice, runs, profiles, and proxies

Authentication

API key setup and troubleshooting

Search overview

Search query parameters and result shape

Fetch overview

Fetch multiple URLs and choose output formats

Browser overview

Create a remote browser session and connect via CDP

Examples

Copy-paste examples for common workflows

llms-full.txt

Complete API reference in a single file (218KB)

Start Here

Agent API

Search API

Fetch API

Browser API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

MCP Server (Recommended for AI Assistants)

Install the SDK

Authentication

Choose the Right TinyFish API

Quick Decision Tree

Authenticated or Recurring Runs

SDK Examples

Agent — Streaming (Recommended)

Agent — Synchronous

Search

Fetch

Anti-Detection Mode

Expected Latency

Prompting

Common Gotchas

Agent

Search

Fetch

Browser

What to Read Next

Agent reference

Authentication

Search overview

Fetch overview

Browser overview

Examples

llms-full.txt

​MCP Server (Recommended for AI Assistants)

​Install the SDK

​Authentication

​Choose the Right TinyFish API

​Quick Decision Tree

​Authenticated or Recurring Runs

​SDK Examples

​Agent — Streaming (Recommended)

​Agent — Synchronous

​Search

​Fetch

​Anti-Detection Mode

​Expected Latency

​Prompting

​Common Gotchas

​Agent

​Search

​Fetch

​Browser

​What to Read Next

Agent reference

Authentication

Search overview

Fetch overview

Browser overview

Examples

llms-full.txt

MCP Server (Recommended for AI Assistants)

Install the SDK

Authentication

Choose the Right TinyFish API

Quick Decision Tree

Authenticated or Recurring Runs

SDK Examples

Agent — Streaming (Recommended)

Agent — Synchronous

Search

Fetch

Anti-Detection Mode

Expected Latency

Prompting

Common Gotchas

Agent

Search

Fetch

Browser

What to Read Next