Skip to main content
The TinyFish Agent API lets you describe a task in natural language and have TinyFish execute it on a real website. Use it when you want goal-based automation rather than low-level browser scripting.
The Agent API is the right choice when TinyFish should decide the browser actions. If you need direct browser control instead, use the Browser API.

​
Canonical Endpoints

EndpointPatternBest for
/runSynchronousQuick tasks and simple integrations
/run-asyncStart then pollLong tasks and batch processing
/run-sseLive event streamReal-time progress in user-facing apps
POST https://agent.tinyfish.ai/v1/automation/run-sse

​
Before You Start

1

Get your API key

Create an API key at agent.tinyfish.ai/api-keys.
2

Store it in your environment

export TINYFISH_API_KEY="your_api_key_here"
All requests require the X-API-Key header. See Authentication for the full setup and troubleshooting guide.

​
Your First Request

from tinyfish import TinyFish

client = TinyFish()

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

​
What Success Looks Like

{"type":"STARTED","run_id":"abc123"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Visit the page to extract product information"}
{"type":"PROGRESS","run_id":"abc123","purpose":"Extract the first two products and prices"}
{"type":"COMPLETE","run_id":"abc123","status":"COMPLETED","result":{"products":[{"name":"Bulbasaur","price":"$63.00"},{"name":"Ivysaur","price":"$87.00"}]}}
If you want a blocking request that returns only the final result, use /run. If you want to start work and poll later, use /run-async.

​
When to Use Agent vs the Other APIs

  • Use Agent when TinyFish should decide the browser actions from your goal.
  • Use Browser when you want to drive Playwright or CDP yourself.
  • Use Fetch when you already know the URLs and only need extracted page content.
  • Use Search when you need ranked search results rather than page automation.

​
Writing Good Goals

A goal is the plain-English instruction you pass in the goal field. TinyFish uses it to decide what to click, type, extract, and return. Good goals are:
  • specific about the output you want
  • explicit about the page or flow to follow
  • clear about response format when you need structured JSON

Agent reference

Full request schema, run lifecycle, browser profiles, and errors

Endpoint selection

Choose between /run, /run-async, and /run-sse

Runs

Understand status, polling, and completion

Goal prompting guide

Write more reliable automation instructions

Authentication

API key setup and troubleshooting