Skip to main content

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.

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.
If you’re running inside an MCP-compatible host (Claude Code, Claude Desktop, Cursor, Windsurf), connect via MCP instead of the REST API — no API key management needed, OAuth handles auth automatically. 
npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
See the MCP Integration guide for all supported clients and available tools.

​
Install the SDK

pip install tinyfish
APITypical LatencySuggested Timeout
Agent (sync)15-60s120s
Agent (SSE)15-60s (streaming)N/A (SSE)
Search1-3s10s
Fetch1-20s150s
Browser (create)10-30s60s
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

APIUse it whenDocs
AgentYou want TinyFish to execute a goal on a real websiteAgent reference
SearchYou want ranked web results for a querySearch overview
FetchYou want extracted page content from one or more URLsFetch overview
BrowserYou want a remote browser session for direct Playwright/CDP controlBrowser 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)

​
SDK Examples

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)

​
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)

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

​
Fetch

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

​
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),
)

​
Expected Latency

APITypical LatencySuggested Timeout
Agent (sync)15-60s120s
Agent (SSE)15-60s (streaming)N/A (SSE)
Search1-3s10s
Fetchup to 30s per URL120s
Browser (create)10-30s60s

​
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

  1. Browser API session creation takes 10-30s — set timeout=60 on your HTTP client.
  2. TypeScript needs "type": "module" in package.json for top-level await, or wrap code in async function main() { ... }; main().
  3. COMPLETED status does not mean the goal succeeded — always check result_json for failure signals like “captcha”, “blocked”, or “access denied”.
  4. 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.
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)