Skip to main content
In this guide you’ll run a single automation that visits a live store, reads the page like a person would, and returns the first two product names and prices as structured JSON — no selectors, no scraping rules, just a goal in plain English.
Expected result
{
  "products": [
    { "name": "Bulbasaur", "price": "£63.00" },
    { "name": "Ivysaur", "price": "£87.00" }
  ]
}
Pick the language you’ll build in (Python, TypeScript, the CLI, or raw cURL) and follow the same five steps.
1

Sign in to TinyFish

Sign up for a new account, or log in if you already have one. New accounts include free credits, so you can run this example right away.
2

Get your API key

  1. Go to the API Keys page
  2. Click “Create API Key”
  3. Save the key to your shell environment so the SDKs and CLI can read it automatically
API keys are shown only once, at creation. Store them securely and never commit them to version control.
export TINYFISH_API_KEY=sk-tinyfish-*****
3

Install the SDK

Install the package for your language. The SDKs and CLI read TINYFISH_API_KEY from your environment, so there’s nothing else to configure.
# A virtual environment keeps the install isolated and works on
# macOS Homebrew Python, which blocks system-wide pip (PEP 668).
python3 -m venv .venv && source .venv/bin/activate
pip install tinyfish
4

Write your automation

Create a file with the minimal code to navigate to the store and extract product data using natural language. (cURL users can skip straight to the next step.)
# first_automation.py
from tinyfish import TinyFish, CompleteEvent

client = TinyFish()  # Reads TINYFISH_API_KEY from environment

# Stream the automation and print the structured result
with client.agent.stream(
    url="https://scrapeme.live/shop",  # Target website to automate
    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)
The goal is a plain-English instruction. See the Prompting Guide and Structured Output to reliably get JSON shaped exactly how you want it.
5

Run it

Execute your automation. Each tab runs against the same goal and URL.
python first_automation.py
6

Verify the output

What you see depends on how you ran the automation.Python, TypeScript, and cURL stream raw Server-Sent Events as the agent works. The final COMPLETE event carries your result:
{'type': 'STARTED', 'run_id': 'abc123'}
{'type': 'STREAMING_URL', 'run_id': 'abc123', 'streaming_url': 'https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0'}
{'type': 'PROGRESS', 'run_id': 'abc123', 'purpose': 'Visit the page to extract product information'}
{'type': 'PROGRESS', 'run_id': 'abc123', 'purpose': 'Check for product information on the page'}
{'type': 'COMPLETE', 'run_id': 'abc123', 'status': 'COMPLETED', 'result': {
  "products": [
    { "name": "Bulbasaur", "price": "£63.00" },
    { "name": "Ivysaur", "price": "£87.00" }
  ]
}}
The CLI consumes the same events but the --pretty flag renders them as a readable summary instead of raw JSON:
▶ Run started
• Visit the page to extract product information
• Check for product information on the page
✓ Completed

{"products": [{"name": "Bulbasaur", "price": "£63.00"}, {"name": "Ivysaur", "price": "£87.00"}]}

View run: https://agent.tinyfish.ai/runs/abc123
Either way, the result is the same structured payload — pick whichever format fits your workflow.

​
Troubleshooting

The package isn’t installed for the language you’re running.
  • Python — ModuleNotFoundError: No module named 'tinyfish' → pip install tinyfish
  • TypeScript — Cannot find module '@tiny-fish/sdk' → npm i @tiny-fish/sdk
  • CLI — command not found: tinyfish → npm install -g @tiny-fish/cli
Homebrew Python (3.11+) blocks system-wide pip install by default (PEP 668), so you’ll see error: externally-managed-environment. Create a virtual environment first, then install:
python3 -m venv .venv
source .venv/bin/activate
pip install tinyfish
python first_automation.py
You only need to run the first two lines once per project. After that, just source .venv/bin/activate to re-enter the environment.
@tiny-fish/sdk ships as ESM only, but tsx defaults to CommonJS, so you’ll see Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined. Tell Node to treat your project as ESM by adding "type": "module" to package.json:
npm pkg set type=module
Then re-run npx tsx first-automation.ts.
Requests fail with a 401 or an authentication error.
  • Confirm the key is set: echo $TINYFISH_API_KEY should print a value starting with sk-tinyfish-. If it’s empty, re-run the export command from the “Get your API key” step above.
  • If the key is wrong or lost, generate a new one on the API Keys page — keys are shown only once on creation, so you can’t recover an old one.
The run is rejected because your workspace is out of credits.
  • Top up credits, or switch to a workspace that has them, then retry.
  • See Authentication for the full error shape.

​
Next Steps

Where you go next depends on what you’re trying to build.
Your goalStart here
Building an app on the APIAgent API Reference
Need stable, predictable outputStructured Output
Real-world scraping examplesExamples
Hard sites or bot protectionAnti-Bot Guide · Browser Profiles

Agent API Reference

Streaming, async runs, and endpoint selection

Structured Output

Get consistent JSON shaped to your schema

Examples

Copy-paste ready code for real use cases

Anti-Bot Guide

Handle protected and high-friction sites