# Browser Context Profiles API
Source: https://docs.tinyfish.ai/agent-api/browser-context-profiles

Create, set up, and use Browser Context Profiles from the Agent API

Use the Browser Context Profiles API to create persistent browser state, set it up once, and reuse it in future
Agent API runs. The happy path is simple: create a profile, save a logged-in setup session, then pass
`use_profile: true` when you run automation.

<CardGroup>
  <Card title="Browser Context Profiles overview" icon="window" href="/key-concepts/browser-context-profiles">
    Learn when to use Browser Context Profile state
  </Card>

  <Card title="Vault Credentials" icon="vault" href="/key-concepts/credentials">
    Add stale-session repair
  </Card>
</CardGroup>

## API setup lifecycle

Browser Context Profiles are API-controlled saved state. The hosted setup UI is a manual helper; API
users should bring their own Playwright, Puppeteer, or CDP controller and connect to the setup session's
`cdp_url`. Use `base_url` only for TinyFish HTTP session endpoints such as `/pages`; do not pass
`base_url` to Playwright.

<Steps>
  <Step title="Create or list profiles">
    Create a named Browser Context Profile with `/v1/profiles`, or list existing profiles and choose one.
  </Step>

  <Step title="Start setup">
    Call `POST /v1/profiles/{profileId}/setup-session` and keep the returned `session_id`,
    `cdp_url`, `base_url`, `timeout_seconds`, and `expires_at`.
  </Step>

  <Step title="Connect and log in">
    Connect your browser automation framework to `cdp_url`, then log in manually or programmatically.
  </Step>

  <Step title="Save or discard">
    Save with `POST /v1/profiles/{profileId}/save` and `{ "session_id": "..." }`. Cancelling
    setup or letting it time out discards unsaved setup state.
  </Step>

  <Step title="Run with saved state">
    Pass `use_profile: true`, or pass both `use_profile: true` and `profile_id` for a specific
    profile.
  </Step>
</Steps>

## Create a profile

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/profiles \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salesforce Production",
    "set_as_default": true,
    "proxy_country_code": "US"
  }'
```

```json theme={null}
{
  "id": "prof_abc123def4567890",
  "name": "Salesforce Production",
  "proxy_country_code": "US",
  "fingerprint_seed": "12345678",
  "created_at": "2026-06-04T18:00:00.000Z"
}
```

| Create field | Type | Notes |
| - | - | - |
| `name` | `string` | Required. 1–100 characters. |
| `set_as_default` | `boolean` | Optional. Makes this the default profile for `use_profile: true`. |
| `proxy_country_code` | `string \| null` | Optional. Supported country code, or `null` for no profile proxy. |

## Set up a profile

Start a setup browser:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/login",
    "timeout_seconds": 900
  }'
```

```json theme={null}
{
  "session_id": "sess_123",
  "cdp_url": "wss://...",
  "base_url": "https://...",
  "timeout_seconds": 900,
  "expires_at": "2026-06-04T18:15:00.000Z"
}
```

Connect to `cdp_url` with Playwright, Puppeteer, Selenium, or another CDP client. For example,
with Playwright:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { chromium } from "playwright";

  const CDP_URL = "<cdp_url from setup-session response>";
  const browser = await chromium.connectOverCDP(CDP_URL);
  const page = browser.contexts()[0].pages()[0];
  await page.goto("https://app.example.com/login");
  // Automate the login form here, or use your own CDP tooling to complete login.
  ```

  ```python Python theme={null}
  import asyncio
  from playwright.async_api import async_playwright

  CDP_URL = "<cdp_url from setup-session response>"

  async def main():
      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(CDP_URL)
          page = browser.contexts[0].pages[0]
          await page.goto("https://app.example.com/login")
          # Automate the login form here, or use your own CDP tooling to complete login.

  asyncio.run(main())
  ```
</CodeGroup>

After login, save the setup session:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/save \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_123" }'
```

```json theme={null}
{
  "domains_updated": ["example.com"],
  "domains_failed": [],
  "cookie_count": 12,
  "pages_captured": 1,
  "target_reads_skipped": 0,
  "domains_skipped": {
    "cookies_skipped": [],
    "local_storage_skipped": [],
    "session_storage_skipped": [],
    "blob_too_large": []
  }
}
```

## Save, cancel, or time out

The setup browser is temporary. If you do not save it before `expires_at`, or if you cancel it, TinyFish
discards the unsaved setup state. Cancel explicitly when you know you do not want to save:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session/cancel \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "session_id": "sess_123" }'
```

Cancelling a setup session that has already ended usually returns `{ "cancelled": true }`. Saving a
session again after a successful save usually returns the first save's result. New sites you pass in
`signed_in_sites` are still checked against what the first save captured, and recorded if they pass.
If that result is no longer available, or the profile was deleted, you get the usual not-found error.

## Run with a Browser Context Profile

Use your default Browser Context Profile:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://app.example.com/dashboard",
    "goal": "Summarize the account health dashboard",
    "use_profile": true
  }'
```

Use a specific Browser Context Profile:

```bash theme={null}
curl -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://app.example.com/dashboard",
    "goal": "Summarize the latest invoice, including the amount due and payment deadline.",
    "use_profile": true,
    "profile_id": "prof_abc123def4567890"
  }'
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `use_profile` | `boolean` | No | Use Browser Context Profile state. Without `profile_id`, TinyFish uses your default Browser Context Profile. |
| `profile_id` | `string` | No | Selects a specific profile. Requires `use_profile: true`. |

<Note>
  If `use_profile: true` is set and no default profile exists, the run returns `400`. Create a
  profile and set it as default first.
</Note>

## Pair with Vault

For authenticated workflows, pair Browser Context Profiles with Vault so stale sessions can be repaired:

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Check the dashboard and summarize anything urgent",
  "use_profile": true,
  "use_vault": true
}
```

The Browser Context Profile starts the run with saved logged-in state. If the session expires and a matching
Vault credential is available, TinyFish can use the credential to sign in again and repair the saved
state for future runs.

## List profiles

```bash theme={null}
curl https://agent.tinyfish.ai/v1/profiles \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## Inspect and update

```bash theme={null}
# Inspect saved domains
curl https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY"

# Rename, make default, or update proxy location
curl -X PATCH https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Salesforce", "set_as_default": true, "proxy_country_code": "US" }'

# Delete one stored domain
curl -X DELETE https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/domains/example.com \
  -H "X-API-Key: $TINYFISH_API_KEY"

# Delete the profile
curl -X DELETE https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890 \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## Upload cookies manually

Use manual upload when you already have exported browser state and do not need to open a setup
browser.

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/upload \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cookies": [
      { "name": "session", "value": "...", "domain": "example.com" }
    ]
  }'
```

Manual upload supports cookies plus local and session storage.

| Limit | Value |
| - | - |
| Upload payload | 5 MB |
| Cookies per upload | 3,000 |
| Domains per profile | 100 |

## Common errors

| Status | Meaning | Fix |
| - | - | - |
| `400` | Invalid body, missing default profile, or `profile_id` without `use_profile: true` | Fix the request or create a default profile |
| `401` | Missing or invalid API key | Set `X-API-Key` |
| `404` | Profile or saved domain not found | Check the profile ID or domain |
| `409` | Setup/save/delete cleanup needs a retry, or the setup browser is no longer running | Retry the operation or start a new setup session |

## Profile endpoints

All requests require `X-API-Key`.

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/profiles` | `GET` | List profiles |
| `/v1/profiles` | `POST` | Create a profile |
| `/v1/profiles/{profileId}` | `GET` | Get profile details and saved domains |
| `/v1/profiles/{profileId}` | `PATCH` | Rename a profile, set default, or update proxy location |
| `/v1/profiles/{profileId}` | `DELETE` | Delete a profile |
| `/v1/profiles/{profileId}/setup-session` | `POST` | Start an interactive setup browser |
| `/v1/profiles/{profileId}/setup-session/cancel` | `POST` | Cancel a setup browser session without saving |
| `/v1/profiles/{profileId}/save` | `POST` | Save a setup browser session |
| `/v1/profiles/{profileId}/upload` | `POST` | Upload cookies and storage manually |
| `/v1/profiles/{profileId}/domains/{domain}` | `DELETE` | Delete stored state for one domain |

## Next steps

<CardGroup>
  <Card title="Browser Context Profiles overview" icon="window" href="/key-concepts/browser-context-profiles">
    Learn when to use Browser Context Profile state
  </Card>

  <Card title="Vault Credentials" icon="vault" href="/key-concepts/credentials">
    Add stale-session repair
  </Card>
</CardGroup>


# Agent API
Source: https://docs.tinyfish.ai/agent-api/index

Use natural-language goals to automate workflows on real websites

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.

<Note>
  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](/browser-api).
</Note>

## Canonical Endpoints

| Endpoint | Pattern | Best for |
| - | - | - |
| `/run` | Synchronous | Quick tasks and simple integrations |
| `/run-async` | Start then poll | Long tasks and batch processing |
| `/run-sse` | Live event stream | Real-time progress in user-facing apps |

```bash theme={null}
POST https://agent.tinyfish.ai/v1/automation/run-sse
```

## Before You Start

<Steps>
  <Step title="Get your API key">
    Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
  </Step>

  <Step title="Store it in your environment">
    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for the full setup and troubleshooting guide.

## Your First Request

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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 JSON.",
  });

  for await (const event of stream) {
    console.log(event);
  }
  ```

  ```bash cURL theme={null}
  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."
    }'
  ```
</CodeGroup>

## What Success Looks Like

```json theme={null}
{"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"}]}}
```

The agent's answer comes back in `result`: a JSON object appears directly (as above), while a bare list or plain-text answer arrives under `result.result`. Pass an [`output_schema`](/key-concepts/structured-output) for guaranteed typed fields.

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

## Read Next

<CardGroup>
  <Card title="Agent reference" icon="code" href="/agent-api/reference">
    Full request schema, run lifecycle, browser profiles, and errors
  </Card>

  <Card title="Structured Output" icon="code" href="/key-concepts/structured-output">
    Schema support, limits, and examples
  </Card>

  <Card title="Endpoint selection" icon="plug" href="/key-concepts/endpoints">
    Choose between `/run`, `/run-async`, and `/run-sse`
  </Card>

  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Understand status, polling, and completion
  </Card>

  <Card title="Goal prompting guide" icon="bullseye" href="/prompting-guide">
    Write more reliable automation instructions
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>
</CardGroup>


# Agent API Reference
Source: https://docs.tinyfish.ai/agent-api/reference

Technical reference for goal-based TinyFish automation

## Endpoints

| Endpoint | Method | Returns | Cancel support |
| - | - | - | - |
| `https://agent.tinyfish.ai/v1/automation/run` | `POST` | Final run result | No |
| `https://agent.tinyfish.ai/v1/automation/run-async` | `POST` | `run_id` immediately | Yes |
| `https://agent.tinyfish.ai/v1/automation/run-sse` | `POST` | SSE event stream | Yes |

All requests require the `X-API-Key` header. See [Authentication](/authentication).

## Common Request Body

All three automation endpoints accept the same JSON body.

```json theme={null}
{
  "url": "https://example.com",
  "goal": "Find the pricing page and extract all plan details",
  "output_schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "price": { "type": "number" }
    },
    "required": ["title", "price"]
  },
  "browser_profile": "lite",
  "proxy_config": {
    "enabled": true,
    "type": "tinyfish",
    "country_code": "US"
  },
  "agent_config": {
    "mode": "strict",
    "max_steps": 50,
    "max_duration_seconds": 300
  },
  "webhook_url": "https://example.com/webhooks/tinyfish",
  "use_profile": true,
  "profile_id": "prof_abc123def4567890",
  "use_vault": true,
  "credential_item_ids": ["cred:a1b2c3d4:Work:item-xyz"]
}
```

| Field | Type | Required | Notes |
| - | - | - | - |
| `url` | `string` | Yes | Target website URL to automate |
| `goal` | `string` | Yes | Natural-language instruction for the automation |
| `output_schema` | `object` | No | Structured-output schema subset for the run result. Unsupported fields are rejected before execution. See [Structured Output](/key-concepts/structured-output) |
| `browser_profile` | `lite \| stealth` | No | Defaults to `lite` |
| `proxy_config.enabled` | `boolean` | No | Enables proxying for the run |
| `proxy_config.type` | `tinyfish \| custom` | No | `tinyfish` (default) uses the built-in TinyFish proxy; `custom` requires your own proxy URL |
| `proxy_config.country_code` | `US \| GB \| CA \| DE \| FR \| JP \| AU` | No | Used with `type: "tinyfish"`. Defaults to `US` |
| `proxy_config.url` | `string` | No | Required when `type: "custom"` |
| `proxy_config.username` | `string` | No | Custom proxy username |
| `proxy_config.password` | `string` | No | Custom proxy password |
| `agent_config.mode` | `default \| strict` | No | Beta-gated. Use `strict` for fail-fast automation where the agent should stop instead of exploring workarounds |
| `agent_config.max_steps` | `integer` | No | Beta-gated. Optional run step limit from 1 to 500. Omit the field to use EVA's default of 150 |
| `agent_config.max_duration_seconds` | `integer` | No | Maximum wall-clock seconds before the agent stops. Defaults to no limit |
| `webhook_url` | `string` | No | HTTPS URL to receive run lifecycle notifications. Must use `https://`. See [Webhooks](/webhooks) |
| `capture_config` | `object` | No | Opt into extra run artifacts (`screenshots`, `recording`, `html`, `snapshots`, `elements`). Account-gated — returns `403` if your account is not enabled for a requested capability |
| `use_profile` | `boolean` | No | Use the default saved [Browser Context Profile](/key-concepts/browser-context-profiles) for this run |
| `profile_id` | `string` | No | Select a specific Browser Context Profile. Requires `use_profile: true` |
| `use_vault` | `boolean` | No | Enable [vault credentials](/key-concepts/credentials) for this run. When `true`, TinyFish can log into sites using your connected password manager |
| `credential_item_ids` | `string[]` | No | Scope the run to specific credential URIs from `GET /v1/vault/items`. Requires `use_vault: true`. If omitted, all synced items are available |

<Info>
  **Beta:** `agent_config.mode: "strict"` is in beta — you must join the beta to use it (contact support to
  enable it for your account). Strict mode is best for
  precise tests and automations where unexpected page state should stop the run quickly instead of
  trying alternate paths.
</Info>

<Info>
  **Beta:** `agent_config.max_steps` is available only to beta-enabled users. Use it when a run
  needs a shorter or longer step budget than EVA's default. Non-beta API requests that include
  `max_steps` return `403 FORBIDDEN`; requests without the field are unaffected.
</Info>

<Note>
  Use `use_profile: true` for your default Browser Context Profile. Add `profile_id` when the run must use a
  specific saved profile. Create and set up profiles from the dashboard or the
  [Browser Context Profiles API](/agent-api/browser-context-profiles).
</Note>

See [Structured Output](/key-concepts/structured-output) for the supported keyword allowlist, size and depth limits, and common rewrites for invalid schemas.

See [Browser Context Profiles](/key-concepts/browser-context-profiles), [Browser Context Profiles API](/agent-api/browser-context-profiles), [Browser Profiles](/key-concepts/browser-profiles), [Proxies](/key-concepts/proxies), and [Vault Credentials](/key-concepts/credentials) for operational guidance.

## `POST /v1/automation/run`

Use this endpoint when you want the final result in one blocking response.

```json theme={null}
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "started_at": "2024-01-01T00:00:00Z",
  "finished_at": "2024-01-01T00:00:30Z",
  "num_of_steps": 5,
  "result": {
    "product": "iPhone 15",
    "price": "$799"
  },
  "error": null
}
```

| Field | Type | Notes |
| - | - | - |
| `run_id` | `string \| null` | Unique identifier for the run |
| `status` | `COMPLETED \| FAILED` | Final run state |
| `started_at` | `string \| null` | ISO 8601 timestamp |
| `finished_at` | `string \| null` | ISO 8601 timestamp |
| `num_of_steps` | `number \| null` | Number of steps taken |
| `result` | `object \| null` | Extracted JSON result |
| `error` | `object \| null` | Present only when the run failed |

Runs created via `/run` cannot be cancelled.

## `POST /v1/automation/run-async`

Use this endpoint when you want a `run_id` immediately and will fetch the full run later.

```json theme={null}
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "error": null
}
```

| Field | Type | Notes |
| - | - | - |
| `run_id` | `string \| null` | Created run ID |
| `error` | `object \| null` | Present only when run creation failed |

Fetch the full run state later with `GET /v1/runs/{id}`.

## `POST /v1/automation/run-sse`

Use this endpoint when you want a streaming event feed while the automation runs.

Possible SSE event types:

| Event type | Fields |
| - | - |
| `STARTED` | `type`, `run_id`, `timestamp` |
| `STREAMING_URL` | `type`, `run_id`, `streaming_url`, `timestamp` |
| `PROGRESS` | `type`, `run_id`, `purpose`, `timestamp` |
| `HEARTBEAT` | `type`, `timestamp` |
| `COMPLETE` | `type`, `run_id`, `status`, `result?`, `error?`, `timestamp` (on failure, `error` carries `help_url` / `help_message`) |

Example stream:

```text theme={null}
data: {"type":"STARTED","run_id":"run_123","timestamp":"2025-01-01T00:00:00Z"}

data: {"type":"STREAMING_URL","run_id":"run_123","streaming_url":"https://...","timestamp":"..."}

data: {"type":"PROGRESS","run_id":"run_123","purpose":"Clicking submit button","timestamp":"..."}

data: {"type":"COMPLETE","run_id":"run_123","status":"COMPLETED","result":{...},"timestamp":"..."}
```

<Note>
  **Reconnection:** SSE streams do not support `Last-Event-ID` reconnection. If your client disconnects mid-stream, recover by polling `GET /v1/runs/{run_id}` until the run reaches a terminal status (`COMPLETED`, `FAILED`, or `CANCELLED`).
</Note>

### Raw HTTP (no SDK)

Parse SSE events directly without the TinyFish SDK:

```python theme={null}
import os
import httpx
import json

url = "https://agent.tinyfish.ai/v1/automation/run-sse"
headers = {"X-API-Key": os.environ["TINYFISH_API_KEY"]}
payload = {"url": "https://example.com", "goal": "Extract the page title"}

with httpx.stream("POST", url, headers=headers, json=payload, timeout=120) as response:
    for line in response.iter_lines():
        if line.startswith("data: "):
            event = json.loads(line[6:])
            print(f"Event: {event['type']}")
            if event["type"] == "COMPLETE":
                print(f"Result: {event.get('result', {})}")
```

## `GET /v1/runs/{id}`

Use this endpoint to retrieve the current or final state of an async or streaming run.

| Field | Type | Notes |
| - | - | - |
| `run_id` | `string` | Unique run identifier |
| `status` | `PENDING \| RUNNING \| COMPLETED \| FAILED \| CANCELLED` | Current run state |
| `goal` | `string` | Original goal text |
| `created_at` | `string` | ISO 8601 timestamp |
| `started_at` | `string \| null` | ISO 8601 timestamp |
| `finished_at` | `string \| null` | ISO 8601 timestamp |
| `num_of_steps` | `integer \| null` | Number of steps taken |
| `result` | `object \| null` | Extracted JSON result |
| `error` | `object \| null` | Error details if failed |
| `profile_attached` | `boolean` | Whether a Browser Context Profile was attached to the run |
| `profile_id` | `string \| null` | ID of the attached Browser Context Profile, if any |
| `streaming_url` | `string \| null` | Live browser stream URL while running |
| `browser_config` | `object \| null` | Proxy settings used for the run |
| `video_url` | `string \| null` | Presigned run recording URL, if available |
| `output_schema` | `object \| null` | Structured-output schema originally requested for the run |
| `steps` | `array` | Recorded step events for the run |

`error` may include:

| Field | Type | Notes |
| - | - | - |
| `code` | `string` | Machine-readable error code |
| `message` | `string` | Human-readable failure description |
| `category` | `SYSTEM_FAILURE \| AGENT_FAILURE \| BILLING_FAILURE \| UNKNOWN` | Error class |
| `retry_after` | `number \| null` | Suggested retry delay in seconds |
| `help_url` | `string` | Troubleshooting link |
| `help_message` | `string` | Human-readable guidance |

## `POST /v1/runs/{id}/cancel`

Only runs created via `/run-async` or `/run-sse` can be cancelled.

```json theme={null}
{
  "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "CANCELLED",
  "cancelled_at": "2026-01-14T10:30:55Z",
  "message": null
}
```

| Field | Type | Notes |
| - | - | - |
| `run_id` | `string` | Run identifier |
| `status` | `CANCELLED \| COMPLETED \| FAILED` | Actual status after the cancel attempt |
| `cancelled_at` | `string \| null` | ISO 8601 timestamp |
| `message` | `string \| null` | Idempotency or terminal-state message |

## Error Codes

Common HTTP-level errors across automation endpoints:

| Status | Code | Meaning |
| - | - | - |
| `400` | `INVALID_INPUT` | Invalid request body or missing required fields |
| `401` | `MISSING_API_KEY`, `INVALID_API_KEY` | Missing or invalid API key |
| `401` | `VAULT_RECONNECT_REQUIRED` | Reconnect the affected vault provider, then retry; see [error recovery](/error-codes) |
| `403` | `FORBIDDEN` | Access denied |
| `429` | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded |
| `500` | `INTERNAL_ERROR` | Internal server error |

The `COMPLETE` SSE event or `GET /v1/runs/{id}` may also include run-level failures such as `TASK_FAILED`, `SITE_BLOCKED`, `MAX_STEPS_EXCEEDED`, `TIMEOUT`, or `BILLING_REJECTED`.

## Related

<CardGroup>
  <Card title="Agent overview" icon="sparkles" href="/agent-api">
    First request, endpoint selection, and goal-writing basics
  </Card>

  <Card title="Structured Output" icon="code" href="/key-concepts/structured-output">
    Schema support, limits, and common rewrites
  </Card>

  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Statuses, polling, and lifecycle behavior
  </Card>

  <Card title="Goal prompting guide" icon="bullseye" href="/prompting-guide">
    Improve automation reliability
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>

  <Card title="Vault Credentials" icon="lock" href="/key-concepts/credentials">
    Use password manager credentials in runs
  </Card>

  <Card title="Browser Context Profiles" icon="window" href="/key-concepts/browser-context-profiles">
    Reuse saved logged-in browser state
  </Card>
</CardGroup>


# Agent Payments
Source: https://docs.tinyfish.ai/agent-payments

Let your agent top up its own TinyFish wallet with the Machine Payments Protocol (MPP)

When your agent runs low on credit, it can add money to your TinyFish wallet itself and keep working. It pays with the wallet it already has, over the [Machine Payments Protocol (MPP)](https://mpp.dev/overview), the open standard Stripe and Tempo created for agents paying over HTTP. No dashboard needed. Whether you approve each payment is up to your wallet: some, like Stripe's Link agent wallet, ask you to approve each one.

<Note>
  Agent payments are rolling out gradually, and need an account on wallet billing. If `POST /v1/wallet/top-up` answers `404` with `FEATURE_NOT_AVAILABLE`, they aren't available for your account yet.
</Note>

## How It Works

1. Your agent asks TinyFish to top up, say \$10.
2. TinyFish answers with an HTTP `402` payment challenge: the amount, the currency, and who to pay.
3. Your agent's wallet issues a one-time [Shared Payment Token (SPT)](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens) for that amount. Your card details never reach the agent or TinyFish.
4. Your agent retries with the payment, Stripe charges it, and your wallet is credited in seconds, with a receipt.

Any wallet that speaks MPP with the `stripe` payment method works, including Stripe's [Link agent wallet](https://docs.stripe.com/agentic-commerce/link-agent-wallet).

| Detail | Value |
| - | - |
| Amount per top-up | $10.00 to $500.00, in whole cents |
| Currency | USD |
| Payment method | Card, through a Stripe Shared Payment Token |
| Where | REST API and the TinyFish MCP server |

***

## REST API

Top-ups use your normal API key in the `X-API-Key` header. The payment travels in a separate `Payment-Authorization` header.

<Tip>
  `GET /v1/wallet` includes `agent_top_up_url` when agent payments are available for your account, so an agent checking its balance can find the endpoint. A request refused with `402 INSUFFICIENT_CREDITS` carries the same field in `error.details` when a top-up would unblock it (not when the card on file needs fixing), so an agent that runs out mid-task knows where to top up.
</Tip>

<Steps>
  <Step title="Ask for a top-up">
    ```bash theme={null}
    curl -i -X POST https://agent.tinyfish.ai/v1/wallet/top-up \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"amount": "10.00"}'
    ```

    The response is `402 Payment Required` with the challenge in the `WWW-Authenticate` header:

    ```
    WWW-Authenticate: Payment id="…", realm="agent.tinyfish.ai", method="stripe", intent="charge", request="…", expires="…", header="Payment-Authorization"
    ```
  </Step>

  <Step title="Pay the challenge">
    Hand the challenge to your MPP wallet. Once the payment is approved (some wallets, like Link, ask you first), it returns a payment credential (`Payment <base64url>`). The challenge expires after 30 minutes, which leaves time for that approval.
  </Step>

  <Step title="Retry with the payment">
    Send the same request again, with the same amount, plus the credential:

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/wallet/top-up \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Payment-Authorization: Payment eyJjaGFsbGVuZ2Ui…" \
      -H "Content-Type: application/json" \
      -d '{"amount": "10.00"}'
    ```
  </Step>
</Steps>

MPP clients that handle `402` responses, such as Stripe's Link agent wallet, run steps 2 and 3 for you.

### Responses

| Status | Meaning | What your agent should do |
| - | - | - |
| `200` | Paid and credited. `available_balance` is your new balance (or `null` if it couldn't be read). | Carry on. |
| `202` | Paid, and the credit lands within minutes. | Don't pay again. Check the balance shortly. |
| `402` with `WWW-Authenticate` | No payment was sent. This is the challenge. | Pay it and retry. |
| `402` without `WWW-Authenticate` | A payment was sent but not accepted. `detail` says why. | Don't pay again on your own (see below). |
| `400` | The amount is invalid or outside $10 to $500. | Fix the amount. |
| `404` | Agent payments aren't available for your account. | Top up from the [dashboard](https://agent.tinyfish.ai) instead. |

A successful top-up looks like this:

```json theme={null}
{
  "status": "settled",
  "amount": "10.00",
  "currency": "USD",
  "payment_reference": "pi_3QxYz2Ab",
  "available_balance": "16.44"
}
```

The response also carries an MPP `Payment-Receipt` header.

***

## MCP

If your agent connects to the TinyFish MCP server at `https://agent.tinyfish.ai/mcp` (see [MCP Integration](/mcp-integration)), it gets a `top_up_wallet` tool. It needs no API key: it tops up the wallet of the account you signed in with.

The tool takes two calls:

1. Call `top_up_wallet` with an `amount`, like `"10.00"`. It returns `payment_required` and the challenge.
2. Pay the challenge, then call `top_up_wallet` again with the same amount and either:
   * `payment_credential`: the credential from your MPP wallet, or
   * `spt` plus `challenge`: a Stripe Shared Payment Token issued for the challenge, and the challenge itself.

MCP clients that support MPP's payment binding pay the challenge automatically from the tool result.

The result's `status` is `settled`, `pending` (paid, credit landing, don't pay again), or `unconfirmed` (don't pay again on your own).

When a run is refused for insufficient balance and the tool is available to you, the refusal names `top_up_wallet` as an alternative to the dashboard link, unless the card on file needs fixing first. Your wallet asks you to approve the payment, the same as any other MPP charge.

<Info>
  `top_up_wallet` is available on the main MCP server and the Claude connector. The ChatGPT app doesn't include it.
</Info>

***

## Never Paying Twice

TinyFish is built so one top-up is charged once:

* **A replayed payment is never charged again.** Sending the same credential twice credits the wallet once.
* **A failed paid retry never gets a new challenge.** Some failures can happen after a charge, for example a timeout while Stripe is processing. So TinyFish answers `402` without a challenge, and an MPP wallet has nothing to pay automatically.
* **A charge that went through is credited automatically,** even if something fails right after it.

If your agent gets a `402` without a challenge, a `202`, or a request that errors or times out after it sent a payment, it shouldn't start a new top-up on its own. If the balance hasn't increased after 10 minutes, it should ask you first.

<Warning>
  A declined card also comes back as a `402` without a challenge, and charges nothing. To try again, start a new top-up with a different payment method.
</Warning>

***

## Refunds

For a refund of an agent top-up, contact support with the `payment_reference` from the response.

## Learn More

* [Machine Payments Protocol](https://mpp.dev/overview)
* [Stripe machine payments](https://docs.stripe.com/payments/machine)
* [Link agent wallet](https://docs.stripe.com/agentic-commerce/link-agent-wallet)


# Anti-Bot Guide
Source: https://docs.tinyfish.ai/anti-bot-guide

Diagnose and bypass bot detection when automating protected websites

You've sent a run, it came back `COMPLETED`, but the result is empty or wrong. Or maybe it outright `FAILED`. Before you start rewriting your goal, check whether the site is blocking you — bot detection is the most common cause of silent failures, and the fix is usually two lines of code.

This guide walks through the full process: confirm the problem, apply the right configuration, and tune your goal to behave more like a human.

<Note>
  Examples use the Python SDK. The same parameters work across all SDKs and the REST API — see [API Reference](/api-reference) for TypeScript and cURL equivalents.
</Note>

## Installation

```bash theme={null}
pip install -U tinyfish
```

Set your API key as an environment variable so you don't have to pass it explicitly:

```bash theme={null}
export TINYFISH_API_KEY="your-api-key"
```

***

## Step 1: Confirm Anti-Bot Is the Problem

Don't assume. Sites can fail for lots of reasons — slow JavaScript, unexpected layout changes, ambiguous goals. Anti-bot has specific fingerprints. Look for them first.

### Get the streaming URL and watch the browser

Every run produces a `streaming_url` — a live browser preview you can open while the run is happening. This is the fastest way to see exactly what the agent encountered.

Use `agent.stream()` to capture it as soon as it's available:

```python theme={null}
from tinyfish import TinyFish, CompleteEvent

client = TinyFish()

with client.agent.stream(
    goal="Extract the product name and price",
    url="https://example.com/products",
    on_streaming_url=lambda e: print(f"Watch live: {e.streaming_url}"),
    on_progress=lambda e: print(f"  > {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            print("Status:", event.status)
            print("Result:", event.result_json)
```

The `on_progress` callback shows each step the agent took — if it got stuck on a challenge page, you'll see it stop there.

If you already started a run with `agent.queue()`, retrieve the streaming URL from the run object:

```python theme={null}
run = client.runs.get("run_abc123")
print(run.streaming_url)   # open this in your browser
```

### What to look for in the browser preview

Open `streaming_url` in your browser. What you see tells you what happened:

| What you see | Likely cause |
| - | - |
| Cloudflare challenge / "Checking your browser" | Cloudflare bot detection |
| DataDome popup or redirect | DataDome protection |
| Blank page or infinite spinner | IP-based block or JS fingerprinting |
| CAPTCHA (reCAPTCHA, hCaptcha) | CAPTCHA gate — cannot be solved automatically |
| "Access Denied" or 403 page | IP or User-Agent block |
| Login page when you expected content | Session-based bot detection |

### Check the result — `COMPLETED` doesn't mean it worked

The `result` field is a better indicator of agentic success.

```python theme={null}
from tinyfish import TinyFish, RunStatus, CompleteEvent

client = TinyFish()

with client.agent.stream(
    goal="Extract the product name and price",
    url="https://example.com/products",
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            if event.status == RunStatus.COMPLETED and event.result_json:
                # Anti-bot shows up here as null fields or explicit failure flags
                result = event.result_json
                if result.get("status") == "failure" or not any(result.values()):
                    print("Blocked — result is empty despite COMPLETED status")
            elif event.status == RunStatus.FAILED:
                print("Run failed:", event.error.message if event.error else "unknown")
```

**Anti-bot signatures in the result:**

* Fields are all `null` or empty arrays AND the streaming view shows the target content was never loaded
* `result.reason` mentions "access denied", "blocked", or "could not find"

If the streaming view shows a challenge page and the result is empty or a failure — you've confirmed anti-bot. Move to Step 2.

***

## Step 2: Enable Stealth Mode and Proxy

Apply both together. Stealth changes the browser fingerprint; the proxy changes the IP. Sites that use anti-bot services correlate both signals — changing only one often isn't enough.

### Switch to stealth browser

```python theme={null}
from tinyfish import TinyFish, BrowserProfile

client = TinyFish()

response = client.agent.run(
    goal="Extract the product name and price",
    url="https://protected-site.com/products",
    browser_profile=BrowserProfile.STEALTH,   # was BrowserProfile.LITE or omitted
)
```

`BrowserProfile.STEALTH` is a modified browser with anti-detection techniques. The default (`BrowserProfile.LITE`) is faster but doesn't include these measures.

### Add a proxy

```python theme={null}
from tinyfish import TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode

client = TinyFish()

response = client.agent.run(
    goal="Extract the product name and price",
    url="https://protected-site.com/products",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(
        enabled=True,
        country_code=ProxyCountryCode.US,   # match the site's expected audience
    ),
)
```

**Choosing a country:** Pick the country where the site's primary users are. `country_code` accepts any ISO 3166-1 alpha-2 code (e.g. `"IN"`); the enum covers common ones:

| Enum | Country |
| - | - |
| `ProxyCountryCode.US` | United States |
| `ProxyCountryCode.GB` | United Kingdom |
| `ProxyCountryCode.CA` | Canada |
| `ProxyCountryCode.DE` | Germany |
| `ProxyCountryCode.FR` | France |
| `ProxyCountryCode.JP` | Japan |
| `ProxyCountryCode.AU` | Australia |

### Verify what proxy was actually used

After a run, `browser_config` on the run object confirms what was applied:

```python theme={null}
run = client.runs.get("run_abc123")
print(run.browser_config.proxy_enabled)        # True/False
print(run.browser_config.proxy_country_code)   # "US" or None
```

### Full example with both applied

```python theme={null}
from tinyfish import TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode, CompleteEvent, RunStatus

client = TinyFish()

with client.agent.stream(
    goal="Extract the product name and price",
    url="https://protected-site.com/products",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
    on_streaming_url=lambda e: print(f"Watch: {e.streaming_url}"),
    on_progress=lambda e: print(f"  > {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            if event.status == RunStatus.COMPLETED:
                print("Result:", event.result_json)
            else:
                print("Failed:", event.error.message if event.error else "unknown")
```

Watch the streaming view again after this change. If the actual page loads instead of a challenge screen — you're through. Move to Step 3 to make the run more reliable at scale.

<Warning>
  TinyFish cannot solve CAPTCHAs (reCAPTCHA, hCaptcha, etc.). The configurations above — stealth mode, proxies, and human-like goal patterns — reduce the likelihood of CAPTCHAs being triggered, but if a site serves one, it's a hard limit for now. We're actively working on expanding our anti-detection capabilities.
</Warning>

***

## Step 3: Guide the Agent to Behave More Like a Human

Stealth and proxy get you past the door. But some sites layer behavioral analysis on top of fingerprinting — they watch for robotic patterns like instant form submissions, missing cookie consent dismissals, or zero mouse dwell time. Your goal controls a lot of this behavior.

### Handle cookie and consent banners

Bot detection systems often look at whether a user interacted with a consent banner before the main content. Always dismiss it explicitly:

```python theme={null}
goal = """
Close any cookie consent or GDPR banner that appears before doing anything else.
Then extract the product name, current price, and availability status.
Return as JSON: { "name": string, "price": number, "available": boolean }
"""
```

### Add deliberate pauses at suspicious checkpoints

Sites with aggressive behavioral detection (checkout pages, login flows) flag runs that move too fast:

```python theme={null}
goal = """
1. Wait for the page to fully load before interacting with anything.
2. Close any cookie banner.
3. Wait for the banner to disappear before proceeding.
4. Scroll down to view the pricing section.
5. Wait for the pricing section to fully render, then extract all plan names and monthly prices.

Return as JSON array: [{ "plan": string, "price_monthly": number }]
"""
```

### Describe elements visually, not by selector

Automation-aware selectors are sometimes deliberately changed to trip scrapers. Visual descriptions are more resilient:

```python theme={null}
# Fragile — may be intentionally changed by the site
goal = "Click the button with id='add-to-cart-btn'"

# Resilient — describes what a human would see
goal = "Click the blue 'Add to Cart' button directly below the product price"
```

### Use numbered steps for multi-step flows

For login flows or multi-page workflows, numbered steps give the agent explicit decision points rather than leaving it to guess:

```python theme={null}
goal = """
1. Wait for the page to fully load (spinner should disappear).
2. If a cookie consent banner is visible, click 'Accept' or 'Accept All'.
3. Locate the search bar at the top of the page and type "running shoes".
4. Wait for autocomplete suggestions to appear, then press Enter.
5. Wait for results to load.
6. Extract the first 10 results: product name, price, and product URL.

Stop after 10 results. Do not paginate.
Return as JSON array.
"""
```

### Add explicit fallback instructions

Protected sites sometimes show intermediate pages (challenge passed, now redirecting). Tell the agent how to handle them:

```python theme={null}
goal = """
Extract the product price from this page.

If a loading screen or redirect page appears, wait for it to complete before extracting.
If an 'Access Denied' page appears, return { "error": "access_denied" }.
If the price shows 'Contact Us', return { "price": null, "contact_required": true }.

Return: { "price": number or null, "currency": string }
"""
```

***

## Putting It All Together

A complete hardened run for a protected site:

```python theme={null}
from tinyfish import (
    TinyFish,
    BrowserProfile,
    ProxyConfig,
    ProxyCountryCode,
    CompleteEvent,
    RunStatus,
)

client = TinyFish()

with client.agent.stream(
    url="https://protected-site.com/pricing",
    browser_profile=BrowserProfile.STEALTH,
    proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
    goal="""
        1. Wait for the page to fully load.
        2. Close any cookie consent or GDPR banner that appears.
        3. Wait 1 second before proceeding.
        4. Locate the pricing section — it typically shows plan names in a grid or table.
        5. For each plan, extract: plan name, monthly price, and annual price if shown.

        If a Cloudflare or security check page appears, wait for it to complete automatically.
        If you see an 'Access Denied' or CAPTCHA page, return { "error": "blocked" }.
        Do not click any purchase or checkout buttons.

        Return as JSON array:
        [{ "plan": "Pro", "monthly_price": 49, "annual_price": 39 }]
    """,
    on_streaming_url=lambda e: print(f"Watch run: {e.streaming_url}"),
    on_progress=lambda e: print(f"  > {e.purpose}"),
) as stream:
    for event in stream:
        if isinstance(event, CompleteEvent):
            if event.status == RunStatus.COMPLETED:
                print("Result:", event.result_json)
            else:
                print("Failed:", event.error.message if event.error else "unknown")
```

***

## Decision Tree

```
Run returned empty or wrong result?
│
├── Open streaming_url (from on_streaming_url callback or runs.get())
│   ├── Challenge / "Checking your browser" page → Anti-bot confirmed
│   ├── Access Denied / 403 → Anti-bot confirmed
│   ├── Blank page → Likely anti-bot (fingerprint-based)
│   └── Page loaded but result wrong → Goal issue, not anti-bot
│
└── Anti-bot confirmed?
    ├── Add browser_profile=BrowserProfile.STEALTH
    ├── Add proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US)
    ├── Re-run and watch stream again
    │   ├── Page loads → Add goal hardening (Step 3) for reliability at scale
    │   └── Still blocked → Site likely requires CAPTCHA (hard limit)
    └── Done
```

***

## Creative Solutions and Iteration

When a site is actively defended, the most effective approach is often to rethink the workflow rather than force the original one.

**Watch yourself do it first.** Before writing your goal, navigate to the target site yourself and think through what a human would actually do. Use that as your script. The streaming view is also useful here — watch a run or two to understand exactly what the agent encounters before committing to a final goal.

**Start at the front door.** Linking directly to a filtered search results page or a deep URL can look robotic. Starting at `target.com` and navigating to your destination — searching for a product, clicking through a category — often succeeds where a direct deep link fails.

**Go to the source.** If the formatted data you need lives behind anti-bot and paywalls, ask whether the underlying raw data is available elsewhere. Aggregator sites are often heavily protected; their primary sources may not be. Synthesizing from multiple simpler sources is frequently more reliable than fighting for one complex one.

**Check for a public API or feed first.** Some sites that actively block scraping also publish APIs, RSS feeds, or sitemaps. Five minutes checking saves a lot of iteration.

**Keep dwell time low.** The longer an agent stays on a site, the higher the likelihood of detection. Balancing human-like navigation with speed matters — break large workflows into focused, smaller tasks that can be handled by multiple agents running in parallel. You get both the human-like pacing and the throughput. Scale is one of TinyFish's superpowers.

**Time your runs intentionally.** Anti-bot systems are sensitive to traffic volume. Running during off-peak hours for your target site (for US-based sites, late morning to early afternoon PST often works well) can reduce the likelihood of triggering rate-based challenges. If you're testing a new workflow, start with a single run during a quiet period before scaling up.

**Vary your entry points at scale.** If you're running hundreds of batch jobs against the same site, uniform traffic patterns can themselves become a fingerprint — even across different IPs. Mixing up how runs navigate to their destination (some via homepage search, some via category pages, some direct) makes the aggregate traffic look more organic. Runs have a 10-minute timeout, so this also naturally encourages breaking complex workflows into smaller, parallelizable pieces. Design goals to complete their core task well within that limit.

**Manage concurrency intentionally.** TinyFish does not throttle runs by domain — if you enqueue a large batch against the same site, they will fire in parallel up to your account's concurrency limit. For sensitive sites, consider staggering your jobs in your own queuing logic rather than enqueuing everything at once.

***

## Authenticated Sessions

Logging in is one of the most effective anti-bot techniques. Logged-in users are treated very differently by most protection systems, so an authenticated session often sails past challenges that block anonymous traffic — and it unlocks gated content at the same time.

[Connect your password manager](/vault-setup), then set `use_vault: true` on a run and TinyFish signs in with the credentials you select. See [Vault Credentials](/key-concepts/credentials) for details.

<Note>
  Vault credentials are supported across the Playground, REST API, Python SDK, TypeScript SDK, and CLI. See [Connect Your Vault](/vault-setup) to get started.
</Note>

***

## What's Coming

TinyFish continuously improves browser behavior and anti-detection performance across the web. If a site blocked you on a previous project, it's worth trying again — the same run that failed before may work without any changes on your end. We're also actively expanding our anti-detection capabilities.

***

## Need Help?

If you're stuck on a specific site, share the URL and your current configuration with us — we can often diagnose the issue quickly.

* **Email:** [support@tinyfish.io](mailto:support@tinyfish.io)
* **Discord:** [discord.gg/tinyfish](https://discord.gg/tinyfish)


# Attach to research progress
Source: https://docs.tinyfish.ai/api-reference/attach-to-research-progress

https://agent.tinyfish.ai/v1/openapi/research get /v1/research-run/{research_run_id}/events
Reconnect with Last-Event-ID. Disconnecting does not cancel research. Retained events expire; poll the run for durable results.



# Run browser automation synchronously
Source: https://docs.tinyfish.ai/api-reference/automation/run-browser-automation-synchronously

https://agent.tinyfish.ai/v1/openapi/main post /v1/automation/run
Execute a browser automation task synchronously and wait for completion. Returns the final result once the automation finishes (success or failure). Use this endpoint when you need the complete result in a single response. Note: Runs created via this endpoint cannot be cancelled. If you need cancellation support, use `/v1/automation/run-async` or `/v1/automation/run-sse` instead.



# Run browser automation with SSE streaming
Source: https://docs.tinyfish.ai/api-reference/automation/run-browser-automation-with-sse-streaming

https://agent.tinyfish.ai/v1/openapi/main post /v1/automation/run-sse
Execute a browser automation task with Server-Sent Events (SSE) streaming. Returns a real-time event stream with automation progress, browser streaming URL, and final results.



# Start automation asynchronously
Source: https://docs.tinyfish.ai/api-reference/automation/start-automation-asynchronously

https://agent.tinyfish.ai/v1/openapi/main post /v1/automation/run-async
Creates and enqueues an automation run, returning the run_id immediately without waiting for completion. Use this for long-running automations where you want to poll for results separately.



# Start multiple automations asynchronously
Source: https://docs.tinyfish.ai/api-reference/automation/start-multiple-automations-asynchronously

https://agent.tinyfish.ai/v1/openapi/main post /v1/automation/run-batch
Creates and enqueues multiple automation runs in a single request, returning run_ids immediately without waiting for completion. Maximum 100 runs per request.

**Atomic creation:** Run creation is all-or-nothing. Either all runs are created successfully, or none are (returns error).

**Idempotency:** This endpoint does not currently support idempotency keys. Retrying a failed request may create duplicate runs.



# Cancel a profile setup session
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/cancel-a-profile-setup-session

https://agent.tinyfish.ai/v1/openapi/main post /v1/profiles/{profileId}/setup-session/cancel
Cancels a running Browser Context Profile setup session and discards unsaved setup state. Requires the session_id returned by setup-session.



# Create a Browser Context Profile
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-browser-context-profile

https://agent.tinyfish.ai/v1/openapi/main post /v1/profiles
Create a Browser Context Profile



# Create a profile setup session
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/create-a-profile-setup-session

https://agent.tinyfish.ai/v1/openapi/main post /v1/profiles/{profileId}/setup-session
Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session is cancelled or times out.



# Delete a Browser Context Profile
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/delete-a-browser-context-profile

https://agent.tinyfish.ai/v1/openapi/main delete /v1/profiles/{profileId}
Delete a Browser Context Profile



# Delete a saved profile domain
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/delete-a-saved-profile-domain

https://agent.tinyfish.ai/v1/openapi/main delete /v1/profiles/{profileId}/domains/{domain}
Delete a saved profile domain



# Get a Browser Context Profile
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/get-a-browser-context-profile

https://agent.tinyfish.ai/v1/openapi/main get /v1/profiles/{profileId}
Get a Browser Context Profile



# List Browser Context Profiles
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/list-browser-context-profiles

https://agent.tinyfish.ai/v1/openapi/main get /v1/profiles
List Browser Context Profiles



# Save a profile setup session
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/save-a-profile-setup-session

https://agent.tinyfish.ai/v1/openapi/main post /v1/profiles/{profileId}/save
Captures cookies, local storage, and session storage from a running setup session into the Browser Context Profile. Requires the session_id returned by setup-session.



# Update a Browser Context Profile
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/update-a-browser-context-profile

https://agent.tinyfish.ai/v1/openapi/main patch /v1/profiles/{profileId}
Update a Browser Context Profile



# Upload Browser Context Profile state
Source: https://docs.tinyfish.ai/api-reference/browser-context-profiles/upload-browser-context-profile-state

https://agent.tinyfish.ai/v1/openapi/main post /v1/profiles/{profileId}/upload
Upload Browser Context Profile state



# Cancel research run by ID
Source: https://docs.tinyfish.ai/api-reference/cancel-research-run-by-id

https://agent.tinyfish.ai/v1/openapi/research post /v1/research-run/{research_run_id}/cancel
Cancel a running research run. Idempotent: an already-terminal run returns 200 with cancelled false and its current status.



# Create a remote browser session
Source: https://docs.tinyfish.ai/api-reference/create-a-remote-browser-session

https://agent.tinyfish.ai/v1/openapi/browser post /
Creates a remote tf-browser session and returns CDP connection details. Connect to the browser via CDP WebSocket at `cdp_url`.

By default the session egresses through the TinyFish residential proxy in the US, pinned to one exit IP for the life of the session. Use `proxy_config` to pick another country (`country_code`, any ISO 3166-1 alpha-2), bring your own proxy (`type: "custom"`), or disable the proxy (`enabled: false`).

Use `timeout_seconds` to set a custom inactivity timeout (5–86400 seconds). If omitted, null, or greater than your plan maximum, the plan maximum is used (15 min on free tier, 60 min on paid).



# Fetch and extract content from URLs
Source: https://docs.tinyfish.ai/api-reference/fetch-and-extract-content-from-urls

https://agent.tinyfish.ai/v1/openapi/fetch post /
Fetches web pages, renders JavaScript-heavy pages when needed, and returns clean extracted content in your preferred format. Submit up to 10 URLs, get back structured content. Per-URL failures appear in `errors[]` and do not fail the entire request.

**Per-URL error codes** (in `errors[].error`):
- `target_http_error` — target server returned a non-2xx HTTP status other than 404/410; the raw status code is in `errors[].status`
- `page_not_found` — target URL returned HTTP 404 or 410; the raw status code is in `errors[].status`
- `target_unreachable` — connection refused, TLS failure, DNS failure, or other network error
- `timeout` — request timed out
- `proxy_error` — proxy tunnel failure
- `bot_blocked` — bot-challenge page detected (Cloudflare, etc.)
- `empty_content` — page loaded but no extractable text was found
- `login_required` — the target redirected to a login or account wall; retrying without credentials will not help
- `content_too_large` — the document exceeds the 20MB size limit for generic documents (PDF and CSV have their own 50MB budgets); not retried in the browser
- `invalid_url` — malformed URL or SSRF-blocked address
- `invalid_redirect_url` — redirect target rejected before fetch
- `conditional_unsupported` — conditional requests (`if_none_match` / `if_modified_since`) are supported on the fast path only; this URL requires browser rendering
- `selector_not_matched` — no elements matching any `include_selectors` entry remained after `exclude_selectors` was applied; the error carries `unmatched_selectors` plus `candidate_selectors` retry hints (a partial miss is not an error — it's reported on the result's `unmatched_selectors`)
- `selector_unsupported` — `include_selectors` / `exclude_selectors` sent for a URL that resolves to a direct PDF/CSV download (no HTML to scope)



# Get research run by ID
Source: https://docs.tinyfish.ai/api-reference/get-research-run-by-id

https://agent.tinyfish.ai/v1/openapi/research get /v1/research-run/{research_run_id}
Retrieve one saved research run, including the plan, evidence, and per-iteration working state.



# List browser session usage
Source: https://docs.tinyfish.ai/api-reference/list-browser-session-usage

https://agent.tinyfish.ai/v1/openapi/browser get /usage
List Tetra browser session usage for the authenticated user. Returns session telemetry including duration, data transfer, mode, and status.



# List fetch usage
Source: https://docs.tinyfish.ai/api-reference/list-fetch-usage

https://agent.tinyfish.ai/v1/openapi/fetch get /usage
List fetch usage records for the authenticated user. Returns paginated results with URL, format, status, and metadata for each fetch operation.



# List research runs
Source: https://docs.tinyfish.ai/api-reference/list-research-runs

https://agent.tinyfish.ai/v1/openapi/research get /v1/research-run
List saved research runs with optional filtering by status, query text, and date range. Cursors are only valid with the sort direction used to generate them.



# List search usage
Source: https://docs.tinyfish.ai/api-reference/list-search-usage

https://agent.tinyfish.ai/v1/openapi/search get /usage
List search usage records for the authenticated user. Returns paginated results with query details, status, and result counts.



# Run research with SSE streaming
Source: https://docs.tinyfish.ai/api-reference/run-research-with-sse-streaming

https://agent.tinyfish.ai/v1/openapi/research post /v1/automation/run-research
Search, evaluate sources, and synthesize a cited report from a natural-language query. Accepted requests always return a Server-Sent Events stream, including when stream is false.



# Cancel multiple runs by IDs
Source: https://docs.tinyfish.ai/api-reference/runs/cancel-multiple-runs-by-ids

https://agent.tinyfish.ai/v1/openapi/main post /v1/runs/batch/cancel
Cancel multiple runs by their IDs in a single request. Returns per-run results including cancelled runs, already-terminal runs, and not-found IDs. Maximum 100 IDs per request. Idempotent: calling twice returns consistent results.



# Cancel run by ID
Source: https://docs.tinyfish.ai/api-reference/runs/cancel-run-by-id

https://agent.tinyfish.ai/v1/openapi/main post /v1/runs/{id}/cancel
Cancel a run by ID. Only runs created via `/v1/automation/run-async` or `/v1/automation/run-sse` can be cancelled. Runs created via the synchronous `/v1/automation/run` endpoint cannot be cancelled.



# Get multiple runs by IDs
Source: https://docs.tinyfish.ai/api-reference/runs/get-multiple-runs-by-ids

https://agent.tinyfish.ai/v1/openapi/main post /v1/runs/batch
Retrieve multiple runs by their IDs in a single request. Returns found runs and lists any IDs that were not found or not owned. Maximum 100 IDs per request.



# Get run by ID
Source: https://docs.tinyfish.ai/api-reference/runs/get-run-by-id

https://agent.tinyfish.ai/v1/openapi/main get /v1/runs/{id}
Get detailed information about a specific automation run by its ID.



# Get step HTML snapshot
Source: https://docs.tinyfish.ai/api-reference/runs/get-step-html-snapshot

https://agent.tinyfish.ai/v1/openapi/main get /v1/runs/{id}/steps/{stepId}/html
Serve the full-page HTML snapshot captured at a specific step via API key. Returns raw HTML. Only available when the run was started with capture_config.html: true.



# Get step screenshot
Source: https://docs.tinyfish.ai/api-reference/runs/get-step-screenshot

https://agent.tinyfish.ai/v1/openapi/main get /v1/runs/{id}/steps/{stepId}/screenshot
Serve the JPEG screenshot captured at a specific step via API key. Returns binary image data. Note: screenshots=url on GET /v1/runs/{id} returns browser-accessible URLs at /runs/{id}/steps/{stepId}/screenshot (session auth).



# List and search runs
Source: https://docs.tinyfish.ai/api-reference/runs/list-and-search-runs

https://agent.tinyfish.ai/v1/openapi/main get /v1/runs
List automation runs with optional filtering by status, goal text, and date range. Returns paginated results with total count. Default sort order is newest first.



# Search the web
Source: https://docs.tinyfish.ai/api-reference/search-the-web

https://agent.tinyfish.ai/v1/openapi/search get /
Search the web and get structured results. Returns ranked results with titles, snippets, and URLs.

**Location and language resolution:**
- If `location` is set but `language` is not, the language auto-resolves to the most predominantly used language in that country.
- If `language` is set but `location` is not, the location auto-resolves to the country where that language is most predominantly used.
- If neither `location` nor `language` is set, defaults to `US` and `en`.



# Start research asynchronously
Source: https://docs.tinyfish.ai/api-reference/start-research-asynchronously

https://agent.tinyfish.ai/v1/openapi/research post /v1/automation/run-research-async
Enqueue research and return its ID after durable dispatch. Poll GET /v1/research-run/{id} or attach to its events endpoint.



# Terminate a browser session
Source: https://docs.tinyfish.ai/api-reference/terminate-a-browser-session

https://agent.tinyfish.ai/v1/openapi/browser delete /{sessionId}
Terminates a remote browser session immediately. If the session is already ended this call is idempotent and still returns 204.



# Connect a vault provider
Source: https://docs.tinyfish.ai/api-reference/vault/connect-a-vault-provider

https://agent.tinyfish.ai/v1/openapi/main post /v1/vault/connections
Connect a supported password manager and immediately sync display-safe credential metadata.



# Disconnect a vault provider
Source: https://docs.tinyfish.ai/api-reference/vault/disconnect-a-vault-provider

https://agent.tinyfish.ai/v1/openapi/main delete /v1/vault/connections/{connectionId}
Disconnect a vault provider and remove its stored enabled items.



# List vault connections
Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-connections

https://agent.tinyfish.ai/v1/openapi/main get /v1/vault/connections
List all connected vault providers for the authenticated user.



# List vault items
Source: https://docs.tinyfish.ai/api-reference/vault/list-vault-items

https://agent.tinyfish.ai/v1/openapi/main get /v1/vault/items
List all vault items currently available from connected providers.



# Sync vault items
Source: https://docs.tinyfish.ai/api-reference/vault/sync-vault-items

https://agent.tinyfish.ai/v1/openapi/main post /v1/vault/items/sync
Sync items from connected providers and return merged item state plus sync counters.



# Get wallet
Source: https://docs.tinyfish.ai/api-reference/wallet/get-wallet

https://agent.tinyfish.ai/v1/openapi/main get /v1/wallet
Get the caller's wallet: current balance, auto-reload configuration, per-product contract rates, and any in-flight top-up.



# Top up wallet (agent-paid)
Source: https://docs.tinyfish.ai/api-reference/wallet/top-up-wallet-agent-paid

https://agent.tinyfish.ai/v1/openapi/main post /v1/wallet/top-up
Add money to the wallet, paid by the calling agent over the Machine Payments Protocol (MPP). The first call answers 402 with a payment challenge in WWW-Authenticate; retry with a Payment-Authorization credential to settle the charge and credit the wallet.



# Authentication
Source: https://docs.tinyfish.ai/authentication

How to authenticate with the TinyFish API

TinyFish uses different authentication methods depending on how you're accessing the API:

| Access Method | Auth Type | When to Use |
| - | - | - |
| REST API | API Key | Direct HTTP requests from your code |
| MCP Integration | OAuth 2.1 | AI assistants (Claude, Cursor) |

***

## REST API Authentication

All REST API requests require an API key passed in the `X-API-Key` header.

### Getting Your API Key

<Steps>
  <Step title="Go to the API Keys page">
    Visit [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)
  </Step>

  <Step title="Create a new key">
    Click "Create API Key"
  </Step>

  <Step title="Copy and store your key">
    Copy and store your key securely
  </Step>
</Steps>

<Warning>
  API keys are shown only once. Store them securely and never commit them to version control.
</Warning>

### Using Your API Key

Pass your API key when making requests. The Python SDK reads `TINYFISH_API_KEY` from your environment automatically:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()  # Reads TINYFISH_API_KEY from environment

  result = client.agent.run(
      url="https://example.com",
      goal="Extract the page title",
  )
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

  const response = await client.agent.run({
    url: "https://example.com",
    goal: "Extract the page title",
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://agent.tinyfish.ai/v1/automation/run \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com", "goal": "Extract the page title"}'
  ```
</CodeGroup>

### Environment Variables

Store your API key in an environment variable:

```bash theme={null}
# Add to your shell profile (.bashrc, .zshrc, etc.)
export TINYFISH_API_KEY="your_api_key_here"
```

For Node.js projects, use a `.env` file:

```bash theme={null}
# .env
TINYFISH_API_KEY=your_api_key_here
```

<Warning>
  Add `.env` to your `.gitignore` to prevent accidental commits.
</Warning>

***

## MCP Authentication

The MCP endpoint uses OAuth 2.1 for secure authentication with AI assistants.

### How It Works

<Steps>
  <Step title="Add the TinyFish MCP server">
    Add the TinyFish MCP server to your AI client configuration. See the [MCP Integration guide](/mcp-integration) for setup instructions.
  </Step>

  <Step title="Authenticate in browser">
    When you first use the tool, a browser window opens for authentication
  </Step>

  <Step title="Log in">
    Log in with your TinyFish account
  </Step>

  <Step title="Start using TinyFish Web Agent">
    Authorization is cached for future sessions
  </Step>
</Steps>

<Note>
  You need a TinyFish account. Search and Fetch are free within a daily allowance; Agent and Browser draw from your wallet (plan credits on legacy accounts). [Sign up here](https://agent.tinyfish.ai/api-keys).
</Note>

***

## Error Responses

Authentication errors return standard HTTP status codes with a JSON error body. See [Error Codes](/error-codes) for the full reference.

<AccordionGroup>
  <Accordion title="401 Unauthorized — Missing API Key" icon="key">
    The request is missing the `X-API-Key` header.

    ```json theme={null}
    {
      "error": {
        "code": "MISSING_API_KEY",
        "message": "X-API-Key header is required"
      }
    }
    ```

    **How to fix:**

    * Add the `X-API-Key` header to your request
    * Check the header name is exactly `X-API-Key` (case-sensitive)
  </Accordion>

  <Accordion title="401 Unauthorized — Invalid API Key" icon="xmark">
    The API key in the request is not valid.

    ```json theme={null}
    {
      "error": {
        "code": "INVALID_API_KEY",
        "message": "The provided API key is invalid"
      }
    }
    ```

    **How to fix:**

    * Verify your API key is correct
    * Ensure no extra whitespace around the key
    * Check if the key has been revoked or regenerated

    ```bash theme={null}
    # Debug: Check your key is set
    echo $TINYFISH_API_KEY

    # Debug: Test authentication
    curl -I -X POST https://agent.tinyfish.ai/v1/automation/run \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://example.com", "goal": "test"}'
    ```
  </Accordion>

  <Accordion title="403 Forbidden — Insufficient Credits (legacy accounts)" icon="credit-card">
    Authentication succeeded, but you lack credits or an active subscription. This applies to legacy credit/subscription accounts — wallet accounts get a 402 instead, see below.

    ```json theme={null}
    {
      "error": {
        "code": "FORBIDDEN",
        "message": "Insufficient credits or no active subscription"
      }
    }
    ```

    **How to fix:**

    * Check your account at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)
    * Add credits to your account
  </Accordion>

  <Accordion title="402 Payment Required — Insufficient Credits (wallet accounts)" icon="wallet">
    Your TinyFish wallet balance is too low to start this run. Non-retryable until money is added.

    ```json theme={null}
    {
      "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
        "details": {
          "status": "failed",
          "error": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
          "reason": "wallet_out_of_funds",
          "non_retryable": true,
          "balance": "-2.50",
          "currency": "usd",
          "wallet_url": "https://agent.tinyfish.ai/wallet",
          "minimum_top_up": "10.00",
          "auto_reload_needs_payment_fix": false
        }
      }
    }
    ```

    **How to fix:**

    * Check your balance with `GET /v1/wallet` (or `client.wallet.get()`, `tinyfish wallet status`)
    * Add money at [agent.tinyfish.ai/wallet](https://agent.tinyfish.ai/wallet) — minimum top-up is \$10
    * If `auto_reload_needs_payment_fix` is `true`, auto-reload is also paused on a declined payment method — update it on the same page

    Not sure whether your account is on wallet or legacy billing? `GET /v1/wallet` returns 404 with `error.code: "FEATURE_NOT_AVAILABLE"` for legacy accounts — see [Error Codes](/error-codes#feature-not-available) for the full discriminator.
  </Accordion>
</AccordionGroup>

***

## Security Best Practices

<CardGroup>
  <Card title="Use Environment Variables" icon="key">
    Never hardcode API keys in source code
  </Card>

  <Card title="Rotate Keys Regularly" icon="rotate">
    Regenerate keys periodically and after team changes
  </Card>

  <Card title="Limit Exposure" icon="shield">
    Use separate keys for development and production
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Review API usage in your dashboard for anomalies
  </Card>
</CardGroup>

***

## Related

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Run your first automation
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Full error code reference
  </Card>
</CardGroup>


# Browser Examples
Source: https://docs.tinyfish.ai/browser-api/examples

Real-world examples for the Browser API

## Create a Session

Start a remote browser session and get the CDP connection URL:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  session = client.browser.sessions.create(url="https://example.com")

  print(f"Session: {session.session_id}")
  print(f"CDP URL: {session.cdp_url}")
  print(f"Base URL: {session.base_url}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const session = await client.browser.sessions.create({
    url: "https://example.com",
  });

  console.log(`Session: ${session.session_id}`);
  console.log(`CDP URL: ${session.cdp_url}`);
  console.log(`Base URL: ${session.base_url}`);
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.browser.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://example.com"}'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "session_id": "tf-84ac6714-0f08-4592-b626-e51105a079f9",
  "cdp_url": "wss://ip-52-53-175-49.tetra-data.tinyfish.io/tf-84ac6714-...",
  "base_url": "https://ip-52-53-175-49.tetra-data.tinyfish.io/tf-84ac6714-..."
}
```

## Connect with Playwright

Create a session and control it with Playwright via CDP:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from playwright.async_api import async_playwright
  from tinyfish import TinyFish

  async def main():
      client = TinyFish()
      session = client.browser.sessions.create(url="https://scrapeme.live/shop")

      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(session.cdp_url)
          page = browser.contexts[0].pages[0]

          await asyncio.sleep(2)
          await page.wait_for_load_state("domcontentloaded")

          title = await page.title()
          print(f"Page title: {title}")

          await page.screenshot(path="shop.png")
          print("Screenshot saved to shop.png")

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { chromium } from "playwright";
  import { TinyFish } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();
    const session = await client.browser.sessions.create({
      url: "https://scrapeme.live/shop",
    });

    const browser = await chromium.connectOverCDP(session.cdp_url);
    const page = browser.contexts()[0].pages()[0];

    await page.waitForTimeout(2000);
    await page.waitForLoadState("domcontentloaded");

    const title = await page.title();
    console.log(`Page title: ${title}`);

    await page.screenshot({ path: "shop.png" });
    console.log("Screenshot saved to shop.png");
  }

  main();
  ```
</CodeGroup>

<Note>
  Session creation takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds. The browser navigates to the URL asynchronously — wait for `domcontentloaded` before interacting.
</Note>

## Scrape with Playwright

Extract structured data from a page using Playwright selectors:

<CodeGroup>
  ```python Python theme={null}
  import asyncio, json
  from playwright.async_api import async_playwright
  from tinyfish import TinyFish

  async def main():
      client = TinyFish()
      session = client.browser.sessions.create(url="https://scrapeme.live/shop")

      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(session.cdp_url)
          page = browser.contexts[0].pages[0]
          await asyncio.sleep(2)
          await page.wait_for_load_state("domcontentloaded")

          products = await page.evaluate("""
              () => [...document.querySelectorAll('.product')].slice(0, 5).map(el => ({
                  name: el.querySelector('.woocommerce-loop-product__title')?.textContent,
                  price: el.querySelector('.price .amount')?.textContent,
              }))
          """)

          print(json.dumps(products, indent=2))

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { chromium } from "playwright";
  import { TinyFish } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();
    const session = await client.browser.sessions.create({
      url: "https://scrapeme.live/shop",
    });

    const browser = await chromium.connectOverCDP(session.cdp_url);
    const page = browser.contexts()[0].pages()[0];
    await page.waitForTimeout(2000);
    await page.waitForLoadState("domcontentloaded");

    const products = await page.evaluate(() =>
      [...document.querySelectorAll(".product")].slice(0, 5).map((el) => ({
        name: el.querySelector(".woocommerce-loop-product__title")?.textContent,
        price: el.querySelector(".price .amount")?.textContent,
      }))
    );

    console.log(JSON.stringify(products, null, 2));
  }

  main();
  ```
</CodeGroup>

**Output:**

```json theme={null}
[
  { "name": "Bulbasaur", "price": "£63.00" },
  { "name": "Ivysaur", "price": "£87.00" },
  { "name": "Venusaur", "price": "£105.00" },
  { "name": "Charmander", "price": "£48.00" },
  { "name": "Charmeleon", "price": "£165.00" }
]
```

## Browse from a Specific Country

Pass `proxy_config.country_code` to exit from any country (ISO 3166-1 alpha-2). The session keeps the same residential IP across all of its connections:

<CodeGroup>
  ```python Python theme={null}
  import asyncio, os
  import httpx
  from playwright.async_api import async_playwright

  async def main():
      resp = httpx.post(
          "https://api.browser.tinyfish.ai",
          headers={"X-API-Key": os.environ["TINYFISH_API_KEY"]},
          json={"url": "https://ipinfo.io/json", "proxy_config": {"country_code": "JP"}},
          timeout=60,
      )
      resp.raise_for_status()
      session = resp.json()

      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(session["cdp_url"])
          page = browser.contexts[0].pages[0]
          await page.wait_for_load_state("domcontentloaded")
          print(await page.inner_text("body"))  # "country": "JP"

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { chromium } from "playwright";

  const res = await fetch("https://api.browser.tinyfish.ai", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TINYFISH_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: "https://ipinfo.io/json",
      proxy_config: { country_code: "JP" },
    }),
  });
  const session = await res.json();

  const browser = await chromium.connectOverCDP(session.cdp_url);
  const page = browser.contexts()[0].pages()[0];
  await page.waitForLoadState("domcontentloaded");
  console.log(await page.innerText("body")); // "country": "JP"
  ```
</CodeGroup>

To route through your own proxy instead, send `{"type": "custom", "url": "http://proxy.example.com:8080", "username": "...", "password": "..."}`. To connect without a proxy, send `{"enabled": false}`. See the [reference](/browser-api/reference#parameters) for all fields.

***

## Related

<CardGroup>
  <Card title="Browser Reference" icon="browser" href="/browser-api/reference">
    Session parameters, lifecycle, and debugging
  </Card>

  <Card title="Browser Profiles" icon="window" href="/key-concepts/browser-profiles">
    Standard and stealth browser modes
  </Card>
</CardGroup>


# Browser API
Source: https://docs.tinyfish.ai/browser-api/index

Create a remote browser session and control it programmatically

The Browser API creates a remote browser session and returns a WebSocket connection URL. Use it when you need direct, low-level browser control — scripting page interactions, running your own automation framework, or tasks that go beyond the [automation run API](/key-concepts/endpoints).

<Note>
  Browser API sessions are isolated and do not persist cookies or storage by themselves. For reusable login state, use [Browser Context Profiles](/agent-api/browser-context-profiles): create a setup session, connect your controller to `cdp_url`, save it, then run Agent API automations with `use_profile: true`.
</Note>

```bash theme={null}
POST https://api.browser.tinyfish.ai
```

***

## Before You Start

<Steps>
  <Step title="Get your API key">
    Create a key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
  </Step>

  <Step title="Store it in your environment">
    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>

  <Step title="Install the required packages">
    <CodeGroup>
      ```bash Python theme={null}
      pip install -U tinyfish playwright
      playwright install chromium
      ```

      ```bash Node theme={null}
      npm install @tiny-fish/sdk@latest playwright
      npx playwright install chromium
      ```
    </CodeGroup>
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for the full setup and troubleshooting guide.

## Your First Request

<Note>
  Session creation typically takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds.
</Note>

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  session = client.browser.sessions.create(url="https://www.tinyfish.ai")
  print(session.session_id)
  print(session.cdp_url)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const session = await client.browser.sessions.create({
    url: "https://www.tinyfish.ai",
  });
  console.log(session.session_id);
  console.log(session.cdp_url);
  ```

  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

## What Success Looks Like

```json theme={null}
{
  "session_id": "br-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cdp_url": "wss://example.tinyfish.io/cdp",
  "base_url": "https://example.tinyfish.io"
}
```

Then connect with Playwright using `cdp_url`:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from playwright.async_api import async_playwright

  CDP_URL = "<cdp_url from API response>"

  async def main():
      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(CDP_URL)
          await asyncio.sleep(2)  # let startup navigation settle

          page = browser.contexts[0].pages[0]
          await page.wait_for_load_state("domcontentloaded")
          print(await page.title())

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { chromium } from 'playwright';

  const CDP_URL = '<cdp_url from API response>';

  const browser = await chromium.connectOverCDP(CDP_URL);
  await new Promise(r => setTimeout(r, 2000)); // let startup navigation settle

  const page = browser.contexts()[0].pages()[0];
  await page.waitForLoadState('domcontentloaded');
  console.log(await page.title());
  ```
</CodeGroup>

<Note>
  Pass `cdp_url` (the WebSocket URL) to `connect_over_cdp`. Do not use `base_url` — it is for polling session status via `/pages`, not for Playwright connections.
</Note>

## Proxies

By default, every session connects through the TinyFish residential proxy in the US and keeps the same exit IP across all of its connections. Use `proxy_config` to pick another country, bring your own proxy, or connect directly:

<CodeGroup>
  ```bash Another country theme={null}
  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", "proxy_config": {"country_code": "DE"}}'
  ```

  ```bash Your own proxy theme={null}
  curl -X POST https://api.browser.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"proxy_config": {"type": "custom", "url": "http://proxy.example.com:8080", "username": "user", "password": "pass"}}'
  ```

  ```bash No proxy theme={null}
  curl -X POST https://api.browser.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"proxy_config": {"enabled": false}}'
  ```
</CodeGroup>

See the [reference](/browser-api/reference#parameters) for every `proxy_config` field.

## When to Use Browser vs the Other APIs

* Use **Browser** when you want direct Playwright or CDP control.
* Use **Agent** when TinyFish should decide the browser actions from a goal.
* Use **Fetch** when you only need extracted content from one or more URLs.
* Use **Search** when you need ranked search results, not a browser session.

***

## Session Lifecycle

| Behavior | Details |
| - | - |
| **Startup navigation** | If `url` was provided at session creation, the browser navigates there immediately. The 201 response is returned before navigation completes — the page may still be loading when you connect. |
| **Inactivity timeout** | Sessions automatically terminate after the inactivity timeout — `timeout_seconds` if set, otherwise your plan maximum (15 minutes on free plans, 60 minutes on paid). A session is considered inactive when no CDP commands are being sent. |
| **Explicit termination** | Send `DELETE https://api.browser.tinyfish.ai/{session_id}` to end a session immediately. See the [reference](/browser-api/reference). |
| **Network** | Sessions connect through the TinyFish residential proxy in the US by default, with one exit IP per session. See [Proxies](#proxies). |
| **Session isolation** | Each direct Browser API session is isolated. For reusable cookies and storage, set up a [Browser Context Profile](/agent-api/browser-context-profiles) instead. |

***

## Read Next

<CardGroup>
  <Card title="API Reference" icon="code" href="/browser-api/reference">
    Request and response schema
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup
  </Card>

  <Card title="Browser Context Profiles" icon="window" href="/agent-api/browser-context-profiles">
    Persist login state for future Agent API runs
  </Card>

  <Card title="Browser Profiles" icon="browser" href="/key-concepts/browser-profiles">
    Configure browser runtime behavior for automation runs
  </Card>

  <Card title="Key Concepts" icon="plug" href="/key-concepts/endpoints">
    Understand when to use Agent vs Browser
  </Card>

  <Card title="For coding agents" icon="robot" href="/for-coding-agents">
    One page that routes an agent to the right TinyFish API
  </Card>
</CardGroup>


# Browser API Reference
Source: https://docs.tinyfish.ai/browser-api/reference

Complete reference for the Browser API endpoints

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `https://api.browser.tinyfish.ai` | Create a browser session |
| `DELETE` | `https://api.browser.tinyfish.ai/{session_id}` | Terminate a browser session |

All requests require an `X-API-Key` header. See [Authentication](/authentication).

<Note>
  The SDKs (`tinyfish` for Python and `@tiny-fish/sdk` for TypeScript) target `https://agent.tinyfish.ai/v1/browser` by default, while the REST host documented here is `https://api.browser.tinyfish.ai`. Both hosts are supported and behave identically.
</Note>

<Note>
  Session creation typically takes 10-30 seconds. Set your HTTP client timeout to at least 60 seconds. Direct Browser API sessions are isolated; use [Browser Context Profiles](/agent-api/browser-context-profiles) when you need reusable cookies or storage.
</Note>

***

## Request

```json theme={null}
{
  "url": "https://www.tinyfish.ai",
  "timeout_seconds": 300,
  "proxy_config": { "country_code": "DE" }
}
```

### Parameters

<ParamField type="string">
  Target URL the session will navigate to on startup. Bare domains (e.g. `tinyfish.ai`) are automatically prefixed with `https://`. Omit to start at `about:blank`.
</ParamField>

<ParamField type="integer">
  Inactivity timeout in seconds (5–86400). Defaults to your account's maximum.
</ParamField>

<ParamField type="object">
  How the session connects to the internet. Omit to use the TinyFish residential proxy in the US.

  | Field | Type | Default | Description |
  | - | - | - | - |
  | `enabled` | `boolean` | `true` | Set `false` to connect directly, with no proxy. Other fields are ignored. |
  | `type` | `"tinyfish"` \| `"custom"` | `"tinyfish"` | `tinyfish` uses the TinyFish residential proxy. `custom` routes through your own proxy. |
  | `country_code` | `string` | `"US"` | Exit country for the `tinyfish` proxy. Any [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code, case-insensitive (e.g. `DE`, `jp`). Not allowed with `custom`. |
  | `url` | `string` | — | Your proxy URL. Required with `custom`. Must be `http://` or `https://`. |
  | `username` | `string` | — | Username for your custom proxy. |
  | `password` | `string` | — | Password for your custom proxy. |

  Unknown fields are rejected with `400`.
</ParamField>

### Proxy Behavior

* **Sticky exit IP.** With the `tinyfish` proxy, a session keeps the same exit IP across all its connections, including after idle periods. Different sessions get different IPs. Residential IPs can occasionally go offline; the session then moves to a new IP in the same country.
* **Default.** Sessions created without `proxy_config` use the `tinyfish` proxy in the US.
* **Custom proxies.** TinyFish connects to your proxy as given and does not rotate or pin its IP. Only `http://` and `https://` proxies are supported.

***

## Response

On success, returns `201 Created` with a JSON body containing `session_id`, `cdp_url`, and `base_url`.

```json theme={null}
{
  "session_id": "br-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "cdp_url": "wss://example.tinyfish.io/cdp",
  "base_url": "https://example.tinyfish.io"
}
```

<ResponseField name="session_id" type="string">
  Unique identifier for this session.
</ResponseField>

<ResponseField name="cdp_url" type="string">
  WebSocket URL for browser connection. Pass this to Playwright's `connect_over_cdp` or any CDP client.
</ResponseField>

<ResponseField name="base_url" type="string">
  HTTPS base URL for the session. Use to access session endpoints such as `/pages`.
</ResponseField>

***

## DELETE — Terminate a Session

```bash theme={null}
DELETE https://api.browser.tinyfish.ai/{session_id}
```

Terminates the session immediately. If the session is already ended this call is a no-op and still returns `204`.

### Path Parameters

<ParamField type="string">
  The `session_id` returned when the session was created.
</ParamField>

### Response

Returns `204 No Content` with an empty body on success.

### Error Codes

| HTTP Status | Error Code | Cause |
| - | - | - |
| 400 | `INVALID_INPUT` | `session_id` is missing or empty. |
| 401 | `MISSING_API_KEY` / `INVALID_API_KEY` | Missing or invalid `X-API-Key`. |
| 404 | `NOT_FOUND` | Session does not exist or belongs to a different API key. |
| 409 | `RETRY_REQUIRED` | Conflicting operation on the session. Termination not confirmed — retry the delete shortly. |
| 429 | `RATE_LIMIT_EXCEEDED` | Browser infrastructure rate limit. Honor `Retry-After`. |
| 500 | `INTERNAL_ERROR` | Unexpected or non-retryable infrastructure failure. Termination is not confirmed — the session may still be running; retry the delete. |
| 503 | `SERVICE_BUSY` | Browser infrastructure temporarily unavailable. Termination not confirmed — retry, honoring `Retry-After`. |
| 504 | `TIMEOUT` | Browser infrastructure timed out terminating the session. Retry. |

Infrastructure errors include `error.details.upstream_status` — the backend status when one was received, otherwise the status TinyFish synthesized (502 for transport failures, 504 for timeouts). Every error also carries `request_id`, echoed in the `X-Request-ID` header; quote it when contacting support.

***

## Debugging — Open DevTools Inspector

Poll `GET {base_url}/pages` and open the `devtoolsFrontendUrl` of the first non-blank page to inspect the live browser session.

<CodeGroup>
  ```python Python theme={null}
  async def get_inspector_url(base_url: str) -> str:
      async with httpx.AsyncClient() as client:
          for _ in range(20):
              pages = (await client.get(f"{base_url}/pages", timeout=5)).json()
              nav = next((p for p in pages if p.get("url") not in ("", "about:blank", "about:newtab")), None)
              if nav:
                  return nav["devtoolsFrontendUrl"]
              await asyncio.sleep(1)
      raise TimeoutError("navigation never completed")
  ```

  ```typescript TypeScript theme={null}
  async function getInspectorUrl(baseUrl: string): Promise<string> {
    for (let i = 0; i < 20; i++) {
      const res = await fetch(`${baseUrl}/pages`);
      const pages: { url: string; devtoolsFrontendUrl: string }[] = await res.json();
      const nav = pages.find(p => !['', 'about:blank', 'about:newtab'].includes(p.url));
      if (nav) return nav.devtoolsFrontendUrl;
      await new Promise(r => setTimeout(r, 1000));
    }
    throw new Error('navigation never completed');
  }
  ```
</CodeGroup>

<Note>
  The page starts at `about:blank` and navigates asynchronously — skip blank pages when polling to get the correct inspector URL.
</Note>

***

## Session Lifecycle

| Behavior | Details |
| - | - |
| **Startup navigation** | If `url` was provided at session creation, the browser navigates there immediately. The 201 response is returned before navigation completes — the page may still be loading when you connect. |
| **Inactivity timeout** | Sessions automatically terminate after the configured inactivity timeout. A session is considered inactive when no CDP commands are being sent. |
| **Explicit termination** | Send `DELETE https://api.browser.tinyfish.ai/{session_id}` to terminate a session immediately. Returns `204 No Content` on success. Deleting an already-ended session is idempotent. |
| **Session isolation** | Each direct Browser API session is isolated. For reusable cookies and storage, use [Browser Context Profiles](/agent-api/browser-context-profiles). |

***

## SDK Methods

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  session = client.browser.sessions.create(url="https://www.tinyfish.ai")
  print(session.session_id)
  print(session.cdp_url)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const session = await client.browser.sessions.create({
    url: "https://www.tinyfish.ai",
  });
  console.log(session.session_id);
  console.log(session.cdp_url);
  ```
</CodeGroup>

***

## End-to-End Example

Create a session, connect with Playwright, take a screenshot, and extract the page title.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from tinyfish import TinyFish
  from playwright.async_api import async_playwright

  client = TinyFish()

  async def main():
      # 1. Create a browser session
      session = client.browser.sessions.create(url="https://scrapeme.live/shop")

      # 2. Connect via Playwright CDP
      async with async_playwright() as p:
          browser = await p.chromium.connect_over_cdp(session.cdp_url)
          await asyncio.sleep(2)  # let startup navigation settle

          page = browser.contexts[0].pages[0]
          await page.wait_for_load_state("domcontentloaded")

          # 3. Interact with the page
          print(await page.title())
          await page.screenshot(path="shop.png")

      # Session ends after its inactivity timeout, or DELETE it explicitly

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";
  import { chromium } from "playwright";

  const client = new TinyFish();

  // 1. Create a browser session
  const session = await client.browser.sessions.create({
    url: "https://scrapeme.live/shop",
  });

  // 2. Connect via Playwright CDP
  const browser = await chromium.connectOverCDP(session.cdp_url);
  await new Promise((r) => setTimeout(r, 2000)); // let startup navigation settle

  const page = browser.contexts()[0].pages()[0];
  await page.waitForLoadState("domcontentloaded");

  // 3. Interact with the page
  console.log(await page.title());
  await page.screenshot({ path: "shop.png" });

  // Session ends after its inactivity timeout, or DELETE it explicitly
  ```
</CodeGroup>

***

## Error Reference

| HTTP Status | Error Code | Cause | Resolution |
| - | - | - | - |
| 400 | `INVALID_INPUT` | `url` field is not a valid URL, or `proxy_config` is invalid (unknown field, unknown `country_code`, `custom` without `url`, non-HTTP(S) proxy URL). | Check the `details` field in the error response for specifics. |
| 401 | `MISSING_API_KEY` / `INVALID_API_KEY` | Missing or invalid `X-API-Key` header. | Verify your API key at the [dashboard](https://agent.tinyfish.ai/api-keys). |
| 402 | `INSUFFICIENT_CREDITS` | Your TinyFish wallet balance is too low to start this run. | Check `GET /v1/wallet` and add money at the [wallet page](https://agent.tinyfish.ai/wallet) — minimum top-up \$10. |
| 404 | `NOT_FOUND` | Browser API is not enabled for your account. | Contact support to enable access. |
| 409 | `RETRY_REQUIRED` | Upstream conflict creating the session. | Retry after a brief delay. |
| 429 | `RATE_LIMIT_EXCEEDED` | Browser infrastructure rate limit. | Back off and honor the `Retry-After` header. |
| 500 | `INTERNAL_ERROR` | Unexpected server error, including non-retryable infrastructure failures. | Not resolved by retrying. If persistent, check [agent.tinyfish.ai/status](https://agent.tinyfish.ai/status). |
| 503 | `SERVICE_BUSY` | Browser infrastructure temporarily unavailable. Session creation was not confirmed. | Retry, honoring the `Retry-After` header. `error.details.upstream_status` carries the backend status, or the status TinyFish synthesized when the call never completed. |
| 504 | `TIMEOUT` | Browser infrastructure timed out starting the session. | Retry after a brief delay. |

## Related

<CardGroup>
  <Card title="Browser Overview" icon="browser" href="/browser-api">
    First request, success shape, and product routing
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup
  </Card>

  <Card title="Browser Context Profiles" icon="window" href="/agent-api/browser-context-profiles">
    Persist login state for future Agent API runs
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Full list of API error codes
  </Card>

  <Card title="Key Concepts" icon="plug" href="/key-concepts/endpoints">
    Understand where Browser fits in the overall API surface
  </Card>
</CardGroup>


# CLI Commands
Source: https://docs.tinyfish.ai/cli/commands

Full reference for TinyFish CLI commands

## `tinyfish search query`

Run a web search. Returns ranked results with titles, URLs, and snippets.

```bash theme={null}
tinyfish search query "best React state management libraries"
```

### Flags

| Flag | Description |
| - | - |
| `--location <value>` | Location hint for geo-targeted results (e.g. `"Vietnam"`) |
| `--language <value>` | Language hint (e.g. `"en"`) |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "query": "best React state management libraries",
  "total_results": 10,
  "results": [
    {
      "position": 1,
      "site_name": "Reddit",
      "title": "Best State Management for React in 2026",
      "url": "https://reddit.com/r/reactjs/...",
      "snippet": "Zustand and Jotai are the most popular choices..."
    }
  ]
}
```

### Examples

<CodeGroup>
  ```bash Basic query theme={null}
  tinyfish search query "tinyfish web automation"
  ```

  ```bash Geo-targeted theme={null}
  tinyfish search query "best pho in Saigon" --location "Vietnam" --language "en"
  ```

  ```bash Human-readable theme={null}
  tinyfish search query "tinyfish web automation" --pretty
  ```
</CodeGroup>

***

## `tinyfish search usage`

List your past search requests.

```bash theme={null}
tinyfish search usage [--status completed|failed] [--limit <n>] [--page <n>]
```

### Flags

| Flag | Description |
| - | - |
| `--start-after <iso>` | Only items created after this ISO 8601 timestamp |
| `--end-before <iso>` | Only items created before this ISO 8601 timestamp |
| `--status <status>` | Filter by status (completed\|failed) |
| `--limit <n>` | Items per page, 1-1000 (default 100) |
| `--page <n>` | Page number, starting from 1 |
| `--pretty` | One line per item, then the page count |

JSON output is the paged response: `{ "items": [...], "total", "limit", "page", "total_pages", "has_more" }`.

## `tinyfish fetch content get`

Fetch clean, extracted content from one or more URLs. Strips ads, navigation, and boilerplate — returns just the content.

```bash theme={null}
tinyfish fetch content get "https://example.com/article"
```

<Note>
  Accepts up to 10 URLs in a single call. Multiple URLs are fetched in parallel server-side.
</Note>

### Flags

| Flag | Description |
| - | - |
| `--format <format>` | Output format: `markdown` (default), `html`, or `json` |
| `--links` | Include extracted links from the page |
| `--image-links` | Include extracted image URLs |
| `--per-url-timeout-ms <milliseconds>` | Per-URL timeout budget, from `1` to `110000` milliseconds |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "results": [
    {
      "url": "https://example.com/article",
      "final_url": "https://example.com/article/",
      "title": "Article Title",
      "description": "A brief description",
      "language": "en",
      "author": "Jane Doe",
      "published_date": "2026-01-15",
      "format": "markdown",
      "text": "# Article Title\n\nThe full article content in clean markdown...",
      "latency_ms": 1430.39
    }
  ],
  "errors": []
}
```

When `--links` or `--image-links` are set, each result also includes:

```json theme={null}
{
  "links": ["https://example.com/about", "https://example.com/contact"],
  "image_links": ["https://example.com/hero.png"]
}
```

### Examples

<CodeGroup>
  ```bash Single URL theme={null}
  tinyfish fetch content get --format markdown "https://example.com/article"
  ```

  ```bash Multiple URLs theme={null}
  tinyfish fetch content get "https://site-a.com" "https://site-b.com" "https://site-c.com"
  ```

  ```bash With link extraction theme={null}
  tinyfish fetch content get --links --image-links "https://example.com"
  ```

  ```bash Custom timeout theme={null}
  tinyfish fetch content get --per-url-timeout-ms 45000 "https://example.com"
  ```

  ```bash HTML format theme={null}
  tinyfish fetch content get --format html "https://example.com"
  ```
</CodeGroup>

***

## `tinyfish fetch usage`

List your past fetch requests.

```bash theme={null}
tinyfish fetch usage [--status completed|failed] [--limit <n>] [--page <n>]
```

### Flags

| Flag | Description |
| - | - |
| `--start-after <iso>` | Only items created after this ISO 8601 timestamp |
| `--end-before <iso>` | Only items created before this ISO 8601 timestamp |
| `--status <status>` | Filter by status (completed\|failed) |
| `--limit <n>` | Items per page, 1-1000 (default 100) |
| `--page <n>` | Page number, starting from 1 |
| `--pretty` | One line per item, then the page count |

JSON output is the paged response: `{ "items": [...], "total", "limit", "page", "total_pages", "has_more" }`.

## `tinyfish agent run`

Execute a browser automation. By default the output streams as newline-delimited JSON — one object per event.

```bash theme={null}
tinyfish agent run "goal" --url example.com
```

### Flags

| Flag | Description |
| - | - |
| `--url <url>` | Target URL to automate (required) |
| `--sync` | Wait for the run to complete and return the full result |
| `--async` | Submit only — return the `run_id` immediately without waiting |
| `--output-schema <json>` | Inline JSON Schema object for structured output |
| `--output-schema-file <path>` | Path to a JSON file containing the output schema |
| `--browser-profile <profile>` | Browser profile for execution (`lite` or `stealth`) |
| `--max-steps <n>` | Maximum tool-call steps before stopping (`1`-`500`) |
| `--mode <mode>` | Agent behavior mode (`default` or `strict`). `strict` is in **beta** — join the beta to use it (contact support to enable it). |
| `--max-duration-seconds <n>` | Maximum wall-clock seconds before stopping |
| `--cursor-style <style>` | Cursor style in the recording (`fish`, `standard`, or `green-pointer`) |
| `--capture-screenshots` / `--no-capture-screenshots` | Capture screenshots (on by default) |
| `--capture-snapshots` | Capture page snapshots |
| `--capture-html` | Capture HTML snapshots |
| `--capture-elements` | Capture page element metadata. Gated capability — returns `403` if not enabled for your account. |
| `--capture-recording` | Capture a browser recording. Gated capability — returns `403` if not enabled for your account. |
| `--webhook-url <url>` | HTTPS URL notified on run lifecycle events. Must use HTTPS. |
| `--use-profile` | Start from your default Browser Context Profile |
| `--profile-id <id>` | Start from a specific Browser Context Profile. Requires `--use-profile`. |
| `--session-id <uuid>` | Caller-provided UUID for idempotency / parallel-safe `--sync` |
| `--use-vault` | Inject vault credentials into the run. Requires a connected vault provider. |
| `--credential-item-id <id>` | Scope the run to a specific credential item by `itemId` (repeat for multiple; from `tinyfish vault item list`). Requires `--use-vault`. Omit to use all enabled items. |
| `--pretty` | Human-readable output instead of JSON |

### Output modes

<Tabs>
  <Tab title="Streaming (default)">
    One JSON object per line as events arrive. Use this when you want live progress or are piping to another tool.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing
    ```

    ```json theme={null}
    {"type":"STARTED","run_id":"abc123","timestamp":"2024-01-15T10:30:00Z"}
    {"type":"PROGRESS","run_id":"abc123","purpose":"Navigating to the pricing page","timestamp":"2024-01-15T10:30:02Z"}
    {"type":"COMPLETE","run_id":"abc123","status":"COMPLETED","result":{"result":"{\"price\":\"£99.00\"}"},"run_url":"https://agent.tinyfish.ai/runs/abc123"}
    ```

    <Note>
      The default stream also emits `STREAMING_URL` events (the live browser view) and periodic `HEARTBEAT` keep-alives.
    </Note>

    <Note>
      Pressing **Ctrl+C** during a streaming run cancels the run server-side before exiting.
    </Note>
  </Tab>

  <Tab title="Sync (--sync)">
    Waits for the run to finish and returns a single JSON object with the full result. Use this for scripts where you only care about the final output.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing --sync
    ```

    ```json theme={null}
    {"run_id":"abc123","run_url":"https://agent.tinyfish.ai/runs/abc123","status":"COMPLETED","result":{"price":"$99"},"num_of_steps":4}
    ```
  </Tab>

  <Tab title="Async (--async)">
    Submits the run and returns immediately with the `run_id`. Use this when you want to fire-and-forget or manage polling yourself.

    ```bash theme={null}
    tinyfish agent run "Extract the pricing" --url example.com/pricing --async
    ```

    ```json theme={null}
    {"run_id":"abc123","error":null,"status":"PENDING","run_url":"https://agent.tinyfish.ai/runs/abc123"}
    ```
  </Tab>
</Tabs>

***

## `tinyfish agent run list`

List recent runs.

```bash theme={null}
tinyfish agent run list
```

### Flags

| Flag | Description |
| - | - |
| `--status <status>` | Filter by status: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, or `CANCELLED` |
| `--limit <n>` | Number of runs to return (default `20`, max `100`) |
| `--cursor <cursor>` | Pagination cursor from a previous response |
| `--pretty` | Human-readable output |

### Examples

<CodeGroup>
  ```bash List all runs theme={null}
  tinyfish agent run list
  ```

  ```bash Filter by status theme={null}
  tinyfish agent run list --status COMPLETED
  ```

  ```bash Paginate theme={null}
  tinyfish agent run list --limit 50 --cursor <cursor_from_previous_response>
  ```

  ```bash Human-readable theme={null}
  tinyfish agent run list --pretty
  ```
</CodeGroup>

***

## `tinyfish agent run get <run_id>`

Get the full details of a specific run.

```bash theme={null}
tinyfish agent run get abc123
```

Returns the complete run object including status, result, and metadata.

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Example

<CodeGroup>
  ```bash JSON output theme={null}
  tinyfish agent run get abc123
  ```

  ```bash Human-readable theme={null}
  tinyfish agent run get abc123 --pretty
  ```
</CodeGroup>

***

## `tinyfish agent run steps <run_id>`

Print the step-by-step trace for a run.

```bash theme={null}
tinyfish agent run steps abc123
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

***

## `tinyfish agent run watch <run_id>`

Poll a run and print new steps as they arrive. Exits when the run reaches a terminal status.

```bash theme={null}
tinyfish agent run watch abc123
```

### Flags

| Flag | Description |
| - | - |
| `--timeout <ms>` | Stop polling after this many milliseconds (default `1800000`) |
| `--interval <ms>` | Poll interval (default `3000`, min `500`) |
| `--pretty` | Human-readable output |

***

## `tinyfish agent run cancel <run_id>`

Cancel a run that is `PENDING` or `RUNNING`.

```bash theme={null}
tinyfish agent run cancel abc123
```

```json theme={null}
{"run_id":"abc123","status":"CANCELLED","cancelled_at":"2024-01-15T10:30:00Z","message":null}
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

***

## `tinyfish agent batch run`

Submit a batch of runs from a CSV file. The CSV must have `url` and `goal` columns.

```bash theme={null}
tinyfish agent batch run --input runs.csv
```

### CSV format

```csv theme={null}
url,goal
https://example.com,"Extract the main heading"
https://another.com,"Get the price and availability"
```

### Flags

| Flag | Description |
| - | - |
| `--input <file>` | Path to CSV file (required) |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "data": {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "total": 2,
    "submitted": 2,
    "results_url": "https://agent.tinyfish.ai/runs"
  }
}
```

<Note>
  Batches are tracked locally in `~/.tinyfish/batches.json`. Use `batch list` and `batch get` to check progress.
</Note>

***

## `tinyfish agent batch list`

List all locally tracked batches.

```bash theme={null}
tinyfish agent batch list
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
[
  {
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "run_ids": ["run-1", "run-2"],
    "total": 2,
    "submitted": 2,
    "created_at": "2026-04-10T10:30:00Z"
  }
]
```

***

## `tinyfish agent batch get <batch_id>`

Get run results for a batch, including per-run status and extracted data.

```bash theme={null}
tinyfish agent batch get 550e8400-e29b-41d4-a716-446655440000
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "batch_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": [
    {
      "run_id": "run-1",
      "status": "COMPLETED",
      "goal": "Extract the main heading",
      "num_of_steps": 5,
      "result": { "heading": "Welcome" }
    }
  ],
  "not_found": null
}
```

***

## `tinyfish agent batch cancel <batch_id>`

Cancel all runs in a batch.

```bash theme={null}
tinyfish agent batch cancel 550e8400-e29b-41d4-a716-446655440000
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "results": [
    {
      "run_id": "run-1",
      "status": "CANCELLED",
      "cancelled_at": "2026-04-10T10:35:00Z",
      "message": null
    }
  ],
  "not_found": null
}
```

***

## `tinyfish browser session create`

Spin up a remote browser instance. Returns a CDP (Chrome DevTools Protocol) WebSocket URL for programmatic control.

```bash theme={null}
tinyfish browser session create
```

### Flags

| Flag | Description |
| - | - |
| `--url <url>` | Navigate to a URL after session creation |
| `--proxy-country <code>` | Exit country for the TinyFish proxy (ISO 3166-1 alpha-2, e.g. `DE`). Defaults to `US` |
| `--proxy-url <url>` | Route through your own HTTP(S) proxy. Set the password in `TINYFISH_PROXY_PASSWORD` |
| `--proxy-username <user>` | Username for `--proxy-url` |
| `--no-proxy` | Connect directly, without a proxy |
| `--pretty` | Human-readable output |

By default, sessions use the TinyFish proxy in the US and keep the same exit IP for the whole session. `--proxy-country` and `--proxy-url` can't be combined, and `--no-proxy` can't be combined with any other `--proxy-*` flag. See [Proxies](/browser-api#proxies).

### Output

```json theme={null}
{
  "session_id": "tf-9c669a12-a0d3-456e-8126-6524c32f10fc",
  "cdp_url": "wss://ip-13-56-193-1.tetra-data.production.tinyfish.io/tf-9c669a12-a0d3-456e-8126-6524c32f10fc",
  "base_url": "https://ip-13-56-193-1.tetra-data.production.tinyfish.io/tf-9c669a12-a0d3-456e-8126-6524c32f10fc"
}
```

<Note>
  Use the `cdp_url` to connect with Playwright, Puppeteer, or any CDP-compatible client. The `base_url` can be used for HTTP-based interactions with the session.
</Note>

### Examples

<CodeGroup>
  ```bash Create a blank session theme={null}
  tinyfish browser session create
  ```

  ```bash Create and navigate to a URL theme={null}
  tinyfish browser session create --url "https://example.com"
  ```

  ```bash Exit from Germany theme={null}
  tinyfish browser session create --url "https://example.de" --proxy-country DE
  ```

  ```bash Your own proxy theme={null}
  TINYFISH_PROXY_PASSWORD=secret tinyfish browser session create \
    --proxy-url "http://proxy.example.com:8080" --proxy-username user
  ```

  ```bash No proxy theme={null}
  tinyfish browser session create --no-proxy
  ```

  ```bash Human-readable theme={null}
  tinyfish browser session create --pretty
  ```
</CodeGroup>

***

## `tinyfish browser session list`

List your browser sessions. Running sessions include `cdp_url` and `base_url`.

```bash theme={null}
tinyfish browser session list [--status running|ended] [--session-id <id>]
```

### Flags

| Flag | Description |
| - | - |
| `--session-id <id>` | Only this session |
| `--start-after <iso>` | Only items created after this ISO 8601 timestamp |
| `--end-before <iso>` | Only items created before this ISO 8601 timestamp |
| `--status <status>` | Filter by status (running\|ended) |
| `--limit <n>` | Items per page, 1-1000 (default 100) |
| `--page <n>` | Page number, starting from 1 |
| `--pretty` | One line per item, then the page count |

JSON output is the paged response: `{ "items": [...], "total", "limit", "page", "total_pages", "has_more" }`.

## `tinyfish browser session close <session_id>`

Close a browser session. A session bills until it is closed or hits its inactivity timeout, so close it when you are done. Closing an ended session succeeds.

```bash theme={null}
tinyfish browser session close <session_id>
# {"session_id":"<session_id>","status":"closed"}
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

## `tinyfish profile create`

Create a Browser Context Profile and get a link where the user signs in to it. The link opens a TinyFish page with a live browser and a **Save profile** button, so nothing else needs to run after the user saves. At a terminal, the CLI opens the link for you.

```bash theme={null}
tinyfish profile create --name "my-github" --site github.com
```

If you are an agent: give the user `setup_url`, never ask for their password, and confirm the save with `tinyfish profile list`. Then run with `tinyfish agent run --use-profile --profile-id <id>`.

### Flags

| Flag | Description |
| - | - |
| `--name <name>` | Profile name (required) |
| `--site <site>` | Site to sign in to, such as `github.com`. A URL also works; only its hostname is used |
| `--proxy-country <code>` | Exit country for sign-in and every run on this profile: `US`, `GB`, `CA`, `AU`, `DE`, `FR`, `IT`, `ES`, `NL`, `JP`, `SG`, `BR`, or `IN`. Without it, runs on this profile use no proxy |
| `--import-cookies` | Import cookies from your local Chrome instead of signing in through the link. Needs `--domain` or `--all-domains` |
| `--domain`, `--all-domains`, `--chrome-profile` | Cookie import scope, as in `profile import-cookies` |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "id": "prof_abc123",
  "name": "my-github",
  "created_at": "2026-10-08 21:00:00",
  "setup_url": "https://agent.tinyfish.ai/profiles/prof_abc123/setup?domain=github.com&source=cli",
  "next_step": "Give the user setup_url. ..."
}
```

The link opens in the TinyFish dashboard, so the user signs in to TinyFish first if they are not already. No browser session starts, and nothing is billed, until they open it.

### Examples

<CodeGroup>
  ```bash Sign in through a link theme={null}
  tinyfish profile create --name "my-github" --site github.com
  ```

  ```bash Import cookies from Chrome theme={null}
  tinyfish profile create --name "my-github" --import-cookies --domain github.com
  ```
</CodeGroup>

***

## `tinyfish profile import-cookies`

Extract cookies from your local Chrome install and upload them to a profile. This lets TinyFish reuse your existing logged-in session without you having to log in again during a run.

Use `--domain` to import cookies for a single site, or `--all-domains` to import every domain in your Chrome profile in one shot. Exactly one of these flags must be provided — they are mutually exclusive. The CLI uses Chrome's last-used profile by default, or `Default` if you have never switched Chrome profiles; pass `--chrome-profile` to select another profile directory explicitly. If the profile can't be found, the error lists the profile directories that have cookies.

```bash theme={null}
tinyfish profile import-cookies --domain github.com
```

<Note>
  Supported on macOS and Linux. Requires Google Chrome to be installed.
</Note>

### Flags

| Flag | Description |
| - | - |
| `--domain <domain>` | Domain to import cookies for, e.g. `github.com`. Mutually exclusive with `--all-domains`. |
| `--all-domains` | Import cookies for every domain in your Chrome profile. Mutually exclusive with `--domain`. |
| `--chrome-profile <name>` | Chrome profile directory, e.g. `Profile 1`. Defaults to Chrome's last-used profile, or `Default`. |
| `--profile-id <id>` | Profile to import into. If omitted, a new profile is created automatically. |
| `--pretty` | Human-readable output |

### Output

```json theme={null}
{
  "profile_id": "profile_abc123",
  "cookie_count": 15,
  "domains_updated": ["github.com"]
}
```

### Examples

<CodeGroup>
  ```bash Create profile + import in one step theme={null}
  tinyfish profile import-cookies --domain github.com
  ```

  ```bash Import into an existing profile theme={null}
  tinyfish profile import-cookies --domain github.com --profile-id profile_abc123
  ```

  ```bash Import all domains theme={null}
  tinyfish profile import-cookies --all-domains
  ```

  ```bash Human-readable theme={null}
  tinyfish profile import-cookies --domain github.com --pretty
  ```

  ```bash Select a Chrome profile theme={null}
  tinyfish profile import-cookies --domain github.com --chrome-profile "Profile 1"
  ```
</CodeGroup>

After importing, pass the profile ID to `tinyfish agent run` via `--use-profile` or include `use_profile: true` + `profile_id` in your API request to reuse the session.

<Tip>
  See [Browser Context Profiles](/key-concepts/browser-context-profiles) for the full workflow.
</Tip>

***

## `tinyfish profile list`

List your browser profiles. Where available, each profile lists the sites it is signed in to under `signed_in_sites`.

```bash theme={null}
tinyfish profile list [--pretty]
```

## `tinyfish profile update <profile_id>`

Rename a profile or change its proxy. Runs on a profile always use the profile's proxy setting, so keep it on the country you signed in from.

```bash theme={null}
tinyfish profile update <profile_id> --proxy-country GB
tinyfish profile update <profile_id> --no-proxy
```

### Flags

| Flag | Description |
| - | - |
| `--name <name>` | New profile name |
| `--proxy-country <code>` | Exit country, as in `profile create` |
| `--no-proxy` | Connect directly, without a proxy |
| `--pretty` | Human-readable output |

## `tinyfish profile sign-in <profile_id>`

Get a sign-in link for an existing profile, to add a site or refresh an expired sign-in. Same output and `--site` flag as `profile create`.

```bash theme={null}
tinyfish profile sign-in <profile_id> --site accounts.google.com
```

## `tinyfish vault connection add`

Connect a credential provider (1Password or Bitwarden). Credentials are validated immediately — if they're invalid, the command fails. Provider secrets are read from environment variables, never passed as flags, so they stay out of shell history.

```bash theme={null}
# 1Password — service account token from env
TINYFISH_VAULT_TOKEN=ops_... \
  tinyfish vault connection add --provider 1password

# Bitwarden — client secret + master password from env; client ID is a flag
TINYFISH_VAULT_CLIENT_SECRET=<secret> TINYFISH_VAULT_MASTER_PASSWORD=<password> \
  tinyfish vault connection add --provider bitwarden --client-id user.xxxx-xxxx
```

### Flags

| Flag | Description |
| - | - |
| `--provider <provider>` | `1password` or `bitwarden` (required) |
| `--client-id <id>` | Bitwarden client ID (required for Bitwarden; format `user.xxxx-xxxx`) |
| `--server-url <url>` | Self-hosted Bitwarden server URL |
| `--pretty` | Human-readable output |

### Environment variables

| Variable | Description |
| - | - |
| `TINYFISH_VAULT_TOKEN` | 1Password service account token (starts with `ops_`) |
| `TINYFISH_VAULT_CLIENT_SECRET` | Bitwarden client secret |
| `TINYFISH_VAULT_MASTER_PASSWORD` | Bitwarden master password |

***

## `tinyfish vault connection list`

List all connected vault providers and their status.

```bash theme={null}
tinyfish vault connection list
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

***

## `tinyfish vault connection remove <connectionId>`

Disconnect a provider. All cached credentials are removed immediately; runs already in progress are not affected.

```bash theme={null}
tinyfish vault connection remove a1b2c3d4-5678-90ab-cdef-1234567890ab
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

***

## `tinyfish vault item sync`

Pull the latest credentials from all connected providers. Run this after adding new credentials or changing passwords in your vault.

```bash theme={null}
tinyfish vault item sync
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

***

## `tinyfish vault item list`

List all synced credential items. Each item has an `itemId` — that's what you pass to `--credential-item-id` on `agent run`.

```bash theme={null}
tinyfish vault item list
```

```json theme={null}
{
  "items": [
    {
      "itemId": "cred:conn-123:Personal:item-abc123",
      "label": "GitHub Login",
      "vaultName": "Personal",
      "domains": ["github.com"],
      "hasTotp": false,
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
  ]
}
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Examples

<CodeGroup>
  ```bash Full vault setup + run theme={null}
  # 1. Connect (one-time)
  TINYFISH_VAULT_TOKEN=ops_... tinyfish vault connection add --provider 1password

  # 2. List items (sync first if the list is empty)
  tinyfish vault item sync
  tinyfish vault item list --pretty

  # 3. Run with credentials
  tinyfish agent run "Log in and export the invoices" \
    --url https://example.com \
    --use-vault \
    --credential-item-id cred:conn-123:Personal:item-abc123
  ```

  ```bash Use all enabled items theme={null}
  tinyfish agent run "Check my dashboard" --url https://example.com --use-vault
  ```
</CodeGroup>

<Tip>
  See [Vault & Credentials](/vault-setup) for provider setup instructions and troubleshooting.
</Tip>

***

## `tinyfish monitor create`

Create a recurring monitor and run its baseline immediately. `--query` makes a search monitor; `--url` makes a fetch monitor. Pass exactly one. Each completed run, including the baseline, is billed to your wallet.

```bash theme={null}
tinyfish monitor create --query "tinyfish funding news" --schedule "0 */6 * * *"
tinyfish monitor create --url https://example.com/pricing --schedule "0 9 * * *" --format markdown
```

### Flags

| Flag | Description |
| - | - |
| `--query <query>` | Search monitor: the query to watch |
| `--url <url>` | Fetch monitor: the page to watch |
| `--schedule <cron>` | **Required.** 5-field cron, UTC unless prefixed `CRON_TZ=<zone> `. Search monitors run at most every 30 minutes |
| `--name <name>` | Monitor name |
| `--webhook-url <url>` | POST each run result to this URL |
| `--purpose <text>` | Why you are monitoring this |
| `--recency-minutes <n>` | Search: only results this recent |
| `--result-limit <n>` | Search: results per run, 1-10 (default 10) |
| `--format <format>` | Fetch: `markdown`, `html`, or `json` (default `json`) |
| `--links` | Fetch: include extracted links |
| `--image-links` | Fetch: include extracted image links |
| `--pretty` | Human-readable output |

Output is `{ "monitor": {...}, "run": {...} }`, where `run` is the baseline result.

## `tinyfish monitor list`

List your monitors.

```bash theme={null}
tinyfish monitor list [--pretty]
```

## `tinyfish monitor get|pause|resume|run|cancel <monitor_id>`

| Command | What it does | Output |
| - | - | - |
| `get` | Show a monitor | The monitor |
| `pause` | Pause its schedule | The updated monitor |
| `resume` | Resume a paused monitor | The updated monitor |
| `run` | Run it now (billed) | `{ "run": {...} }` |
| `cancel` | Delete the monitor and its schedule | `{ "deleted": true, "id": "..." }` |

Each takes `--pretty` for human-readable output.

## `tinyfish wallet status`

Show wallet balance, auto-reload, pending top-up, and rates.

```bash theme={null}
tinyfish wallet status
```

### Flags

| Flag | Description |
| - | - |
| `--pretty` | Human-readable output |

### Output

<Tabs>
  <Tab title="JSON (default)">
    ```json theme={null}
    {
      "available_balance": "21.44",
      "currency": "USD",
      "as_of": "2026-08-10T18:04:11.220Z",
      "auto_reload": { "state": "unconfigured" },
      "pending_top_up": null,
      "rates": {
        "meters": [
          { "label": "Agent steps", "unit_amount": "0.016000", "currency": "USD", "per": "step" }
        ],
        "as_of": "2026-08-10T18:04:11.220Z"
      }
    }
    ```
  </Tab>

  <Tab title="Pretty (--pretty)">
    ```
    Balance: 21.44 USD
    Auto-reload: unconfigured
    Pending top-up: none
    Agent steps: 0.016000 USD/step
    ```

    <Note>
      `auto_reload` prints `unavailable` when the read failed, or `on`/`off`/`paused_payment_failed`/`needs_payment_method` with the threshold and recharge-to amount when configured. `rates` prints `unavailable` when the read failed, or `none` when the wallet has no rate contract yet.
    </Note>
  </Tab>
</Tabs>

### Examples

<CodeGroup>
  ```bash JSON output theme={null}
  tinyfish wallet status
  ```

  ```bash Human-readable theme={null}
  tinyfish wallet status --pretty
  ```
</CodeGroup>

### Errors

Accounts are on either wallet billing or a legacy subscription/credits plan — `wallet status` only works for the former. A wallet account that hasn't added money yet isn't an error: it reads as a zero balance. Errors print to stderr as `{"error": "<message>", "status": <status>}`:

| `status` | `error` message | Meaning |
| - | - | - |
| 404 | `Wallet is not available for your account yet.` | Account isn't wallet-enabled — it's on the legacy subscription/credits plan instead. |

Anything else is an unexpected server error (`status` 500). Retry, and contact support if it persists.

See [Error Codes](/error-codes) for the full reference, including each response's machine-readable `error.code` (the CLI's JSON output above only surfaces `status` and `error`, not `code`).

***

## Auth commands

| Command | Description |
| - | - |
| `tinyfish auth login` | Open the API keys page and save a key interactively |
| `tinyfish auth set` | Read an API key from stdin and save it |
| `tinyfish auth status` | Check whether a key is configured and where it comes from |
| `tinyfish auth logout` | Remove the saved API key |

***

## `tinyfish doctor`

Diagnose your TinyFish setup: which agent harnesses are installed, whether each is registered against TinyFish, and whether your API key works.

```bash theme={null}
tinyfish doctor --pretty
```

### Flags

| Flag | Description |
| - | - |
| `--harness <name>` | Restrict the run to one harness instead of every installed one |
| `--fix` | Repair what can be repaired by re-running `tinyfish connect` |
| `--yes` | Allow `--fix` to run without a terminal (unattended-safe repairs only) |
| `--url <mcpUrl>` | MCP endpoint override |
| `--pretty` | Human-readable check list instead of JSON |

### Exit codes

Unlike other commands, `doctor` distinguishes its failures by exit code, so a script can tell a broken setup from a broken invocation.

| Code | Meaning |
| - | - |
| `0` | Healthy: every applicable check passed |
| `1` | A harness check failed |
| `2` | Doctor could not run |
| `3` | Invalid invocation, such as an unknown `--harness` value |

Exit 3 prints the accepted values alongside the rejected one:

```bash theme={null}
tinyfish doctor --harness claude
# {"error":"Unknown --harness value: claude","valid":["claude-code","codex","command-code","cursor","grok","hermes","kilo","omp","openclaw","opencode","pi"]}
```


# CLI
Source: https://docs.tinyfish.ai/cli/index

Run TinyFish automations directly from your terminal

The TinyFish CLI lets you run browser automations, check results, and manage runs from your terminal — no code required.

## Installation

```bash theme={null}
npm install -g @tiny-fish/cli@latest
```

**Verify:**

```bash theme={null}
tinyfish --version
```

## Authentication

```bash theme={null}
tinyfish auth login
```

Opens the API keys page in your browser. Paste your key when prompted. The key is saved to `~/.tinyfish/config.json`.

**For CI/CD:**

```bash theme={null}
echo $TINYFISH_API_KEY | tinyfish auth set
```

**Check status:**

```bash theme={null}
tinyfish auth status
```

Returns JSON with `source` (`env`, `config`, or `none`), `key_preview` (first/last chars of the key, or `null`), and `authenticated` (`true`/`false`). Exit code 1 when not authenticated.

## Quick Start

```bash theme={null}
npm install -g @tiny-fish/cli@latest
export TINYFISH_API_KEY="sk-tinyfish-..."
tinyfish agent run --url "https://example.com" "Extract product data. Return JSON."
```

## Environment variables

| Variable | Description |
| - | - |
| `TINYFISH_API_KEY` | API key — takes priority over saved config |
| `TINYFISH_VAULT_TOKEN` | 1Password service account token for `vault connection add` |
| `TINYFISH_VAULT_CLIENT_SECRET` | Bitwarden client secret for `vault connection add` |
| `TINYFISH_VAULT_MASTER_PASSWORD` | Bitwarden master password for `vault connection add` |
| `TINYFISH_DEBUG` | Set to `1` to enable debug output |
| `TINYFISH_NO_TELEMETRY` | Set to any value other than `0`/`false` to disable all CLI-emitted analytics and update checks |

## Output

By default all commands output JSON to stdout. Errors go to stderr as JSON. Exit code 1 on failure, except `tinyfish doctor`, which has [its own exit codes](/cli/commands#tinyfish-doctor).

Add `--pretty` to any command for human-readable output.


# Common Patterns
Source: https://docs.tinyfish.ai/common-patterns

Ready-to-use code patterns for common TinyFish Web Agent use cases

These patterns cover the most common ways to integrate TinyFish Web Agent into your application.

## Simple Extraction

Use the synchronous endpoint for quick, one-off extractions where you need the result immediately.

```typescript theme={null}
import { TinyFish, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();

async function extractData(url: string, dataDescription: string) {
  const run = await client.agent.run({
    url,
    goal: `Extract ${dataDescription}. Return as JSON.`,
  });

  return run.status === RunStatus.COMPLETED ? run.result : null;
}

// Usage
async function main() {
  const products = await extractData(
    "https://example.com/products",
    "all product names and prices"
  );
  console.log(products);
}

main();
```

***

## Batch Processing

For multiple URLs, use the async endpoint to submit all tasks at once, then poll for results. This avoids blocking while waiting for each task to complete.

```typescript theme={null}
import { TinyFish, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();

async function processBatch(tasks: { url: string; goal: string }[]) {
  // Submit all tasks
  const responses = await Promise.all(
    tasks.map((task) => client.agent.queue(task))
  );

  // Poll for completion
  const maxAttempts = 150; // 5 minutes at 2s intervals
  const results = await Promise.all(
    responses.map(async (r) => {
      if (r.error) {
        throw r.error;
      }
      for (let attempt = 0; attempt < maxAttempts; attempt++) {
        const run = await client.runs.get(r.run_id);
        if (
          run.status === RunStatus.COMPLETED ||
          run.status === RunStatus.FAILED ||
          run.status === RunStatus.CANCELLED
        ) {
          return run;
        }
        await new Promise((resolve) => setTimeout(resolve, 2000));
      }
      throw new Error(`Run ${r.run_id} timed out after ${maxAttempts} attempts`);
    })
  );

  return results;
}

// Usage
async function main() {
  const results = await processBatch([
    { url: "https://example.com/page1", goal: "Extract product info" },
    { url: "https://example.com/page2", goal: "Extract product info" },
  ]);
  console.log(results);
}

main();
```

***

## Retry with Stealth Mode

Some sites block automated requests. Start with lite mode for speed, then automatically retry with stealth mode if you get blocked.

```typescript theme={null}
import { TinyFish, RunStatus, BrowserProfile, ProxyCountryCode } from "@tiny-fish/sdk";

const client = new TinyFish();

async function extractWithFallback(url: string, goal: string) {
  // Try standard mode first
  let result = await client.agent.run({
    url,
    goal,
    browser_profile: BrowserProfile.LITE,
  });

  if (result.status === RunStatus.FAILED && result.error?.message.includes("blocked")) {
    // Retry with stealth mode
    result = await client.agent.run({
      url,
      goal,
      browser_profile: BrowserProfile.STEALTH,
      proxy_config: { enabled: true, country_code: ProxyCountryCode.US },
    });
  }

  return result;
}
```

***

## Result Validation

A run with `COMPLETED` status means the agent finished, but the result may still describe a failure (e.g., the site showed a captcha or access-denied page). Always validate the result content.

<CodeGroup>
  ```python Python theme={null}
  def is_real_success(result):
      """COMPLETED status is necessary but not sufficient."""
      if not result:
          return False
      result_str = str(result).lower()
      failure_signals = ["captcha", "blocked", "access denied", "could not", "unable to"]
      return not any(signal in result_str for signal in failure_signals)

  # Usage
  from tinyfish import TinyFish, RunStatus

  client = TinyFish()
  run = client.agent.run(
      url="https://example.com",
      goal="Extract pricing data. Return as JSON.",
  )
  if run.status == RunStatus.COMPLETED and is_real_success(run.result):
      print("Success:", run.result)
  else:
      print("Needs retry or manual review")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, RunStatus } from "@tiny-fish/sdk";

  function isRealSuccess(result: unknown): boolean {
    if (!result) return false;
    let resultStr: string;
    try {
      resultStr = JSON.stringify(result).toLowerCase();
    } catch {
      resultStr = String(result).toLowerCase();
    }
    const failureSignals = ["captcha", "blocked", "access denied", "could not", "unable to"];
    return !failureSignals.some((signal) => resultStr.includes(signal));
  }

  // Usage
  async function main() {
    const client = new TinyFish();
    const run = await client.agent.run({
      url: "https://example.com",
      goal: "Extract pricing data. Return as JSON.",
    });

    if (run.status === RunStatus.COMPLETED && isRealSuccess(run.result)) {
      console.log("Success:", run.result);
    } else {
      console.log("Needs retry or manual review");
    }
  }

  main();
  ```
</CodeGroup>

***

## Rate Limit Handling

TinyFish enforces per-account concurrency limits. The SDK automatically retries `429` and `5xx` errors with exponential backoff (up to `maxRetries` attempts, default 2).

```typescript theme={null}
import { TinyFish, RateLimitError } from "@tiny-fish/sdk";

// Adjust retry behavior via client options
const client = new TinyFish({
  maxRetries: 3,  // default is 2
});

async function main() {
  try {
    const run = await client.agent.run({
      url: "https://example.com",
      goal: "Extract data",
    });
    console.log(run.result);
  } catch (e) {
    if (e instanceof RateLimitError) {
      console.log("Rate limited after all retries exhausted");
    }
    throw e;
  }
}

main();
```

***

## Authenticated Automation

Use vault credentials to automate sites that require login. Connect your password manager once via the [vault setup](/vault-setup), then pass credentials to each run.

<CodeGroup>
  ```bash cURL theme={null}
  # Use all vault credentials
  curl -X POST https://agent.tinyfish.ai/v1/automation/run \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.linkedin.com",
      "goal": "Log in and extract the latest 3 posts from my feed. Return as JSON.",
      "use_vault": true
    }'

  # Scope to a specific credential
  curl -X POST https://agent.tinyfish.ai/v1/automation/run \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.linkedin.com",
      "goal": "Log in and extract the latest 3 posts from my feed. Return as JSON.",
      "use_vault": true,
      "credential_item_ids": ["cred:conn-abc:Work:item-linkedin"]
    }'
  ```

  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  # Use all vault credentials
  result = client.agent.run(
      url="https://www.linkedin.com",
      goal="Log in and extract the latest 3 posts from my feed. Return as JSON.",
      use_vault=True,
  )
  print(result.result)

  # Scope to a specific credential
  result = client.agent.run(
      url="https://www.linkedin.com",
      goal="Log in and extract the latest 3 posts from my feed. Return as JSON.",
      use_vault=True,
      credential_item_ids=["cred:conn-abc:Work:item-linkedin"],
  )
  print(result.result)
  ```
</CodeGroup>

<Tip>
  Use `credential_item_ids` to scope runs to specific credentials when you have multiple accounts on the same domain. See [Vault Credentials](/key-concepts/credentials) for details.
</Tip>

***

## Cross-API Workflows

Chain multiple TinyFish APIs together for complex workflows.

### Search + Fetch

Search for URLs, then fetch full content from the top results:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  # Step 1: Search for relevant pages
  search_results = client.search.query("best python web frameworks 2026")

  # Step 2: Fetch content from top 3 results
  urls = [r.url for r in search_results.results[:3]]
  fetched = client.fetch.get_contents(urls=urls, format="markdown")

  for page in fetched.results:
      print(f"{page.title}: {page.text[:200]}...")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  // Step 1: Search for relevant pages
  const searchResults = await client.search.query({
    query: "best python web frameworks 2026",
  });

  // Step 2: Fetch content from top 3 results
  const urls = searchResults.results.slice(0, 3).map((r) => r.url);
  const fetched = await client.fetch.getContents({ urls, format: "markdown" });

  fetched.results.forEach((page) =>
    console.log(`${page.title}: ${page.text.slice(0, 200)}...`)
  );
  ```
</CodeGroup>

### Search + Agent

Search for a URL, then extract structured data via the Agent API:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish, RunStatus

  client = TinyFish()

  # Step 1: Find a product page
  search_results = client.search.query("scrapeme pokemon shop bulbasaur")
  target_url = search_results.results[0].url

  # Step 2: Extract structured data with the Agent
  run = client.agent.run(
      url=target_url,
      goal="""Extract from this product page:
      - product_name, price (number), in_stock (boolean)
      Return as JSON.""",
  )

  if run.status == RunStatus.COMPLETED:
      print(run.result)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, RunStatus } from "@tiny-fish/sdk";

  const client = new TinyFish();

  // Step 1: Find a product page
  const searchResults = await client.search.query({
    query: "scrapeme pokemon shop bulbasaur",
  });
  const targetUrl = searchResults.results[0].url;

  // Step 2: Extract structured data with the Agent
  const run = await client.agent.run({
    url: targetUrl,
    goal: `Extract from this product page:
      - product_name, price (number), in_stock (boolean)
      Return as JSON.`,
  });

  if (run.status === RunStatus.COMPLETED) {
    console.log(run.result);
  }
  ```
</CodeGroup>

***

## Related

<CardGroup>
  <Card title="AI Integration Guide" icon="robot" href="/ai-integration">
    Best practices for AI agents
  </Card>

  <Card title="Examples" icon="code" href="/examples/scraping">
    More detailed examples
  </Card>
</CardGroup>


# Error Codes
Source: https://docs.tinyfish.ai/error-codes

API error codes and how to resolve them

TinyFish surfaces errors in two layers, and you need to handle both:

1. **API-level errors** — returned as non-2xx HTTP responses (auth, validation, rate limits, server errors).
2. **Run-response error codes** — returned with HTTP **200** inside the `error` object of a run response (agent failures, infrastructure issues that map to a finished run, cancellations).

Knowing which layer you're looking at tells you whether the issue is with the request, your account, or the automation itself.

## Error Response Format

API-level errors contain an `error` object with a `code`, a `message`, and optional `details`. The shape of `details` depends on the error code:

```json theme={null}
// 400 Bad Request — may include validation details
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"url\": Invalid input: expected string, received undefined",
    "details": [
      {
        "expected": "string",
        "code": "invalid_type",
        "path": ["url"],
        "message": "Invalid input: expected string, received undefined"
      }
    ]
  }
}
```

```json theme={null}
// 401 invalid API key — no additional details
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key"
  }
}
```

```json theme={null}
// 401 vault reconnect required — affected provider IDs
{
  "error": {
    "code": "VAULT_RECONNECT_REQUIRED",
    "message": "1Password vault connection expired. Reconnect 1Password in Vault settings before starting a run with vault credentials.",
    "details": { "providers": ["1password"] }
  }
}
```

Most error bodies also carry a top-level `request_id` that matches the `X-Request-ID` response header. Include it when contacting support.

<Note>
  `details` is optional. For `INVALID_INPUT` (400), it can be an array of [Zod](https://zod.dev/) validation issues containing `code`, `path`, `message`, and issue-specific fields. For `VAULT_RECONNECT_REQUIRED` (401), it can be an object containing `providers`, an array of provider ID strings such as `1password` and `bitwarden`.
</Note>

`/v1/automation/run-batch` can return a per-run validation envelope; see [Batch Errors](#batch-errors). Vault reconnect failures before enqueueing use the top-level error shape shown above.

## API-level Error Codes

### MISSING\_API\_KEY

**HTTP Status:** 401

The `X-API-Key` header was not included in the request.

```json theme={null}
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "X-API-Key header is required"
  }
}
```

**Solution:** Add the `X-API-Key` header to your request:

```bash theme={null}
curl -H "X-API-Key: ***" ...
```

***

### INVALID\_API\_KEY

**HTTP Status:** 401

The provided API key does not exist or has been revoked.

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key"
  }
}
```

**Solutions:**

1. Verify your API key is correct (no extra whitespace)
2. Check if the key was deleted in the [API Keys dashboard](https://agent.tinyfish.ai/api-keys)
3. Generate a new key if needed

***

### UNAUTHORIZED

**HTTP Status:** 401

Authentication failed for a reason other than missing/invalid key. For example, required user context may be missing. Expired vault credentials use `VAULT_RECONNECT_REQUIRED`.

```json theme={null}
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication failed"
  }
}
```

**Solutions:**

1. Check your account status at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)
2. For Vault-related calls, reconnect your vault under **Settings → Vault**
3. Try generating a new API key

***

### VAULT\_RECONNECT\_REQUIRED

**HTTP Status:** 401

A vault connection needs replacement credentials. Reconnect the affected provider from the Vault page, then retry the request. Vault-backed runs reject credentials already marked expired before enqueueing; other provider-scoped runs can remain usable.

The TypeScript and Python SDKs preserve `code = "VAULT_RECONNECT_REQUIRED"` on the authentication exception. Check this code to distinguish vault recovery from an invalid TinyFish API key. Responses may identify affected provider IDs in `error.details.providers`.

CLI users can reconnect with `tinyfish vault connection add --provider 1password` or `tinyfish vault connection add --provider bitwarden --client-id <client-id>`. Supply the replacement 1Password token through `TINYFISH_VAULT_TOKEN`, or Bitwarden secrets through `TINYFISH_VAULT_CLIENT_SECRET` and `TINYFISH_VAULT_MASTER_PASSWORD`, then retry. CLI guidance requires an updated CLI version.

***

### INVALID\_INPUT

**HTTP Status:** 400

The request body failed validation.

```json theme={null}
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "Field \"browser_profile\": Invalid option: expected one of \"lite\"|\"stealth\"",
    "details": [
      {
        "code": "invalid_value",
        "values": ["lite", "stealth"],
        "path": ["browser_profile"],
        "message": "Invalid option: expected one of \"lite\"|\"stealth\""
      }
    ]
  }
}
```

**Common Causes:**

* `url` is missing or not a valid URL (must include `https://`)
* `goal` is empty or missing
* `browser_profile` is not `"lite"` or `"stealth"`
* `proxy_config.country_code` is not a supported 2-letter code (US, GB, CA, DE, FR, JP, AU)
* `output_schema` is invalid JSON Schema
* Missing required query parameter (e.g. `query` on `/v1/search`)

**Solution:** Check the `details` field for specific validation errors. Each entry includes the failing field `path` and a human-readable `message`.

***

### FORBIDDEN

**HTTP Status:** 403

Authentication succeeded, but the request was rejected — usually because the account lacks an entitlement, capability, or remaining credits. The credit case applies to legacy credit/subscription accounts only; wallet accounts get [`INSUFFICIENT_CREDITS`](#insufficient-credits-wallet-accounts) at 402 instead.

```json theme={null}
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient credits. You have 0 credits remaining. Requested 1 runs. Add credits at https://..."
  }
}
```

**Common Causes:**

* No remaining credits or expired subscription on a legacy credit/subscription account
* `proxy_config.type: "custom"` requested without the custom-proxy entitlement
* `output_schema` provided without the output-schema entitlement
* `capture_config` requests a capability the account isn't enabled for
* Attempting to access a resource you don't own

**Solution:** Check your account balance and subscription at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys), or contact support to enable a specific capability. The `message` field always specifies which entitlement or condition failed.

***

### INSUFFICIENT\_CREDITS (wallet accounts)

**HTTP Status:** 402

The account's TinyFish wallet balance is too low to start this run. This is a pre-flight check — the run is never created, and it is not retryable until money is added. Runs are never cut off mid-flight: a run already in progress finishes even if it takes the balance negative, and it's the next one that gets denied.

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
    "details": {
      "status": "failed",
      "error": "Run not started: the user's TinyFish wallet balance is too low ($-2.50). This is not retryable and will keep failing until money is added. Tell the user to add money at https://agent.tinyfish.ai/wallet (minimum top-up $10), then try again.",
      "reason": "wallet_out_of_funds",
      "non_retryable": true,
      "balance": "-2.50",
      "currency": "usd",
      "wallet_url": "https://agent.tinyfish.ai/wallet",
      "minimum_top_up": "10.00",
      "auto_reload_needs_payment_fix": false
    }
  }
}
```

**Common Causes:**

* Wallet balance is zero or negative
* Auto-reload is paused because the payment method on file was declined

`details` carries machine-readable fields (`balance`, `currency`, `wallet_url`, `minimum_top_up`, `auto_reload_needs_payment_fix`) so REST callers can act on the denial without parsing `message`. When [agent payments](/agent-payments) are available for the account and a top-up would unblock the request (`auto_reload_needs_payment_fix` is `false`), `details.agent_top_up_url` names the endpoint an agent can pay over MPP. `/v1/automation/run-batch` includes the same `details` object on its wallet-denial error slot.

**Solution:** Add money at [agent.tinyfish.ai/wallet](https://agent.tinyfish.ai/wallet) (minimum top-up \$10), or update the payment method if auto-reload is paused, then retry.

**Search and Fetch:** these return the same status and code when the daily free allowance (12,000 Search requests, 1,000 Fetch URLs; resets at 00:00 UTC) is used and the wallet balance is zero or below. Nothing is fetched or searched. The error carries only `code` and `message`:

```json theme={null}
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Daily free Search allowance used and your wallet balance is empty. Add funds at https://agent.tinyfish.ai/wallet?utm_source=api&utm_medium=insufficient_funds&utm_campaign=search"
  }
}
```

Add funds and retry after a few seconds, or wait for the allowance to reset.

***

### FREE\_ALLOWANCE\_EXHAUSTED (metered products)

**HTTP Status:** 402

The product's daily free allowance is used and the product does not charge your wallet — products in beta ship this way, so adding funds does not help. Nothing is fetched or searched. The allowance resets at 00:00 UTC.

```json theme={null}
{
  "error": {
    "code": "FREE_ALLOWANCE_EXHAUSTED",
    "message": "Daily free Search allowance used; it resets at 00:00 UTC."
  }
}
```

**Solution:** Retry after the daily reset.

***

### FEATURE\_NOT\_AVAILABLE

**HTTP Status:** 404

The account is not enabled for the requested feature. Currently emitted only by `GET /v1/wallet`, when the account is on legacy credit/subscription billing rather than a wallet — this is the discriminator for telling the two billing modes apart at request time.

```json theme={null}
{
  "error": {
    "code": "FEATURE_NOT_AVAILABLE",
    "message": "Wallet is not available for your account yet."
  }
}
```

**Solution:** The account isn't wallet-enabled. Use the legacy credits/subscription flow instead — check your account at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).

***

### NOT\_FOUND

**HTTP Status:** 404

The requested resource does not exist.

```json theme={null}
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Run with id 'a1b2c3d4-...' not found"
  }
}
```

**Common Causes:**

* Invalid `run_id` in `GET /v1/runs/:id`
* Vault connection not found
* Browser context profile not found
* Step HTML/screenshot not found (`GET /v1/runs/:id/steps/:stepId/...`)
* Run was deleted or never existed
* Run ID belongs to a different token scope — CLI/REST run IDs and MCP run IDs live in separate scopes, so a CLI lookup for an MCP-created run returns 404 by design

**Solution:** Verify the resource ID is correct. Run IDs are returned from `/v1/automation/run-async` or can be listed via `GET /v1/runs`.

***

### RETRY\_REQUIRED

**HTTP Status:** 409

A transient conflict prevented the request from completing. Currently emitted by Browser Context Profile setup endpoints (`/v1/profiles/:id/save`, `/v1/profiles/:id/setup-session`, `/v1/profiles/:id/setup-session/cancel`) when the setup session is in an intermediate state.

```json theme={null}
{
  "error": {
    "code": "RETRY_REQUIRED",
    "message": "Setup session is busy. Please retry in a moment."
  }
}
```

**Solution:** Wait briefly and retry. Use a short delay (1–2s) plus exponential backoff if the conflict persists.

***

### RATE\_LIMIT\_EXCEEDED

**HTTP Status:** 429

Too many requests in a short period.

```json theme={null}
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Limit: 30 requests per minute. Request a higher limit at https://agent.tinyfish.ai/wallet?utm_source=api&utm_medium=rate_limit_error&utm_campaign=search",
    "details": {
      "limit": 30,
      "unit": "requests",
      "window_seconds": 60,
      "upgrade_url": "https://agent.tinyfish.ai/wallet?utm_source=api&utm_medium=rate_limit_error&utm_campaign=search"
    }
  }
}
```

The `message` wording varies by endpoint. Read `details` instead of parsing it:

| Field | Values | Meaning |
| - | - | - |
| `details.limit` | integer | The ceiling that was hit |
| `details.unit` | `"requests"` or `"urls"` | What the limit counts (`urls` for Fetch, `requests` for Search) |
| `details.window_seconds` | integer | The window the limit applies over |
| `details.upgrade_url` | URL | Where to request a higher limit, routed to your billing page |

`details` is present when **your account's** per-minute limit rejected the call, which is the case this section describes. Two other conditions also return `RATE_LIMIT_EXCEEDED` and deliberately omit `details`, because no change to your plan would clear them:

* The upstream search or fetch provider throttled the request. Retry with backoff.
* The automation pending-run cap was hit. Wait for existing runs to finish.
* Too many usage reads or invalid requests (60 per minute combined). Invalid Search or Fetch requests count toward this limit even though each one returns 400. Fix the request, then retry with backoff.

Treat a missing `details` as "retry, do not upsell".

Rate limits depend on your account's limits and which API you're calling:

* `/v1/search` and `/v1/fetch` enforce per-minute request limits, applied per API key.
* `/v1/automation/run`, `/run-async`, and `/run-batch` enforce a pending-run cap tied to your account's concurrency limit.

See the [Search](/search-api/reference#rate-limits) and [Fetch](/fetch-api/reference#rate-limits) references for the specific numbers. To raise a limit, follow `details.upgrade_url` from the error body.

**Response headers:**

| Header | When set | Description |
| - | - | - |
| `Retry-After` | Search, Fetch (per-minute limits) | Suggested retry delay in seconds |
| `X-RateLimit-Limit` | Search, Fetch (200 and 429 responses) | Your current per-minute limit |
| `X-RateLimit-Remaining` | Search, Fetch (200 and 429 responses) | Requests (Search) or URLs (Fetch) left in the current window; `0` on a 429 |
| `X-RateLimit-Reset` | Search, Fetch (when the window is known) | Unix time in seconds when the current window resets |
| `X-Request-ID` | Search, Fetch | Request ID for support / observability |

<Note>
  The automation **pending-run cap** (429 from `/v1/automation/run`, `/run-async`, `/run-batch`) does **not** set `Retry-After` or `X-RateLimit-Limit` — wait for existing runs to finish and retry. The body message includes your current count and the maximum.
</Note>

**Solutions:**

1. Respect `Retry-After` when present, otherwise implement exponential backoff
2. Space out requests (recommended: 1-2 seconds between calls)
3. Use batch endpoints for high-volume workloads
4. Request a higher limit by following `details.upgrade_url` from the error body

**Example: Exponential Backoff**

```python theme={null}
import time
import random
from tinyfish import TinyFish, RateLimitError

client = TinyFish()

def call_with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except RateLimitError as exc:
            if attempt == max_retries - 1:
                raise
            # Prefer server hint when available
            retry_after = getattr(exc, "retry_after", None)
            wait = retry_after if retry_after else (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
```

***

### DAILY\_LIMIT\_EXCEEDED

**HTTP Status:** 429

The account reached its daily allowance for a capability. Research (`POST /v1/automation/run-research`) counts runs
started per Pacific calendar day, including runs still in progress. Runs that fail, time out, or are cancelled do not
count.

```json theme={null}
{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Today's Big Search limit has been reached. Please try again later.",
    "details": {
      "capability": "big_search_completion",
      "limit": 5,
      "used": 5,
      "remaining": 0,
      "reason": "exhausted",
      "window": "pacific_day",
      "resets_at": "2026-09-10T07:00:00.000Z"
    }
  }
}
```

| Field | Meaning |
| - | - |
| `details.capability` | Which allowance was exhausted |
| `details.limit` / `used` / `remaining` | The allowance and its consumption for the window |
| `details.window` | The window the allowance resets on (`pacific_day`) |
| `details.resets_at` | ISO 8601 timestamp when the allowance resets |

**Response headers:** `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` (Unix seconds).

**Solution:** Wait for `resets_at`, or contact support to raise the allowance. Unlike `RATE_LIMIT_EXCEEDED`, backoff
within the same day will not clear this error.

***

### INTERNAL\_ERROR

**HTTP Status:** 500

An unexpected error occurred on the server.

```json theme={null}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}
```

**Solutions:**

1. Retry the request after a brief delay
2. If the error persists, check [agent.tinyfish.ai/status](https://agent.tinyfish.ai/status) for outages
3. Contact support with your request details and timestamp (include `request_id` or `X-Request-ID` if you have it)

***

### BACKEND\_UNAVAILABLE

**HTTP Status:** 502, 503, or 504

The service handling the request was unreachable or timed out. An unavailable authentication or rate-limit store returns [`SERVICE_BUSY`](#service_busy) instead.

```json theme={null}
{
  "error": {
    "code": "BACKEND_UNAVAILABLE",
    "message": "Backend service timed out."
  },
  "request_id": "5f0c2b8e-…"
}
```

**Solution:** Retry with exponential backoff, honoring `Retry-After` when present. This is not caused by your request or your plan.

***

### UNKNOWN\_ROUTE

**HTTP Status:** 400 or 404

The request path does not match any API. Check the path against the API reference.

## Run-response Error Codes

Once a run is accepted, **completion-time failures** are reported inside the run response body — not as HTTP error codes. The HTTP response is **200**, and you inspect `status` + `error`:

```json theme={null}
{
  "run_id": "a1b2c3d4-...",
  "status": "FAILED",
  "result": null,
  "error": {
    "code": "SITE_BLOCKED",
    "message": "Target site blocked the automation. Try using stealth mode.",
    "category": "AGENT_FAILURE",
    "retry_after": null,
    "help_url": "https://docs.tinyfish.ai/key-concepts/browser-profiles#stealth",
    "help_message": "Getting blocked? Try enabling stealth mode."
  }
}
```

The `category` field gives you a quick branching key:

| Category | Meaning | Recommended action |
| - | - | - |
| `SYSTEM_FAILURE` | TinyFish-side issue (browser crash, capacity, infra timeout) | Retry the run |
| `AGENT_FAILURE` | The agent ran but couldn't achieve the goal (site blocked, content not found, auth required, etc.) | Refine input — change goal, enable stealth, attach a profile, etc. |
| `BILLING_FAILURE` | The run was rejected at the billing check before it started — wallet balance too low, or out of credits on a legacy account | Add money at [agent.tinyfish.ai/wallet](https://agent.tinyfish.ai/wallet) (minimum top-up \$10); legacy accounts add credits |
| `UNKNOWN` | Unclassified | Treat as retryable |

Optional fields:

* `retry_after` — suggested delay in seconds (`null` if not retryable)
* `help_url` — link to troubleshooting docs
* `help_message` — short human-readable guidance

### SERVICE\_BUSY

**Category:** `SYSTEM_FAILURE` · **In-body HTTP:** 200

The platform is temporarily out of capacity (browser pool exhausted, dependent service unavailable). Equivalent to a 503 if returned at the HTTP layer.

`/v1/search` and `/v1/fetch` return it as HTTP 503 when a backing store is down, including the rate-limit store.

**Solution:** Retry with exponential backoff.

### TIMEOUT

**Category:** `SYSTEM_FAILURE` · **In-body HTTP:** 200

An infrastructure or request timeout terminated the run. Equivalent to a 504.

**Solution:** Retry. If the goal is large/multi-step, consider splitting it or simplifying.

### BILLING\_REJECTED

**Category:** `BILLING_FAILURE` · **In-body HTTP:** 200

The run was rejected at the billing check before execution — the wallet balance was too low, or a legacy account was out of credits. The agent never started, so the run lands in a terminal `CANCELLED` status with no steps recorded. Runs are never cut off mid-flight: one already in progress finishes even if it takes the balance negative, and it's the next one that gets denied.

The same condition can also be caught earlier and reported at the HTTP layer, before the run record is created — [`INSUFFICIENT_CREDITS`](#insufficient-credits-wallet-accounts) at 402 for wallet accounts, [`FORBIDDEN`](#forbidden) at 403 for legacy credit/subscription accounts. Handle both.

**Solution:** Add money at [agent.tinyfish.ai/wallet](https://agent.tinyfish.ai/wallet) — minimum top-up \$10. Legacy accounts add credits at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys). Then retry.

### CONTENT\_POLICY\_VIOLATION

**Category:** `AGENT_FAILURE` · **In-body HTTP:** 200

The request — typically the goal text or a target URL — was blocked by content policy.

**Solution:** Adjust the goal or target. Contact support if you believe the block was a false positive.

### MAX\_STEPS\_EXCEEDED

**Category:** `AGENT_FAILURE` · **In-body HTTP:** 200

The automation hit the configured maximum step count without producing a result.

**Solution:** Simplify the goal, split it into multiple runs, or raise the step limit if your account's limits allow it.

### SITE\_BLOCKED

**Category:** `AGENT_FAILURE` · **In-body HTTP:** 200

The target site blocked the automation (anti-bot, CAPTCHA, IP block). The `status` field is still `FAILED`.

**Solution:** Switch `browser_profile` to `"stealth"`, attach a proxy via `proxy_config`, or use a Browser Context Profile with a warmed session. See the [anti-bot guide](/anti-bot-guide).

### TASK\_FAILED

**Category:** `AGENT_FAILURE` · **In-body HTTP:** 200

The agent ran but couldn't achieve the goal — navigation failed, content not found, authentication required, the result was incorrect, or the task wasn't achievable as described.

**Solution:** Make the goal more concrete (which page, which selector-equivalent description, which field). See the [prompting guide](/prompting-guide). For auth flows, use a vault credential or a saved profile.

### CANCELLED

**Category:** *N/A* · **Status:** `CANCELLED` · **In-body HTTP:** 200

The run was cancelled — either by you (`POST /v1/runs/:id/cancel`), by SDK cancellation, or because the async task lifecycle was terminated. Not an error in the usual sense.

**Solution:** No action needed unless the cancellation was unintended.

## Batch Errors

`/v1/automation/run-batch` validates the whole request first, then dispatches each child run. Batch-level failures (auth, missing capability, validation) follow the standard `{ "error": { "code", "message" } }` shape, with an optional `details` object on wallet-denial (`INSUFFICIENT_CREDITS`, 402) errors — see the example above. Per-run dispatch errors are returned inside the batch response under each run's slot. Treat the batch envelope as "did the batch get accepted?" and inspect each child for "did the individual run get scheduled?"

## Run Status vs Error Codes

<Note>
  HTTP error codes (the table below) indicate **request-level failures** — your request didn't make it to the agent. Run-response error codes indicate **completion-level outcomes** — the run reached the worker and reported back.

  For more on COMPLETED-but-failed runs, see [Understanding Run Status](/faq#what-does-completed-status-mean).
</Note>

## HTTP Status Code Summary

| Status | Meaning | Error codes returned |
| - | - | - |
| 200 | OK (run finished — may still carry a run-response error) | `SERVICE_BUSY`, `TIMEOUT`, `BILLING_REJECTED`, `CONTENT_POLICY_VIOLATION`, `MAX_STEPS_EXCEEDED`, `SITE_BLOCKED`, `TASK_FAILED`, `CANCELLED` (all inside the response body) |
| 400 | Bad Request | `INVALID_INPUT`, `UNKNOWN_ROUTE` |
| 401 | Unauthorized | `MISSING_API_KEY`, `INVALID_API_KEY`, `UNAUTHORIZED`, `VAULT_RECONNECT_REQUIRED` |
| 402 | Payment Required | `INSUFFICIENT_CREDITS` (wallet accounts, pre-flight), `FREE_ALLOWANCE_EXHAUSTED` (metered products that do not charge the wallet) |
| 403 | Forbidden | `FORBIDDEN` |
| 404 | Not Found | `NOT_FOUND`, `FEATURE_NOT_AVAILABLE` (`GET /v1/wallet`, legacy accounts), `UNKNOWN_ROUTE` |
| 409 | Conflict | `RETRY_REQUIRED` |
| 429 | Too Many Requests | `RATE_LIMIT_EXCEEDED`, `DAILY_LIMIT_EXCEEDED` |
| 500 | Server Error | `INTERNAL_ERROR` |
| 502, 504 | Bad Gateway, Gateway Timeout | `BACKEND_UNAVAILABLE` |
| 503 | Service Unavailable | `SERVICE_BUSY`, `BACKEND_UNAVAILABLE` |

## Related

<CardGroup>
  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>

  <Card title="FAQ" icon="circle-question" href="/faq">
    Common questions and issues
  </Card>
</CardGroup>


# Async Bulk Requests
Source: https://docs.tinyfish.ai/examples/bulk-requests-async

Submit multiple runs and poll for results

## Overview

The async API pattern is ideal when you want to submit multiple long-running tasks and check their status later. Instead
of waiting for each run to complete, you submit all requests and get back run IDs that you can poll for completion.

## How It Works

1. Submit requests to `/v1/automation/run-async`, which returns corresponding `run_id`s, which you will need if you want
   to check the status of a particular run.
2. Check individual runs with `GET /v1/runs/:id` to check status
3. Or fetch all runs with `GET /v1/runs` to monitor batch progress

## Basic Example

Submit multiple TinyFish Web Agent runs and poll for completion:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from tinyfish import AsyncTinyFish, RunStatus

  async def wait_for_completion(client, run_id, poll_interval=2):
      """Poll a run until it completes"""
      while True:
          run = await client.runs.get(run_id)

          if run.status in (RunStatus.COMPLETED, RunStatus.FAILED, RunStatus.CANCELLED):
              return run

          await asyncio.sleep(poll_interval)

  async def main():
      client = AsyncTinyFish()

      # Define your batch of tasks
      tasks_to_run = [
          {
              "url": "https://scrapeme.live/shop/",
              "goal": "Extract all available products on page two with their name, price, and review rating (if available)",
          },
          {
              "url": "https://books.toscrape.com/",
              "goal": "Extract all available books on page two with their title, price, and review rating (if available)",
          },
      ]

      # Step 1: Submit all tinyfish runs and collect run_ids
      print("Submitting tinyfish runs...")
      submit_tasks = [
          client.agent.queue(url=task["url"], goal=task["goal"])
          for task in tasks_to_run
      ]
      responses = await asyncio.gather(*submit_tasks)
      run_ids = [r.run_id for r in responses]
      print(f"Submitted {len(run_ids)} runs: {run_ids}")

      # Step 2: Wait for all runs to complete
      print("Waiting for completion...")
      completion_tasks = [
          wait_for_completion(client, run_id)
          for run_id in run_ids
      ]
      results = await asyncio.gather(*completion_tasks)

      # Step 3: Process results
      for i, run in enumerate(results):
          print(f"Run {i + 1} ({run.run_id}):")
          print(f"  Status: {run.status}")
          if run.status == RunStatus.COMPLETED:
              print(f"  Result: {run.result}")

  # Run the async main function
  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, RunStatus } from "@tiny-fish/sdk";

  const client = new TinyFish();

  async function waitForCompletion(runId: string, pollInterval = 2000) {
    while (true) {
      const run = await client.runs.get(runId);
      if (
        run.status === RunStatus.COMPLETED ||
        run.status === RunStatus.FAILED ||
        run.status === RunStatus.CANCELLED
      ) {
        return run;
      }
      await new Promise((r) => setTimeout(r, pollInterval));
    }
  }

  async function main() {
    // Define your batch of tasks
    const tasksToRun = [
      {
        url: "https://scrapeme.live/shop/",
        goal: "Extract all available products on page two with their name, price, and review rating (if available)",
      },
      {
        url: "https://books.toscrape.com/",
        goal: "Extract all available books on page two with their title, price, and review rating (if available)",
      },
    ];

    // Step 1: Submit all tinyfish runs and collect run_ids
    console.log("Submitting tinyfish runs...");
    const responses = await Promise.all(
      tasksToRun.map((task) => client.agent.queue(task))
    );
    const runIds = responses.map((response) => {
      if (response.error) {
        throw new Error(`Failed to queue run: ${response.error.message}`);
      }
      return response.run_id;
    });
    console.log(`Submitted ${runIds.length} runs:`, runIds);

    // Step 2: Wait for all runs to complete
    console.log("Waiting for completion...");
    const results = await Promise.all(runIds.map((id) => waitForCompletion(id)));

    // Step 3: Process results
    results.forEach((run, i) => {
      console.log(`Run ${i + 1} (${run.run_id}):`);
      console.log(`  Status: ${run.status}`);
      if (run.status === RunStatus.COMPLETED) {
        console.log(`  Result:`, run.result);
      }
    });
  }

  main();
  ```
</CodeGroup>

## Fire and Forget Pattern

Submit tasks without waiting for completion:

<CodeGroup>
  ```python Python theme={null}
  async def main():
      client = AsyncTinyFish()

      tasks_to_run = [
          {"url": "https://example.com/page1", "goal": "Extract product info"},
          {"url": "https://example.com/page2", "goal": "Extract product info"},
          {"url": "https://example.com/page3", "goal": "Extract product info"},
      ]

      # Submit all tasks
      submit_tasks = [
          client.agent.queue(url=task["url"], goal=task["goal"])
          for task in tasks_to_run
      ]
      responses = await asyncio.gather(*submit_tasks)
      run_ids = [r.run_id for r in responses]

      print(f"Submitted {len(run_ids)} runs")
      print(f"Run IDs: {run_ids}")
      print("Check status later using client.runs.get(run_id)")

  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  async function main() {
    const tasksToRun = [
      { url: "https://example.com/page1", goal: "Extract product info" },
      { url: "https://example.com/page2", goal: "Extract product info" },
      { url: "https://example.com/page3", goal: "Extract product info" },
    ];

    // Submit all tasks
    const responses = await Promise.all(
      tasksToRun.map((task) => client.agent.queue(task))
    );
    const runIds = responses.map((response) => {
      if (response.error) {
        throw new Error(`Failed to queue run: ${response.error.message}`);
      }
      return response.run_id;
    });

    console.log(`Submitted ${runIds.length} runs`);
    console.log("Run IDs:", runIds);
    console.log("Check status later using client.runs.get(runId)");
  }

  main();
  ```
</CodeGroup>

## When to Use Async vs Sync

| Use Case | API Pattern | Why |
| - | - | - |
| Quick tasks (\<30s) | Sync `/run` | Simpler code, immediate results |
| Long-running tasks | Async `/run-async` | Don't block, check later |
| Large batches | Async `/run-async` | Submit all at once, monitor progress |
| Fire and forget | Async `/run-async` | No need to wait |
| Real-time feedback | SSE `/run-sse` | Stream progress events |

## Best Practices

### Polling Interval

* **Short tasks (under 1 min)**: Poll every 2-3 seconds
* **Medium tasks (1-5 min)**: Poll every 5-10 seconds
* **Long tasks (over 5 min)**: Poll every 30-60 seconds

### Error Handling

Always check run status and handle failures:

```python Python theme={null}
async def process_completed_run(run):
    if run.status == RunStatus.COMPLETED:
        return run.result
    elif run.status == RunStatus.FAILED:
        print(f"Run {run.run_id} failed: {run.error}")
        return None
    elif run.status == RunStatus.CANCELLED:
        print(f"Run {run.run_id} was cancelled")
        return None
```

## API Reference

<CardGroup>
  <Card title="Run Async" icon="code" href="https://docs.tinyfish.ai/api-reference/automation/start-automation-asynchronously">
    Start TinyFish Web Agent run asynchronously
  </Card>

  <Card title="List Runs" icon="list" href="https://docs.tinyfish.ai/api-reference/automation/list-runs">
    Get all runs
  </Card>

  <Card title="Get Run by ID" icon="file" href="https://docs.tinyfish.ai/api-reference/automation/get-run-by-id">
    Check individual run status
  </Card>

  <Card title="Cancel Run" icon="xmark" href="https://docs.tinyfish.ai/api-reference/runs/cancel-run-by-id">
    Cancel a running automation
  </Card>
</CardGroup>

## Related

<CardGroup>
  <Card title="Concurrent Requests" icon="bolt" href="/examples/bulk-requests-sync">
    Sync API for immediate results
  </Card>

  <Card title="Web Scraping" icon="magnifying-glass" href="/examples/scraping">
    Extract data from pages
  </Card>
</CardGroup>


# Concurrent Requests
Source: https://docs.tinyfish.ai/examples/bulk-requests-sync

Process multiple runs in parallel for better performance

## Overview

When you need to scrape multiple pages, fill multiple forms, or process a batch of URLs, firing requests concurrently
can significantly speed up your workflow. This guide shows how to run multiple TinyFish Web Agent runs in parallel using the sync API.

## Basic Example

Fire multiple requests concurrently and gather results:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from tinyfish import AsyncTinyFish

  async def main():
      client = AsyncTinyFish()

      # Define your batch of tasks - scraping multiple sites
      tasks_to_run = [
          {
              "url": "https://scrapeme.live/shop/",
              "goal": "Extract all available products on page two with their name, price, and review rating (if available)",
          },
          {
              "url": "https://books.toscrape.com/",
              "goal": "Extract all available books on page two with their title, price, and review rating (if available)",
          },
      ]

      # Fire all requests concurrently
      tasks = [
          client.agent.run(url=task["url"], goal=task["goal"])
          for task in tasks_to_run
      ]

      # Wait for all tasks to complete
      results = await asyncio.gather(*tasks)

      # Process results
      for i, response in enumerate(results):
          print(f"Task {i + 1} result:", response.result)

  # Run the async main function
  asyncio.run(main())
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  async function main() {
    // Define your batch of tasks - scraping multiple sites
    const tasksToRun = [
      {
        url: "https://scrapeme.live/shop/",
        goal: "Extract all available products on page two with their name, price, and review rating (if available)",
      },
      {
        url: "https://books.toscrape.com/",
        goal: "Extract all available books on page two with their title, price, and review rating (if available)",
      },
    ];

    // Fire all requests concurrently
    const results = await Promise.all(
      tasksToRun.map((task) => client.agent.run(task))
    );

    // Process results
    results.forEach((response, i) => {
      console.log(`Task ${i + 1} result:`, response.result);
    });
  }

  main();
  ```
</CodeGroup>

<Note>
  The sync `/run` API is perfect for concurrent requests - you get clean, simple code without SSE stream handling,
  making it ideal for batch operations with `asyncio.gather()` or `Promise.all()`.
</Note>

## Batch Multiple Forms

Fill multiple contact forms concurrently:

```python Python theme={null}
async def main():
    client = AsyncTinyFish()

    companies = [
        {"name": "Acme Corp", "url": "https://acme.com/contact"},
        {"name": "TechStart", "url": "https://techstart.io/contact"},
        {"name": "BuildIt", "url": "https://buildit.com/contact"},
    ]

    tasks = [
        client.agent.run(
            url=company["url"],
            goal=f"""Fill in the contact form:
                - Name field: "John Doe"
                - Email field: "john@example.com"
                - Message field: "Interested in partnership with {company['name']}"
                Then click Submit and extract the success message.
            """,
        )
        for company in companies
    ]

    results = await asyncio.gather(*tasks)

    for company, response in zip(companies, results):
        print(f"{company['name']}: {response.result}")
```

## Gotchas and Caveats

<Warning>
  **Concurrency Limits**: Each user account has a concurrency limit for simultaneous browser sessions. When you exceed
  this limit, additional requests will be queued automatically rather than returning a 429 error.
</Warning>

### Queueing Behavior

When you hit your account's concurrency cap:

* **No 429 errors**: Unlike traditional rate-limited APIs, TinyFish won't reject your request with a 429 status code
* **Automatic queueing**: Your request will be accepted and queued until a browser session becomes available
* **Longer run times**: The total run time will include both queue wait time and execution time

**Example scenario**: If your account allows 3 concurrent sessions and you fire 10 requests simultaneously:

* Requests 1-3 start immediately
* Requests 4-10 are queued
* As each request completes, the next queued request begins
* You won't get errors, but later requests will take longer to complete

<Note>
  We're actively working on improving the queueing experience with better visibility into queue position and estimated
  wait times. This behavior will be enhanced in an upcoming release.
</Note>

### Best Practices

* **Know your limits**: Concurrency is limited per account; 429 and limit errors tell you when you've hit it
* **Batch sizing**: Size your concurrent batches to match your concurrency limit for optimal performance
* **Progress tracking**: Implement timing/logging to monitor which requests are queued vs executing
* **Error handling**: Always handle potential timeouts for long-running or queued requests

## Related

<CardGroup>
  <Card title="Web Scraping" icon="magnifying-glass" href="/examples/scraping">
    Extract data from pages
  </Card>

  <Card title="Form Filling" icon="file-lines" href="/examples/form-filling">
    Automate form submissions
  </Card>

  <Card title="Run API Reference" icon="code" href="https://docs.tinyfish.ai/api-reference/automation/run-browser-automation-synchronously">
    Complete API documentation
  </Card>
</CardGroup>


# Form Filling
Source: https://docs.tinyfish.ai/examples/form-filling

Automate form filling and submission

## Basic Example

Fill and submit a contact form:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish, EventType, RunStatus

  client = TinyFish()

  with client.agent.stream(
      url="https://example.com/contact",
      goal="""Fill in the contact form:
          - Name field: "John Doe"
          - Email field: "john@example.com"
          - Message field: "I am interested in your services."
          Then click the Submit button and extract the success message.
      """,
  ) as stream:
      for event in stream:
          if event.type == EventType.COMPLETE and event.status == RunStatus.COMPLETED:
              print("Result:", event.result_json)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://example.com/contact",
      goal: `Fill in the contact form:
        - Name field: "John Doe"
        - Email field: "john@example.com"
        - Message field: "I am interested in your services."
        Then click the Submit button and extract the success message.
      `,
    });

    for await (const event of stream) {
      if (event.type === EventType.COMPLETE && event.status === RunStatus.COMPLETED) {
        console.log("Result:", event.result);
      }
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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://example.com/contact",
      "goal": "Fill in the contact form with name John Doe and email john@example.com, then click Submit"
    }'
  ```

  ```bash CLI theme={null}
  tinyfish agent run "Fill in the contact form: Name: John Doe, Email: john@example.com, Message: I am interested in your services. Then click Submit and return the success message." \
    --url example.com/contact --pretty
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "success": true,
  "message": "Thank you for contacting us!"
}
```

## Multi-Step Form

Handle multi-step forms in a single goal:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  with client.agent.stream(
      url="https://example.com/signup",
      goal="""Complete the multi-step signup form:

          Step 1 (Personal Info):
          - First name: "John"
          - Last name: "Doe"
          - Email: "john@example.com"
          - Click "Next"

          Step 2 (Address):
          - Street: "123 Main St"
          - City: "San Francisco"
          - State: "CA"
          - ZIP: "94102"
          - Click "Next"

          Step 3 (Preferences):
          - Select "Email notifications" checkbox
          - Click "Submit"

          Extract the confirmation number from the success page.
      """,
  ) as stream:
      for event in stream:
          print(event)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://example.com/signup",
      goal: `Complete the multi-step signup form:

        Step 1 (Personal Info):
        - First name: "John"
        - Last name: "Doe"
        - Email: "john@example.com"
        - Click "Next"

        Step 2 (Address):
        - Street: "123 Main St"
        - City: "San Francisco"
        - State: "CA"
        - ZIP: "94102"
        - Click "Next"

        Step 3 (Preferences):
        - Select "Email notifications" checkbox
        - Click "Submit"

        Extract the confirmation number from the success page.
      `,
    });

    for await (const event of stream) {
      console.log(event);
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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://example.com/signup",
      "goal": "Complete the multi-step signup form: Step 1 - First name John, Last name Doe, Email john@example.com, click Next. Step 2 - Street 123 Main St, City San Francisco, State CA, ZIP 94102, click Next. Step 3 - Select Email notifications checkbox, click Submit. Extract the confirmation number."
    }'
  ```
</CodeGroup>

## Tips

* Use stealth mode for login/signup forms
* Be explicit about field values in your goal
* Describe buttons by their text ("click 'Submit'")
* Handle multi-step forms in one goal

## Try It

<Steps>
  <Step title="Save the code">Save any example above as `form.ts`</Step>
  <Step title="Set your API key">`export TINYFISH_API_KEY="your_api_key" `</Step>
  <Step title="Run it">`npx tsx form.ts `</Step>
</Steps>

## Related

<CardGroup>
  <Card title="Web Scraping" icon="magnifying-glass" href="/examples/scraping">
    Extract data from pages
  </Card>

  <Card title="Run SSE API" icon="code" href="/api-reference">
    Complete API docs
  </Card>
</CardGroup>


# Web Scraping
Source: https://docs.tinyfish.ai/examples/scraping

Extract data from any website using natural language

## Basic Example

Extract product data from any page:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish, EventType, RunStatus

  client = TinyFish()

  with client.agent.stream(
      url="https://scrapeme.live/shop/Bulbasaur/",
      goal="Extract the product name, price, and stock status. Return as JSON.",
  ) as stream:
      for event in stream:
          if event.type == EventType.COMPLETE and event.status == RunStatus.COMPLETED:
              print("Result:", event.result_json)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://scrapeme.live/shop/Bulbasaur/",
      goal: "Extract the product name, price, and stock status. Return as JSON.",
    });

    for await (const event of stream) {
      if (event.type === EventType.COMPLETE && event.status === RunStatus.COMPLETED) {
        console.log("Result:", event.result);
      }
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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/Bulbasaur/",
      "goal": "Extract the product name, price, and stock status. Return as JSON."
    }'
  ```

  ```bash CLI theme={null}
  tinyfish agent run "Extract the product name, price, and stock status. Return as JSON." \
    --url scrapeme.live/shop/Bulbasaur/ --pretty
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "name": "Bulbasaur",
  "price": "£63.00",
  "inStock": true
}
```

## Extract Multiple Items

Get all products from a category page:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  with client.agent.stream(
      url="https://scrapeme.live/shop/",
      goal="Extract all products on this page. For each product return: name, price, and link. Return as JSON.",
  ) as stream:
      for event in stream:
          print(event)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://scrapeme.live/shop/",
      goal: "Extract all products on this page. For each product return: name, price, and link. Return as JSON.",
    });

    for await (const event of stream) {
      console.log(event);
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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 all products on this page. For each product return: name, price, and link. Return as JSON."
    }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "products": [
    { "name": "Bulbasaur", "price": "£63.00", "link": "https://..." },
    { "name": "Ivysaur", "price": "£87.00", "link": "https://..." },
    { "name": "Venusaur", "price": "£105.00", "link": "https://..." }
  ]
}
```

## Use Stealth Mode

For sites with bot protection:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish, BrowserProfile

  client = TinyFish()

  with client.agent.stream(
      url="https://protected-site.com",
      goal="Extract product data",
      browser_profile=BrowserProfile.STEALTH,
  ) as stream:
      for event in stream:
          print(event)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, BrowserProfile } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://protected-site.com",
      goal: "Extract product data",
      browser_profile: BrowserProfile.STEALTH,
    });

    for await (const event of stream) {
      console.log(event);
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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://protected-site.com",
      "goal": "Extract product data",
      "browser_profile": "stealth"
    }'
  ```
</CodeGroup>

## Use Proxy

Route through a specific country:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish, BrowserProfile, ProxyConfig, ProxyCountryCode

  client = TinyFish()

  with client.agent.stream(
      url="https://geo-restricted-site.com",
      goal="Extract data",
      browser_profile=BrowserProfile.STEALTH,
      proxy_config=ProxyConfig(enabled=True, country_code=ProxyCountryCode.US),
  ) as stream:
      for event in stream:
          print(event)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish, BrowserProfile, ProxyCountryCode } from "@tiny-fish/sdk";

  async function main() {
    const client = new TinyFish();

    const stream = await client.agent.stream({
      url: "https://geo-restricted-site.com",
      goal: "Extract data",
      browser_profile: BrowserProfile.STEALTH,
      proxy_config: { enabled: true, country_code: ProxyCountryCode.US },
    });

    for await (const event of stream) {
      console.log(event);
    }
  }

  main();
  ```

  ```bash cURL theme={null}
  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://geo-restricted-site.com",
      "goal": "Extract data",
      "browser_profile": "stealth",
      "proxy_config": {
        "enabled": true,
        "country_code": "US"
      }
    }'
  ```
</CodeGroup>

## Try It

<Steps>
  <Step title="Save the code">Save any example above as `scraper.ts`</Step>
  <Step title="Set your API key">`export TINYFISH_API_KEY="your_api_key" `</Step>
  <Step title="Run it">`npx tsx scraper.ts `</Step>
</Steps>

## Related

<CardGroup>
  <Card title="Form Filling" icon="file-lines" href="/examples/form-filling">
    Automate form submissions
  </Card>

  <Card title="Run SSE API" icon="code" href="/api-reference">
    Complete API docs
  </Card>
</CardGroup>


# Frequently Asked Questions
Source: https://docs.tinyfish.ai/faq

Common questions about TinyFish Web Agent

## General

<AccordionGroup>
  <Accordion title="What is TinyFish Web Agent?" icon="circle-info">
    TinyFish Web Agent is an AI-powered web automation API that lets you automate any website using natural language.
    Instead of writing brittle selectors, you describe what you want to do, and our AI handles the rest.
  </Accordion>

  <Accordion title="What sites can I automate?" icon="globe">
    Any publicly accessible website. For authenticated sites, use [Vault Credentials](/key-concepts/credentials) or a
    saved [Browser Context Profile](/key-concepts/browser-context-profiles) instead of putting passwords in your goal.
    For sites with bot protection, use stealth mode and a proxy.
  </Accordion>

  <Accordion title="How fast are automations?" icon="bolt">
    Typically 3-10 seconds for simple pages, 30-60 seconds for complex multi-step automations. Time depends on page load
    speed and task complexity.
  </Accordion>

  <Accordion title="Can I see the browser?" icon="eye">
    Yes. Runs provide a `streaming_url` where you can watch the browser execute live. With the SSE API, listen for the
    `STREAMING_URL` event; for queued runs, retrieve the run with `client.runs.get(run_id)` or `GET /v1/runs/:id`.
  </Accordion>
</AccordionGroup>

## API Usage

<AccordionGroup>
  <Accordion title="What authentication method do I use?" icon="key">
    The REST API uses the `X-API-Key` header:

    ```
    X-API-Key: $TINYFISH_API_KEY
    ```

    The Python SDK, TypeScript SDK, and CLI also use your API key. The MCP endpoint uses OAuth 2.1 for AI assistant
    integrations. CLI run IDs and MCP run IDs are scoped to different tokens, so a CLI lookup for an MCP-created run can
    return 404 by design.
  </Accordion>

  <Accordion title="Do you support proxies?" icon="route">
    Yes, configure proxy routing:

    ```typescript theme={null}
    {
      proxy_config: {
        enabled: true,
        country_code: "US"
      }
    }
    ```

    Supported countries: US, GB, CA, DE, FR, JP, AU.
  </Accordion>

  <Accordion title="How do I process many URLs?" icon="list-check">
    For a few immediate results, use concurrent sync requests with `asyncio.gather()`, `Promise.all()`, or shell
    background jobs. For larger or long-running sets, use `agent.queue()` in SDKs, `POST /v1/automation/run-batch` in
    REST, or `tinyfish agent batch run` in the CLI.

    See [Concurrent Requests](/examples/bulk-requests-sync) and [Async Bulk Requests](/examples/bulk-requests-async).
  </Accordion>
</AccordionGroup>

## Technical

<AccordionGroup>
  <Accordion title="What browsers do you use?" icon="browser">
    We use Chromium-based browsers. Choose between:

    * **Lite**: Standard Chromium (fast)
    * **Stealth**: Modified Chromium with anti-detection (slower but bypasses bot protection)
  </Accordion>

  <Accordion title="What about JavaScript-heavy sites?" icon="js">
    We fully support SPAs (React, Vue, Angular). Pages are rendered and JavaScript is executed before extraction.
  </Accordion>

  <Accordion title="Can I automate authenticated content?" icon="lock">
    Yes! For password-manager login, connect your password manager (1Password or Bitwarden) in **Settings → Vault**.
    Select credentials per run and TinyFish handles login securely — the AI agent never sees your actual passwords.
    For sites where saved session state matters, create a Browser Context Profile after signing in once, then use that
    profile on future runs.

    See the [Connect Your Vault](/vault-setup) guide for setup, [Vault Credentials](/key-concepts/credentials) for how
    credential access works, and [Browser Context Profiles](/key-concepts/browser-context-profiles) for reusing cookies,
    MFA state, and trusted-device sessions.

    API example:

    ```typescript theme={null}
    const run = await client.agent.run({
      url: "https://app.example.com/dashboard",
      goal: "Log in and summarize the account dashboard",
      use_vault: true,
      use_profile: true,
    });
    ```

    If you haven't connected a vault or saved profile, you can still include login steps in your goal:

    ```typescript theme={null}
    goal: `
      1. Login with username "user@example.com" and password "pass123"
      2. Navigate to dashboard
      3. Extract account balance
    `
    ```

    <Warning>Including credentials directly in goals is less secure — they appear in run logs and AI context. Use vault credentials when possible.</Warning>
  </Accordion>

  <Accordion title="Do you support pagination?" icon="arrows-left-right">
    Yes, describe pagination in your goal:

    ```typescript theme={null}
    goal: `Click "Next Page" button 5 times, extracting products from each page`
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="What does COMPLETED status mean?" icon="circle-check">
    `status: "COMPLETED"` means the **infrastructure succeeded** - the browser launched, navigated, and the automation finished without crashing.

    **It does NOT mean the goal was achieved.** You must check the `result` field to determine if the goal succeeded.

    **Scenario 1: Goal achieved**

    ```json theme={null}
    {
      "status": "COMPLETED",
      "result": {
        "products": [
          { "name": "iPhone 15", "price": "$799" }
        ]
      },
      "error": null
    }
    ```

    The `result` contains the extracted data - goal succeeded.

    **Scenario 2: Infrastructure succeeded, goal failed**

    ```json theme={null}
    {
      "status": "COMPLETED",
      "result": {
        "status": "failure",
        "reason": "Could not find any products on the page",
        "product_price": null
      },
      "error": null
    }
    ```

    Status is COMPLETED (browser worked), but `result.status` is "failure" indicating the goal wasn't achieved.

    **Scenario 3: Infrastructure failed**

    ```json theme={null}
    {
      "status": "FAILED",
      "result": null,
      "error": {
        "message": "Browser crashed during execution"
      }
    }
    ```

    The automation couldn't complete due to infrastructure issues.

    **Best Practice:** Always validate `result` content, not just `status`:

    ```typescript theme={null}
    if (run.status === "COMPLETED" && run.result) {
      // Check if result indicates goal failure
      if (run.result.status === "failure" || run.result.error) {
        console.log("Goal not achieved:", run.result.reason || run.result.error);
      } else {
        console.log("Data extracted:", run.result);
      }
    } else if (run.status === "FAILED") {
      console.log("Automation failed:", run.error?.message);
    }
    ```
  </Accordion>

  <Accordion title="Why is my automation failing?" icon="bug">
    Common causes:

    1. **Timeout** - Site is slow or down
       * Solution: Retry or use stealth mode
    2. **Access Denied** - Anti-bot protection
       * Solution: Use stealth mode + proxy
    3. **Element Not Found** - Goal is too specific
       * Solution: Make goal more flexible (describe visually)
    4. **Invalid URL** - URL is malformed
       * Solution: Ensure URL includes `https://`
  </Accordion>

  <Accordion title="Site is blocking me. What do I do?" icon="shield">
    ```typescript theme={null}
    // Use stealth mode
    browser_profile: "stealth"

    // Add proxy
    proxy_config: {
      enabled: true,
      country_code: "US"
    }

    // Reduce speed (add delays in goal)
    goal: "Wait 3 seconds, then click button"
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="What makes a good goal?" icon="bullseye">
    **Good** (specific, actionable):

    ```typescript theme={null}
    goal: "Extract product name, price, and stock status from the product details section"
    ```

    **Bad** (vague):

    ```typescript theme={null}
    goal: "Get data"
    ```
  </Accordion>

  <Accordion title="When should I use stealth mode?" icon="user-secret">
    Use stealth when:

    * Site shows CAPTCHA
    * Getting "Access Denied" errors
    * Site uses Cloudflare or anti-bot protection

    Otherwise use lite mode (faster).
  </Accordion>
</AccordionGroup>

## Getting Help

<CardGroup>
  <Card title="Email Support" icon="envelope" href="mailto:support@tinyfish.io">
    [support@tinyfish.io](mailto:support@tinyfish.io)
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/tinyfish">
    Join our community
  </Card>
</CardGroup>

## Related

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Get started in 5 minutes
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete endpoint docs
  </Card>
</CardGroup>


# Fetch Examples
Source: https://docs.tinyfish.ai/fetch-api/examples

Real-world examples for the Fetch API

## Fetch a Single Page

Extract content from any URL as clean Markdown:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://example.com"],
      format="markdown",
  )

  page = result.results[0]
  print(f"Title: {page.title}")
  print(page.text)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://example.com"],
    format: "markdown",
  });

  const page = result.results[0];
  console.log(`Title: ${page.title}`);
  console.log(page.text);
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"urls": ["https://example.com"], "format": "markdown"}'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "language": "en",
      "text": "This domain is for use in documentation examples without needing permission...",
      "format": "markdown"
    }
  ],
  "errors": []
}
```

## Batch Fetch

Fetch up to 10 URLs in a single request. Failed URLs appear in `errors[]` without affecting the rest:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=[
          "https://example.com",
          "https://httpbin.org/html",
          "https://nonexistent.invalid",
      ],
      format="markdown",
  )

  for page in result.results:
      print(f"OK: {page.url} → {page.text[:80]}")

  for err in result.errors:
      print(f"FAIL: {err.url} → {err.error}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: [
      "https://example.com",
      "https://httpbin.org/html",
      "https://nonexistent.invalid",
    ],
    format: "markdown",
  });

  for (const page of result.results) {
    console.log(`OK: ${page.url} → ${page.text.slice(0, 80)}`);
  }

  for (const err of result.errors) {
    console.log(`FAIL: ${err.url} → ${err.error}`);
  }
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": [
        "https://example.com",
        "https://httpbin.org/html",
        "https://nonexistent.invalid"
      ],
      "format": "markdown"
    }'
  ```
</CodeGroup>

## Fetch with Intent

Pass the optional `purpose` parameter to state *why* you are fetching — the goal or
task the content will be used for. It is always optional, but supplying it gives the
fetch additional intent signal beyond the raw URLs, helping deliver
better-quality results.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://example.com/pricing"],
      purpose="Compare pricing tiers across vendors for a procurement report",
  )
  print(result.results[0].text)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://example.com/pricing"],
    purpose: "Compare pricing tiers across vendors for a procurement report",
  });
  console.log(result.results[0].text);
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com/pricing"],
      "purpose": "Compare pricing tiers across vendors for a procurement report"
    }'
  ```
</CodeGroup>

## Control Cache Freshness

Use `ttl` when you need to bound how old a cached page can be. Set `ttl` to `0` when you want a live fetch, or to a positive number of seconds to accept cached entries younger than that window.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://example.com"],
      ttl=0,
  )
  print(result.results[0].text)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://example.com"],
    ttl: 0,
  });
  console.log(result.results[0].text);
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"urls": ["https://example.com"], "ttl": 0}'
  ```
</CodeGroup>

## Detect Page Changes with Conditional Requests

Save a page's `etag`, then replay it on your next fetch to skip re-processing content that hasn't changed. Conditional requests are a stateless pass-through — Fetch doesn't store the validators for you.

**1. Bootstrap: fetch once and save the `etag`**

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com"],
      "include_etag_and_last_modified": true
    }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "results": [
    {
      "url": "https://example.com",
      "final_url": "https://example.com/",
      "text": "This domain is for use in documentation examples without needing permission...",
      "format": "markdown",
      "etag": "W/\"abc123\"",
      "last_modified": "Wed, 21 Oct 2015 07:28:00 GMT"
    }
  ],
  "errors": []
}
```

Save `etag` (or `last_modified`) somewhere durable, keyed by URL.

**2. Later: replay the `etag` to check for changes**

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com"],
      "if_none_match": "W/\"abc123\"",
      "include_etag_and_last_modified": true
    }'
  ```
</CodeGroup>

<Tabs>
  <Tab title="Unchanged">
    The origin confirms nothing changed — skip re-processing:

    ```json theme={null}
    {
      "results": [
        {
          "url": "https://example.com",
          "final_url": "https://example.com/",
          "text": null,
          "format": "markdown",
          "not_modified": true,
          "etag": "W/\"abc123\"",
          "last_modified": "Wed, 21 Oct 2015 07:28:00 GMT"
        }
      ],
      "errors": []
    }
    ```
  </Tab>

  <Tab title="Changed">
    The page changed — fresh content plus a new `etag` to save for next time:

    ```json theme={null}
    {
      "results": [
        {
          "url": "https://example.com",
          "final_url": "https://example.com/",
          "text": "This domain now includes updated documentation examples...",
          "format": "markdown",
          "etag": "W/\"def456\"",
          "last_modified": "Thu, 02 Jul 2026 12:00:00 GMT"
        }
      ],
      "errors": []
    }
    ```
  </Tab>
</Tabs>

## Scope Extraction to Part of the Page

Use `include_selectors` to extract only the elements you care about, and `exclude_selectors` to strip noise (removed before `include_selectors` is applied). Selected content is returned verbatim in the requested format — automatic boilerplate removal is bypassed — while page-level metadata (`title`, `description`, etc.) still comes from the full document.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://example.com/blog/post"],
      "format": "markdown",
      "include_selectors": ["article", "aside.related"],
      "exclude_selectors": [".comments", ".newsletter-signup"]
    }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "results": [
    {
      "url": "https://example.com/blog/post",
      "final_url": "https://example.com/blog/post",
      "title": "Post Title",
      "text": "# Post Title\n\nOnly the article content, with comments and the newsletter signup removed...",
      "format": "markdown",
      "unmatched_selectors": ["aside.related"]
    }
  ],
  "errors": []
}
```

Here `article` matched but `aside.related` didn't — a **partial miss**. The URL still succeeds with the matched content, and the entries that matched nothing are listed in the result's `unmatched_selectors` (omitted when everything matched).

<Note>
  If **no** `include_selectors` entry matches anything on a page, that URL fails with the per-URL error code `selector_not_matched` in `errors[]` — there is no silent full-page fallback. The error carries `unmatched_selectors` (what missed) and `candidate_selectors` (up to 10 landmark tags and `#id` selectors found on the page), so agents can retry with `include_selectors` drawn from `candidate_selectors`. `exclude_selectors` entries that match nothing are simply a no-op.
</Note>

## Extract Ranked Passages with Highlights

Add a `highlights` object with a question to pull the passages that best answer it from each page — ranked, and quoted word-for-word from the page. Passages are extracted, never generated, so they're citable evidence with zero fabrication risk. Highlights is in **beta**, enabled per-account — requests from an account that isn't enabled return `403 FORBIDDEN`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -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/"],
      "format": "markdown",
      "highlights": {
        "query": "what does TinyFish do and who uses it",
        "max_snippets": 3
      }
    }'
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "results": [
    {
      "url": "https://www.tinyfish.ai/",
      "final_url": "https://www.tinyfish.ai/",
      "title": "TinyFish — Web Infrastructure for AI Agents",
      "text": null,
      "format": "markdown",
      "highlights": [
        { "text": "Teams use TinyFish when the work depends on dynamic pages, authenticated flows, structured outputs, and production reliability...", "rank": 1 },
        { "text": "One config change gives your agents Search, Fetch, Browser, and Agent. MCP-native, so it works with Claude, Cursor, and any MCP-compatible client...", "rank": 2 },
        { "text": "Your model reasons. TinyFish gives it the live web. Default web access returns cached results. TinyFish hits the live page...", "rank": 3 }
      ]
    }
  ],
  "errors": []
}
```

`text` is `null` because a highlights request returns just the passages by default — set `highlights.include_full_page_text: true` to also receive the full page markdown.

<Note>
  An **empty** `highlights` array means the page was fetched and analyzed and does not answer the query — a calibrated "nothing here", not a failure. The API may also return passages that are *related* to the query without directly answering it, so treat highlights as candidate evidence to extract from: if the asked-for fact isn't in the passages, the correct conclusion is "not on this page."
</Note>

## Extract Links

Get all hyperlinks and image URLs from a page:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://www.tinyfish.ai/"],
      format="markdown",
      links=True,
      image_links=True,
  )

  page = result.results[0]
  print(f"Found {len(page.links)} links and {len(page.image_links)} images")

  for link in page.links[:5]:
      print(f"  → {link}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://www.tinyfish.ai/"],
    format: "markdown",
    links: true,
    image_links: true,
  });

  const page = result.results[0];
  console.log(`Found ${page.links.length} links and ${page.image_links.length} images`);

  for (const link of page.links.slice(0, 5)) {
    console.log(`  → ${link}`);
  }
  ```

  ```bash cURL theme={null}
  curl -s -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/"],
      "format": "markdown",
      "links": true,
      "image_links": true
    }'
  ```
</CodeGroup>

## Fetch as HTML

Get semantic HTML instead of Markdown — useful for preserving structure:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://httpbin.org/html"],
      format="html",
  )

  page = result.results[0]
  print(page.text[:300])
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://httpbin.org/html"],
    format: "html",
  });

  const page = result.results[0];
  console.log(page.text.slice(0, 300));
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.fetch.tinyfish.ai \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"urls": ["https://httpbin.org/html"], "format": "html"}'
  ```
</CodeGroup>

***

## Related

<CardGroup>
  <Card title="Fetch Reference" icon="bolt" href="/fetch-api/reference">
    Full parameter, response, and content type docs
  </Card>

  <Card title="Search Examples" icon="magnifying-glass" href="/search-api/examples">
    Web search with geo-targeting
  </Card>
</CardGroup>


# Fetch API
Source: https://docs.tinyfish.ai/fetch-api/index

Fetch URLs and extract clean text — no external APIs required

<Note>
  Fetch is free up to 1,000 URLs per day. Beyond that, requests need a positive wallet balance.
</Note>

The TinyFish Fetch API fetches web pages, renders JavaScript-heavy pages when needed, and returns clean extracted text in your preferred format. Submit a URL, get back structured content.

```bash theme={null}
POST https://api.fetch.tinyfish.ai
```

`api.fetch.tinyfish.ai` is the public Fetch API endpoint.

## Before You Start

<Steps>
  <Step title="Get your API key">
    Visit [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys) and create a key. Store it in your environment:

    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for the full setup and troubleshooting guide.

## Your First Request

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(urls=["https://www.tinyfish.ai/"])
  print(result.results[0].title)
  print(result.results[0].text)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://www.tinyfish.ai/"],
  });
  console.log(result.results[0].title);
  console.log(result.results[0].text);
  ```

  ```bash cURL theme={null}
  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/"]}'
  ```
</CodeGroup>

## What Success Looks Like

```json theme={null}
{
  "results": [
    {
      "url": "https://www.tinyfish.ai/",
      "final_url": "https://www.tinyfish.ai/",
      "title": "TinyFish | Enterprise Web Agent Infrastructure",
      "description": "TinyFish provides enterprise infrastructure for AI web agents.",
      "language": "en",
      "format": "markdown",
      "text": "# TinyFish | Enterprise Web Agent Infrastructure\n\nTinyFish provides enterprise infrastructure for AI web agents...\n"
    }
  ],
  "errors": []
}
```

## When to Use Fetch vs the Other APIs

* Use **Fetch** when you already know the URL and need clean extracted page content.
* Use **Search** when you need help finding the right URLs first.
* Use **Agent** when TinyFish should perform a multi-step workflow on the site.
* Use **Browser** when you need direct browser control from your own code.

***

## Fetching Multiple URLs

Submit up to 10 URLs in a single request. Each URL is processed independently — one failure doesn't affect the others.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=[
          "https://www.tinyfish.ai/",
          "https://en.wikipedia.org/wiki/Web_scraping",
          "https://docs.python.org/3/tutorial/index.html",
      ]
  )

  for page in result.results:
      print(page.url, "→", page.title)

  for error in result.errors:
      print("Failed:", error.url, "–", error.error)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: [
      "https://www.tinyfish.ai/",
      "https://en.wikipedia.org/wiki/Web_scraping",
      "https://docs.python.org/3/tutorial/index.html",
    ],
  });

  result.results.forEach((r) => console.log(r.url, "→", r.title));
  result.errors.forEach((e) => console.log("Failed:", e.url, "–", e.error));
  ```

  ```bash cURL theme={null}
  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/",
        "https://en.wikipedia.org/wiki/Web_scraping",
        "https://docs.python.org/3/tutorial/index.html"
      ]
    }'
  ```
</CodeGroup>

<Note>
  Per-URL failures (timeouts, DNS errors, anti-bot blocks) appear in `errors[]` alongside a `200` response — they do not cause the entire request to fail.
</Note>

***

## Output Formats

Control the format of the `text` field with the `format` parameter. When omitted, the default is `markdown`.

<Tabs>
  <Tab title="html">
    Semantic HTML.

    ```json theme={null}
    {
      "format": "html",
      "text": "<h1>Async Fn in Traits Are Now Available</h1>
    <p>Starting with Rust 1.75, you can use <code>async fn</code> directly inside traits.</p>
    <h2>What Changed</h2>
    <ul>
    <li>Works in all stable traits</li>
    <li>No heap allocation for simple cases</li>
    </ul>"
    }
    ```
  </Tab>

  <Tab title="markdown">
    Clean Markdown. Ideal for LLM consumption and readable storage.

    ```json theme={null}
    {
      "format": "markdown",
      "text": "# Async Fn in Traits Are Now Available

    Starting with Rust 1.75, you can use `async fn` directly inside traits.

    ## What Changed

    Previously, writing async functions in traits required the `async-trait` crate...

    - Works in all stable traits
    - No heap allocation for simple cases
    - Compatible with `Send` bounds"
    }
    ```
  </Tab>

  <Tab title="json">
    Structured document tree. Useful for programmatic content processing.

    ```json theme={null}
    {
      "format": "json",
      "text": {
        "type": "document",
        "children": [
          { "type": "heading", "level": 1, "text": "Async Fn in Traits Are Now Available" },
          { "type": "paragraph", "text": "Starting with Rust 1.75, you can use async fn directly inside traits." },
          { "type": "heading", "level": 2, "text": "What Changed" },
          { "type": "list", "ordered": false, "items": ["Works in all stable traits", "No heap allocation for simple cases"] }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

***

## Cache Freshness

By default, Fetch may serve an existing cached entry for the URL when one is available. Pass `ttl` to set a freshness preference in seconds.

```json theme={null}
{
  "urls": ["https://example.com"],
  "ttl": 3600
}
```

* Omit `ttl` to accept any cached entry.
* Set `ttl` to `0` when you want a live fetch.
* Set `ttl` to a positive integer to accept cached entries younger than that many seconds.

***

## Conditional Requests

Skip reprocessing pages that haven't changed since your last fetch. Set `include_etag_and_last_modified: true` to get `etag` / `last_modified` validators back on each result, save them, then replay the `etag` as `if_none_match` (or the `last_modified` as `if_modified_since`) the next time you fetch that URL.

```json theme={null}
{
  "urls": ["https://example.com"],
  "if_none_match": "W/\"abc123\"",
  "include_etag_and_last_modified": true
}
```

* `if_none_match` and `if_modified_since` are single-URL only — combining either with a batch of URLs returns a `400`.
* When the origin confirms nothing changed, the result comes back with `not_modified: true` so you can skip re-processing.
* Fetch persists nothing — you own storing and replaying the validators.

See the [full reference](/fetch-api/reference#parameters) and a [worked example](/fetch-api/examples#detect-page-changes-with-conditional-requests).

***

## CSS Selector Scoping

Extract only the part of the page you care about. Pass `include_selectors` (an array of CSS selectors, max 20) to scope extracted content to elements matching any entry, and/or `exclude_selectors` to strip matching elements before extraction.

```json theme={null}
{
  "urls": ["https://example.com/blog/post"],
  "include_selectors": ["article"],
  "exclude_selectors": [".comments", ".newsletter-signup"]
}
```

* Selected content is returned verbatim in your requested format — automatic boilerplate removal is bypassed. Page-level metadata (`title`, `description`, etc.) still comes from the full document.
* `exclude_selectors` is applied first, then `include_selectors` scopes what remains.
* If some entries match and others don't, the URL still succeeds and the misses are listed in the result's `unmatched_selectors`. If no entry matches anything, that URL fails with `selector_not_matched` in `errors[]`, carrying `unmatched_selectors` plus `candidate_selectors` retry hints — agents can retry with `include_selectors` drawn from that list. `exclude_selectors` entries that match nothing are a no-op.

See the [full reference](/fetch-api/reference#parameters) and a [worked example](/fetch-api/examples#scope-extraction-to-part-of-the-page).

***

## Highlights

Add a `highlights` object to a normal Fetch request and, for each URL, get back the passages from that page that best answer your question — ranked, and quoted word-for-word from the page. Highlights are extracted, never generated: every passage is an exact substring of the fetched page, so they can't paraphrase or hallucinate. When the page doesn't answer the question, you get an explicit empty list instead of a forced guess.

<Info>
  **Beta:** Highlights is in beta and is enabled per-account — contact support to enable it for your account. Requests that include `highlights` from an account that isn't enabled return `403 FORBIDDEN`; requests without the field are unaffected.
</Info>

```json theme={null}
{
  "urls": ["https://example.com/"],
  "format": "markdown",
  "highlights": {
    "query": "what does this company do and who are its main customers",
    "max_snippets": 5
  }
}
```

* `highlights` requires `format: "markdown"`.
* Each result gains a `highlights` array of ranked verbatim passages, best first. An **empty list** means the page was fetched and analyzed and does not answer the query — a deliberate, calibrated signal, not a failure. A **missing field** means highlights could not be computed for that URL (rare and transient — the fetch itself still succeeded, and a retry is safe).
* Include the entity or topic in the query (e.g. "who founded Acme Corp", not "who founded this company") — retrieval works on vocabulary overlap with the page, and keyword-poor queries return empty results far more often.
* Typical single-URL highlights request on a live page render: \~1.5–2s; JavaScript-heavy sites can take 10–20s to render server-side. Multi-URL requests process in parallel, so request latency ≈ the slowest URL in the batch.

See the [full reference](/fetch-api/reference#parameters) and a [worked example](/fetch-api/examples#extract-ranked-passages-with-highlights).

***

## Supported Content Types

The Fetch API handles more than just HTML. See the [full content types table](/fetch-api/reference#supported-content-types) in the reference — in short: PDF text extraction works, JSON endpoints return raw JSON, but binary files (images, video) return an error.

***

## Fetch Intent

The optional `purpose` parameter lets you state *why* you are fetching — the underlying goal or task the content will be used for. A URL alone says nothing about what you need from the page. Passing `purpose` gives us additional signal to further inform and deliver better-quality results. It works the same way as the [Search API's `purpose` parameter](/search-api/index#search-intent).

* `purpose` is always optional. Omitting it leaves fetch behaviour unchanged.
* Keep it to a short phrase or sentence (maximum 2000 characters), for example `Compare pricing tiers across vendors for a procurement report`.

***

## Read Next

<CardGroup>
  <Card title="API Reference" icon="code" href="/fetch-api/reference">
    Full request and response schema
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup
  </Card>

  <Card title="Fetch Examples" icon="bolt" href="/fetch-api/examples">
    Common Fetch request patterns
  </Card>

  <Card title="For coding agents" icon="robot" href="/for-coding-agents">
    One page that routes an agent to the right TinyFish API
  </Card>
</CardGroup>


# Fetch API Reference
Source: https://docs.tinyfish.ai/fetch-api/reference

Complete reference for the Fetch API endpoint

## Endpoint

```
POST https://api.fetch.tinyfish.ai
```

All requests require an `X-API-Key` header. See [Authentication](/authentication).

***

## Request

```json theme={null}
{
  "urls": ["https://example.com"],
  "format": "html",
  "links": false,
  "image_links": false,
  "ttl": 3600,
  "per_url_timeout_ms": 45000
}
```

### Parameters

<ParamField type="string[]">
  URLs to fetch and extract. Maximum 10 URLs per request.

  All URLs must use `http` or `https`. Private IP addresses, localhost, and cloud metadata endpoints are rejected.
</ParamField>

<ParamField type="string">
  An optional short statement of **why** you are fetching these URLs — the underlying goal or task
  the content will be used for. Supplying the intent behind a fetch gives us additional signal to
  further inform and deliver better-quality results. When omitted, fetch behaves exactly as before.
  When supplied, the value must be non-empty (whitespace-only values are rejected). Maximum 2000
  characters. For example, `Compare pricing tiers across vendors for a procurement report`.
</ParamField>

<ParamField type="string">
  Output format for the `text` field in each result. One of:

  * `html` — semantic HTML
  * `markdown` — clean Markdown, recommended for LLMs (default)
  * `json` — structured document tree
</ParamField>

<ParamField type="boolean">
  When `true`, include all `<a href>` URLs found on the page in the `links` field.
</ParamField>

<ParamField type="boolean">
  When `true`, include all `<img src>` URLs found on the page in the `image_links` field.
</ParamField>

<ParamField type="boolean">
  When `true`, include the `src` URLs of `<iframe>` elements found on the page in the `iframe_links` field.

  Use this when a page embeds its main content in a frame (job boards, booking widgets, document viewers): fetch the returned URL to read the embedded content. Iframes that a page injects with JavaScript are only present when the page was rendered in a browser.
</ParamField>

<ParamField type="integer">
  Cache freshness tolerance in seconds.

  * Omit `ttl` to accept any cached entry.
  * Set `ttl` to `0` when you want a live fetch.
  * Set `ttl` to a positive integer to accept cached entries younger than that many seconds.
</ParamField>

<ParamField type="integer">
  Per-URL wall-clock timeout budget in milliseconds. Must be between `1` and `110000`.

  If a URL exceeds this budget, that URL returns a `timeout` error in `errors[]` while other URLs in the same request can still complete.
</ParamField>

<ParamField type="string">
  An ETag you saved from a prior fetch of this URL, forwarded verbatim as the `If-None-Match` header on the origin request. Single URL only — combining with a batch of URLs returns a `400`.
</ParamField>

<ParamField type="string">
  A `Last-Modified` value you saved from a prior fetch of this URL, forwarded verbatim as the `If-Modified-Since` header on the origin request. Single URL only — combining with a batch of URLs returns a `400`.
</ParamField>

<ParamField type="boolean">
  When `true`, include `etag` and `last_modified` on each result so you can store them and replay them on your next fetch of the same URL. Works with a single URL or a batch.
</ParamField>

<Note>
  Conditional requests are a stateless pass-through — Fetch does not store `etag` or `last_modified` for you. Save the values returned by `include_etag_and_last_modified` and replay them as `if_none_match` / `if_modified_since` on your next request to detect whether the page changed.
</Note>

<ParamField type="string[]">
  An array of CSS selectors (1–20 entries, each 1–1000 characters) that scopes extracted content (`text`, `links`, `image_links`) to elements matching **any** entry, concatenated in document order. Tag selectors cover semantic sections (`main`, `article`, `nav`); entries may themselves use CSS comma-grouping (`"main, footer"`). Standard CSS only — not XPath, Playwright `text=` locators, or glob patterns such as `*specificat*` (attribute matching like `[class*="price"]` is fine). Ids that start with a digit or contain dots are not valid `#id` selectors; use the attribute form instead (`[id="48599"]`).

  Selected content is returned verbatim, converted to the requested `format` (scripts and styles stripped) — automatic boilerplate removal is bypassed. Page-level metadata (`title`, `description`, `language`, `author`, `published_date`) still comes from the full document.

  If **some** entries match and others don't, the URL still succeeds with the matched content and the misses are listed in the result's `unmatched_selectors`. If **no** entry matches anything, that URL fails with the per-URL error code `selector_not_matched` — there is no silent full-page fallback — and the error carries `unmatched_selectors` plus `candidate_selectors` retry hints. Invalid CSS selector syntax is rejected with a `422`.
</ParamField>

<ParamField type="string[]">
  An array of CSS selectors (1–20 entries, each 1–1000 characters) for elements to remove before extraction. Applied **before** `include_selectors` scopes what remains, so it also prunes inside selected regions. Entries that match nothing are a no-op, never an error. Same syntax rules as `include_selectors`: standard CSS only, attribute form for digit-leading or dotted ids. Invalid CSS selector syntax is rejected with a `422`.
</ParamField>

<Note>
  Selectors are applied after the page is fetched — caching and routing are unchanged. URLs that resolve to direct PDF or CSV downloads have no HTML to scope, so sending `include_selectors` or `exclude_selectors` for them fails that URL with `selector_unsupported`.
</Note>

<ParamField type="object">
  Ask a question and get back the passages from each page that best answer it — ranked, and quoted word-for-word from the page. Requires `format: "markdown"`. Sub-fields below.
</ParamField>

<ParamField type="string">
  The question to answer from each page. Include the entity or topic in the query (e.g. "who founded Acme Corp", not "who founded this company") — retrieval works on vocabulary overlap with the page, and keyword-poor queries return empty results far more often.
</ParamField>

<ParamField type="integer">
  Maximum ranked passages per URL. Between `1` and `20`.
</ParamField>

<ParamField type="integer">
  Soft total-character budget across a URL's passages, between `100` and `20000`. Passages are added until the budget is reached, but the top-ranked passage is always returned even if it alone exceeds the budget.
</ParamField>

<ParamField type="boolean">
  By default a highlights request returns just the passages — the result's `text` field is `null`. Set `true` to also receive the full page markdown in `text`.
</ParamField>

<Info>
  **Beta:** Highlights is in beta and is enabled per-account — contact support to enable it for your account. Requests that include `highlights` from an account that isn't enabled return `403 FORBIDDEN`; requests without the field are unaffected.
</Info>

<Note>
  Highlights are computed for standard web pages. PDFs and other non-HTML documents are still fetched and their text returned, but `highlights` is not computed for them — the field is absent on those results.
</Note>

***

## Response

```json theme={null}
{
  "results": [...],
  "errors": [...]
}
```

### `results[]`

One entry per successfully fetched URL.

<ResponseField name="url" type="string">
  The original requested URL.
</ResponseField>

<ResponseField name="final_url" type="string">
  The URL after any redirects. May differ from `url`.
</ResponseField>

<ResponseField name="title" type="string | null">
  Page title, preferring `og:title` over `<title>`. `null` if not found.
</ResponseField>

<ResponseField name="description" type="string | null">
  Meta description, preferring `og:description` over `<meta name="description">`. `null` if not found.
</ResponseField>

<ResponseField name="language" type="string | null">
  Detected page language (e.g. `"en"`). `null` if undetectable.
</ResponseField>

<ResponseField name="author" type="string | null">
  Author from meta tags. `null` if not found.
</ResponseField>

<ResponseField name="published_date" type="string | null">
  Publication date, if detectable. `null` if not found.
</ResponseField>

<ResponseField name="text" type="string | object | null">
  Extracted page content. Format depends on the `format` request parameter:

  * `string` when `format` is `"html"` or `"markdown"`
  * `object` (document tree) when `format` is `"json"`
  * `null` on a highlights request, unless `highlights.include_full_page_text: true`
</ResponseField>

<ResponseField name="links" type="string[]">
  All `<a href>` URLs on the page, resolved to absolute URLs. Only present when `links: true` was requested.
</ResponseField>

<ResponseField name="image_links" type="string[]">
  All `<img src>` URLs on the page, resolved to absolute URLs. Only present when `image_links: true` was requested.
</ResponseField>

<ResponseField name="iframe_links" type="string[]">
  `<iframe src>` URLs on the page, resolved to absolute URLs and deduplicated, in document order. Only present when `iframe_links: true` was requested.
</ResponseField>

<ResponseField name="not_modified" type="boolean (optional)">
  Present and `true` only when the origin returned `304 Not Modified` for your `if_none_match` or `if_modified_since` header — the content is unchanged and you can skip re-processing. Omitted otherwise.
</ResponseField>

<ResponseField name="etag" type="string (optional)">
  The origin's current ETag validator. Save it and replay it as `if_none_match` on your next fetch of this URL. Present only when the origin sent one and you set `include_etag_and_last_modified`; omitted otherwise.
</ResponseField>

<ResponseField name="last_modified" type="string (optional)">
  The origin's current Last-Modified validator. Save it and replay it as `if_modified_since` on your next fetch of this URL. Present only when the origin sent one and you set `include_etag_and_last_modified`; omitted otherwise.
</ResponseField>

<ResponseField name="unmatched_selectors" type="string[] (optional)">
  Partial-miss report for `include_selectors`: the entries that matched no elements on this page. Present only when some (but not all) entries matched — the result still carries the matched content. Omitted when every entry matched. A total miss is reported as a `selector_not_matched` entry in `errors[]` instead.
</ResponseField>

<ResponseField name="highlights" type="object[] (optional)">
  Ranked verbatim passages answering the request's `highlights.query`, best first. Each entry is `{ "text": string, "rank": integer }`, with `rank` starting at `1`. Present only on highlights requests.

  An **empty array** means the page was fetched and analyzed and does not answer the query — a deliberate, calibrated signal, not a failure. A **missing field** on a highlights request means highlights could not be computed for this URL (rare and transient); the fetch itself still succeeded, and a retry is safe.
</ResponseField>

<ResponseField name="latency_ms" type="number | null">
  Time to fetch and extract this URL, in milliseconds. `null` if unavailable.
</ResponseField>

<ResponseField name="format" type="string">
  Output format used for the `text` field. Echoes the request `format` parameter (`"markdown"`, `"html"`, or `"json"`).
</ResponseField>

<Note>
  Fields that could not be extracted (`title`, `description`, `language`, `author`, `published_date`) are returned as `null`.
</Note>

### `errors[]`

One entry per URL that could not be fetched. Always present, may be empty. Per-URL failures do not affect the rest of the batch.

<ResponseField name="url" type="string">
  The URL that failed.
</ResponseField>

<ResponseField name="error" type="string">
  Structured error code identifying the failure type. One of: `target_http_error`, `page_not_found`, `target_unreachable`, `timeout`, `bot_blocked`, `empty_content`, `login_required`, `content_too_large`, `invalid_url`, `invalid_redirect_url`, `proxy_error`, `conditional_unsupported`, `selector_not_matched`, `selector_unsupported`.
</ResponseField>

<ResponseField name="status" type="number (optional)">
  Upstream HTTP status code. Present when `error` is `target_http_error` or `page_not_found`.
</ResponseField>

<ResponseField name="unmatched_selectors" type="string[] (optional)">
  The `include_selectors` entries that matched no elements on the fetched page. Present only when `error` is `selector_not_matched`.
</ResponseField>

<ResponseField name="candidate_selectors" type="string[] (optional)">
  Cheap retry hints (max 10), present only when `error` is `selector_not_matched`: landmark tags found on the page (e.g. `main`, `article`, `nav`) plus `#id` selectors of content-heavy elements. Agents can retry the fetch with `include_selectors` drawn from this list.
</ResponseField>

## SDK Methods

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  result = client.fetch.get_contents(
      urls=["https://www.tinyfish.ai/"],
      format="markdown",
  )
  for page in result.results:
      print(page.title, "→", page.text[:100])
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const result = await client.fetch.getContents({
    urls: ["https://www.tinyfish.ai/"],
    format: "markdown",
  });
  result.results.forEach((page) => console.log(page.title, "→", page.text.slice(0, 100)));
  ```
</CodeGroup>

***

## Error Codes

HTTP-level errors apply to the entire request.

| Status | Meaning |
| - | - |
| `400` | Invalid request — missing `urls`, too many URLs (max 10), bad parameter value, `if_none_match`/`if_modified_since` combined with a batch of URLs, or `highlights` combined with a non-markdown `format` |
| `401` | Missing or invalid API key |
| `402` | Daily free allowance used and wallet balance is zero or below (`INSUFFICIENT_CREDITS`) — add funds at the [wallet page](https://agent.tinyfish.ai/wallet) or wait for the daily reset. `FREE_ALLOWANCE_EXHAUSTED` when the allowance is used and the product does not charge the wallet (beta) — wait for the daily reset |
| `403` | `highlights` sent from an account that isn't beta-enabled — contact support for access |
| `422` | Invalid CSS selector syntax in `include_selectors` / `exclude_selectors` |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `503` | Fetch service or rate limiting unavailable — retry with backoff |

Per-URL errors appear in `errors[]` alongside a `200` response. The `error` field is one of these codes:

| Error code | `status` field | Meaning |
| - | - | - |
| `target_http_error` | HTTP status code (e.g. `403`, `500`) | Target server returned a non-2xx HTTP response other than 404/410 |
| `page_not_found` | `404` or `410` | Target URL does not exist (HTTP 404 Not Found or 410 Gone) |
| `target_unreachable` | — | Connection refused, TLS failure, DNS failure, or other network error |
| `timeout` | — | Page did not finish loading within the request deadline |
| `bot_blocked` | — | Site returned a bot-protection challenge (Cloudflare, Incapsula) |
| `empty_content` | — | Browser returned HTML but no extractable text found |
| `login_required` | — | Target redirected to a login or account wall — the page is not served to anonymous sessions, so retrying without credentials won't help |
| `content_too_large` | — | Document exceeds the 20MB size limit for generic documents (PDF and CSV have their own 50MB budgets); not retried in the browser |
| `invalid_url` | — | URL rejected before fetch (private IP, invalid scheme, disallowed host) |
| `invalid_redirect_url` | — | Redirect target rejected before fetch (private IP or disallowed host) |
| `proxy_error` | — | Proxy tunnel failed — site may be reachable directly |
| `conditional_unsupported` | — | URL requires browser rendering — conditional requests (`if_none_match` / `if_modified_since`) are supported on the fast path only |
| `selector_not_matched` | — | No elements matching any `include_selectors` entry remained after `exclude_selectors` was applied (total miss); the error carries `unmatched_selectors` + `candidate_selectors` retry hints. A partial miss is not an error — it's reported on the result's `unmatched_selectors` |
| `selector_unsupported` | — | `include_selectors` / `exclude_selectors` sent for a URL that resolves to a direct PDF/CSV download — no HTML to scope |

<Note>
  Per-URL fetch failures are **not** HTTP errors. They appear as entries in `errors[]` alongside a `200` response.
</Note>

<Note>
  Each URL has a **110-second backend timeout**. If the page doesn't respond within 110 seconds, that URL returns a `timeout` error in `errors[]` while the rest of the batch continues. Requests are also subject to a **120-second CDN ceiling** for the full batch. Set your client-side timeout to at least **150 seconds** to receive CDN timeout errors cleanly.
</Note>

***

## Supported Content Types

| Content Type | Behavior |
| - | - |
| HTML | Full text extraction with formatting |
| PDF | Text content extracted |
| JSON | Raw JSON returned as text |
| Plain text | Full text returned |
| Images (PNG, JPG) | Not supported — returns an error indicating no extractable content |

***

## Usage Endpoint

Retrieve a paginated history of your fetch operations.

```
GET https://api.fetch.tinyfish.ai/usage
```

All requests require an `X-API-Key` header. See [Authentication](/authentication).

### Query Parameters

<ParamField type="string (ISO 8601)">
  Filter results created after this timestamp. Example: `2026-01-01T00:00:00Z`
</ParamField>

<ParamField type="string (ISO 8601)">
  Filter results created before this timestamp. Example: `2026-02-01T00:00:00Z`
</ParamField>

<ParamField type="string">
  Filter by result status. One of: `completed`, `failed`.
</ParamField>

<ParamField type="integer">
  Maximum number of items per page. Range: 1-1000.
</ParamField>

<ParamField type="integer">
  Page number for pagination.
</ParamField>

### Response

```json theme={null}
{
  "items": [...],
  "total": 42,
  "limit": 100,
  "page": 1,
  "total_pages": 1,
  "has_more": false
}
```

### `items[]`

<ResponseField name="id" type="string">
  Unique identifier for the fetch result.
</ResponseField>

<ResponseField name="url" type="string">
  The original requested URL.
</ResponseField>

<ResponseField name="final_url" type="string">
  The URL after any redirects.
</ResponseField>

<ResponseField name="title" type="string | null">
  Page title, if detected.
</ResponseField>

<ResponseField name="description" type="string | null">
  Meta description, if detected.
</ResponseField>

<ResponseField name="language" type="string | null">
  Detected page language (e.g. `"en"`).
</ResponseField>

<ResponseField name="author" type="string | null">
  Page author, if detected.
</ResponseField>

<ResponseField name="published_date" type="string | null">
  Published date, if detected.
</ResponseField>

<ResponseField name="format" type="string">
  The format used for extraction: `markdown`, `html`, or `json`.
</ResponseField>

<ResponseField name="status" type="string">
  Result status: `completed` or `failed`.
</ResponseField>

<ResponseField name="request_origin" type="string">
  Where the request originated: `api`, `cli`, `python-sdk`, `js-sdk`, `mcp`, etc.
</ResponseField>

<ResponseField name="request_id" type="string | null">
  The request ID that grouped this URL with others in a batch.
</ResponseField>

<ResponseField name="text_length" type="integer | null">
  Length of the extracted text content in characters. The full text is not included in usage responses.
</ResponseField>

<ResponseField name="links_count" type="integer">
  Number of links found on the page.
</ResponseField>

<ResponseField name="image_links_count" type="integer">
  Number of image links found on the page.
</ResponseField>

<ResponseField name="latency_ms" type="number | null">
  Time taken to fetch and extract the page, in milliseconds.
</ResponseField>

<ResponseField name="not_modified" type="boolean (optional)">
  Present and `true` only when that fetch was a conditional request that returned `304 Not Modified`. Omitted otherwise.
</ResponseField>

<ResponseField name="etag" type="string (optional)">
  The origin's ETag validator captured at fetch time. Present only when `include_etag_and_last_modified` was set on that request and the origin returned one; omitted otherwise.
</ResponseField>

<ResponseField name="last_modified" type="string (optional)">
  The origin's Last-Modified validator captured at fetch time. Present only when `include_etag_and_last_modified` was set on that request and the origin returned one; omitted otherwise.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when the fetch was executed.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the fetch failed. `null` for successful fetches.
</ResponseField>

### Error Codes

| Status | Meaning |
| - | - |
| `400` | Invalid query parameters |
| `401` | Missing or invalid API key |
| `500` | Internal server error |

***

## Rate Limits

Limits apply per API key, measured in URLs per minute across all requests. Accounts default to 150 URLs / minute. When the limit is exceeded, the API returns `HTTP 429`.

***

## Billing

Fetch is free up to 1,000 URLs per day, counted per successfully fetched URL; the allowance resets at 00:00 UTC. Beyond it, requests need a positive wallet balance: with a balance of zero or below the API returns `HTTP 402` with code `INSUFFICIENT_CREDITS` until you add funds or the allowance resets. After a top-up, allow a few seconds for the balance to apply. A product that does not charge the wallet (beta) returns `FREE_ALLOWANCE_EXHAUSTED` instead once its allowance is used; only the daily reset lifts it.

***

## Related

<CardGroup>
  <Card title="Fetch Overview" icon="bolt" href="/fetch-api">
    First request, response shape, and product routing
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Full list of API error codes
  </Card>
</CardGroup>


# For Coding Agents
Source: https://docs.tinyfish.ai/for-coding-agents

Single-page TinyFish context for Claude, Codex, Cursor, and other 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.

<Note>
  For complete API reference in a single file, use [llms-full.txt](https://docs.tinyfish.ai/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.
</Note>

## MCP Server (Recommended for AI Assistants)

If you're running inside an MCP-compatible host (Codex, Claude Code, OpenCode, Command Code, Claude Desktop, Cursor, Windsurf, ChatGPT), connect via MCP instead of the REST API. Most hosts sign in with OAuth and need no API key management; Command Code connects with a TinyFish API key.

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
    ```
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
    ```
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    opencode mcp add tinyfish --url https://agent.tinyfish.ai/mcp
    ```
  </Tab>

  <Tab title="Command Code">
    ```bash theme={null}
    npx -y @tiny-fish/cli@latest connect command-code
    ```
  </Tab>

  <Tab title="ChatGPT">
    ```text theme={null}
    https://agent.tinyfish.ai/mcp/chatgpt
    ```
  </Tab>
</Tabs>

See the [MCP Integration guide](/mcp-integration) for all supported clients and available tools.

## Install the SDK

<CodeGroup>
  ```bash Python theme={null}
  pip install -U tinyfish
  ```

  ```bash TypeScript theme={null}
  npm install @tiny-fish/sdk@latest
  ```
</CodeGroup>

| 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](https://agent.tinyfish.ai/api-keys)):

```bash theme={null}
export TINYFISH_API_KEY="your_api_key_here"
```

Both SDKs read `TINYFISH_API_KEY` from the environment automatically. See [Authentication](/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](/agent-api/reference) |
| Search | You want ranked web results for a query | [Search overview](/search-api) |
| Fetch | You want extracted page content from one or more URLs | [Fetch overview](/fetch-api) |
| Browser | You want a remote browser session for direct Playwright/CDP control | [Browser overview](/browser-api) |

### 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](/agent-api/browser-context-profiles), 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.

<Steps>
  <Step title="Create and set up a profile">
    Use the [Browser Context Profiles API](/agent-api/browser-context-profiles) 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.
  </Step>

  <Step title="Run with saved state">
    Pass `use_profile: true` to use the default profile, or add `profile_id` for a specific profile.
  </Step>

  <Step title="Repair stale sessions with Vault">
    For long-lived workflows, pair profiles with `use_vault: true` so TinyFish can sign in again when cookies expire.
  </Step>
</Steps>

<CodeGroup>
  ```python Python theme={null}
  result = client.agent.run(
      url="https://app.example.com/dashboard",
      goal="Summarize the account health dashboard.",
      use_profile=True,
      use_vault=True,
  )
  ```

  ```typescript TypeScript theme={null}
  const run = await client.agent.run({
    url: "https://app.example.com/dashboard",
    goal: "Summarize the account health dashboard.",
    use_profile: true,
    use_vault: true,
  });
  ```
</CodeGroup>

`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`:

<CodeGroup>
  ```python Python theme={null}
  result = client.agent.run(
      url="https://app.example.com/dashboard",
      goal="Summarize the latest invoice, including the amount due and payment deadline.",
      use_profile=True,
      profile_id="prof_abc123def4567890",
  )
  ```

  ```typescript TypeScript theme={null}
  const run = await client.agent.run({
    url: "https://app.example.com/dashboard",
    goal: "Summarize the latest invoice, including the amount due and payment deadline.",
    use_profile: true,
    profile_id: "prof_abc123def4567890",
  });
  ```
</CodeGroup>

## SDK Examples

### Agent — Streaming (Recommended)

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
    }
  }
  ```
</CodeGroup>

### Agent — Synchronous

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

### Search

<CodeGroup>
  ```python Python theme={null}
  result = client.search.query("web automation tools", location="US", language="en")
  print(result)
  ```

  ```typescript TypeScript theme={null}
  const result = await client.search.query({
    query: "web automation tools",
    location: "US",
    language: "en",
  });
  console.log(result);
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  result = client.fetch.get_contents(urls=["https://www.tinyfish.ai/"])
  print(result)
  ```

  ```typescript TypeScript theme={null}
  const result = await client.fetch.getContents({
    urls: ["https://www.tinyfish.ai/"],
  });
  console.log(result);
  ```
</CodeGroup>

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:

<CodeGroup>
  ```python Python theme={null}
  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),
  )
  ```

  ```typescript TypeScript theme={null}
  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,
    },
  });
  ```
</CodeGroup>

## 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.

<Tip>
  See the full [Prompting Guide](/prompting-guide) for tested patterns, templates, and examples.
</Tip>

## 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.

<Accordion title="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

  ```bash theme={null}
  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

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

  ### Fetch

  ```bash theme={null}
  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

  ```bash theme={null}
  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"}'
  ```
</Accordion>

## What to Read Next

<CardGroup>
  <Card title="Agent reference" icon="sparkles" href="/agent-api/reference">
    Goal-based automation, endpoint choice, runs, profiles, and proxies
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>

  <Card title="Search overview" icon="magnifying-glass" href="/search-api">
    Search query parameters and result shape
  </Card>

  <Card title="Fetch overview" icon="bolt" href="/fetch-api">
    Fetch multiple URLs and choose output formats
  </Card>

  <Card title="Browser overview" icon="browser" href="/browser-api">
    Create a remote browser session and connect via CDP
  </Card>

  <Card title="Examples" icon="code" href="/examples/scraping">
    Copy-paste examples for common workflows
  </Card>

  <Card title="llms-full.txt" icon="file-lines" href="https://docs.tinyfish.ai/llms-full.txt">
    Complete API reference in a single file (218KB)
  </Card>
</CardGroup>


# TinyFish Developer Documentation
Source: https://docs.tinyfish.ai/index

Choose the right TinyFish API, authenticate quickly, and start integrating faster

TinyFish gives you five public API surfaces: Agent, Research, Search, Fetch, and Browser. This docs site is organized to help you pick the right one quickly, authenticate once, and move straight to the examples or reference you need.

Search and Fetch are free within a daily allowance. Agent, Research, and Browser draw from your wallet as they run.

## Start Here

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Run your first integration in minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Set up API keys and MCP auth
  </Card>

  <Card title="For Coding Agents" icon="robot" href="/for-coding-agents">
    Single-page context for Claude, Codex, and Cursor
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Debug auth, rate limits, and run failures
  </Card>
</CardGroup>

## Choose the Right API

<CardGroup>
  <Card title="Agent API" icon="sparkles" href="/agent-api">
    Use natural-language goals to automate workflows on real sites
  </Card>

  <Card title="Research API" icon="telescope" href="/research-api">
    Produce source-backed reports with configurable depth and live progress
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/search-api">
    Get structured ranked web results for a query
  </Card>

  <Card title="Fetch API" icon="bolt" href="/fetch-api">
    Fetch URLs and extract clean page content
  </Card>

  <Card title="Browser API" icon="browser" href="/browser-api">
    Create a remote browser session for direct Playwright/CDP control
  </Card>
</CardGroup>

## Canonical Endpoints

| Product | Canonical endpoint |
| - | - |
| Agent | `https://agent.tinyfish.ai/v1/automation/...` |
| Research | `POST https://agent.tinyfish.ai/v1/automation/run-research` |
| Search | `GET https://api.search.tinyfish.ai` |
| Fetch | `POST https://api.fetch.tinyfish.ai` |
| Browser | `POST https://api.browser.tinyfish.ai` |

## Learn the Basics

<CardGroup>
  <Card title="Agent Endpoints" icon="plug" href="/key-concepts/endpoints">
    Pick `/run`, `/run-async`, or `/run-sse`
  </Card>

  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Understand lifecycle, polling, and statuses
  </Card>

  <Card title="Goals" icon="bullseye" href="/key-concepts/goals">
    Write instructions that produce reliable results
  </Card>

  <Card title="Browser Context Profiles" icon="window" href="/key-concepts/browser-context-profiles">
    Keep logged-in state across runs
  </Card>

  <Card title="Browser Profiles" icon="shield" href="/key-concepts/browser-profiles">
    Choose lite vs stealth
  </Card>

  <Card title="Proxies" icon="globe" href="/key-concepts/proxies">
    Route runs through supported countries
  </Card>

  <Card title="MCP Integration" icon="robot" href="/mcp-integration">
    Connect TinyFish to Claude and other assistants
  </Card>
</CardGroup>


# Dify
Source: https://docs.tinyfish.ai/integrations/dify

Use TinyFish Web Agent as a tool in Dify AI workflows and agents

## Overview

The TinyFish Web Agent plugin for [Dify](https://dify.ai) lets you add AI-powered web automation to any Dify workflow or agent. Navigate websites, extract structured data, fill forms, and complete multi-step browser tasks — all using natural language.

## Setup

<Steps>
  <Step title="Install the plugin">
    On the Dify platform, go to the [Plugin Marketplace](https://docs.dify.ai/plugins/quick-start/install-plugins#marketplace) and install the **TinyFish Web Agent** tool.
  </Step>

  <Step title="Get your API key">
    Visit the [TinyFish Dashboard](https://agent.tinyfish.ai/api-keys) and generate an API key.
  </Step>

  <Step title="Authorize the plugin">
    In Dify, go to **Plugins > TinyFish Web Agent > To Authorize** and enter your API key.
  </Step>
</Steps>

## Available Tools

| Tool | Description |
| - | - |
| **Run Synchronously** | Execute browser automation and wait for the result in a single response. |
| **Run Asynchronously** | Start browser automation and return a `run_id` immediately. Use with **Get Run** to poll for results. |
| **Run with SSE Streaming** | Execute browser automation with real-time progress updates via Server-Sent Events. |
| **List Runs** | List previous automation runs, with optional status filtering and pagination. |
| **Get Run** | Get detailed information about a specific automation run by its ID. |

## Using in Workflows

1. Add TinyFish Web Agent's **Run Asynchronously** tool to your pipeline.
2. Configure input variables (URL and goal) in the tool's UI.
3. Run the pipeline to extract data from any web page.

## Using with Agents

1. Add all TinyFish Web Agent tools to your Agent app.
2. Prompt the Agent to perform web automations using natural language. The Agent will choose the appropriate tool automatically.

**Example prompts:**

* `"Extract the blog post titles and authors from https://example.com/blog"`
* `"Go to https://example.com/pricing and extract all plan names and prices"`
* `"List my recent automation runs that have completed"`

## API Tool Config (Manual Setup)

If you need to configure TinyFish as a custom API tool in Dify instead of using the plugin, use this endpoint and auth pattern:

```json theme={null}
{
  "url": "https://agent.tinyfish.ai/v1/automation/run",
  "method": "POST",
  "headers": {
    "X-API-Key": "<your_tinyfish_api_key>"
  },
  "body": {
    "url": "{url}",
    "goal": "{goal}"
  }
}
```

In Dify's custom tool configuration, set the authentication type to **API Key** with the header name `X-API-Key`.

## Resources

* [Dify Plugin Marketplace](https://docs.dify.ai/plugins/quick-start/install-plugins#marketplace)
* [TinyFish Web Agent API Docs](/quick-start)
* [GitHub: tinyfish-web-agent-integrations](https://github.com/tinyfish-io/tinyfish-web-agent-integrations)


# n8n
Source: https://docs.tinyfish.ai/integrations/n8n

Use TinyFish Web Agent as a node in n8n automation workflows

## Overview

The TinyFish Web Agent node for [n8n](https://n8n.io) lets you add AI-powered web automation to any n8n workflow. Browse any website using an AI-powered remote browser to extract structured data, fill forms, navigate multi-step workflows, or interact with JavaScript-rendered pages.

## Quick Start

### Prerequisites

* n8n instance (self-hosted or cloud)
* TinyFish Web Agent API key ([get one here](https://agent.tinyfish.ai/api-keys))
* Google account (for the Google Sheets part of the tutorial)

### Setting Up the TinyFish Node

<Steps>
  <Step title="Install the community node">
    In n8n, go to **Settings > Community Nodes**. Search for `n8n-nodes-tinyfish` and click **Install**.
  </Step>

  <Step title="Add TinyFish Web Agent to your workflow">
    In any workflow, click the **+** button to open the node panel. Search for **TinyFish Web Agent** and click it to add it to your canvas.

    <img alt="n8n node panel showing the TinyFish Web Agent node" />
  </Step>

  <Step title="Create your TinyFish credentials">
    Click **Credentials > New Credential** and select **TinyFish Web Agent API**. Paste your [API key](https://agent.tinyfish.ai/api-keys) and click **Save**.

    <img alt="TinyFish Web Agent credentials in n8n" />
  </Step>
</Steps>

## Your First Workflow with TinyFish

In this tutorial, we'll build a workflow that scrapes the top stories from Hacker News (news.ycombinator.com) and writes them to a Google Sheet — no code required. The final workflow looks like this:

<img alt="Complete n8n workflow: Trigger → TinyFish Web Agent → Split Out → Google Sheets" />

### Scraping Hacker News to Google Sheets

#### Step 1: Add a Manual Trigger

1. Create a new workflow in n8n.
2. Add a **Manual Trigger** node ("When clicking 'Execute workflow'").

This lets you run the workflow on demand. You can swap this for a **Schedule Trigger** later to run it automatically (e.g., every hour).

#### Step 2: Configure TinyFish Web Agent

1. Add a **TinyFish Web Agent** node after the trigger.
2. Select your TinyFish credentials.
3. Set **Operation** to **Run (Sync)**.
4. Set **URL** to `https://news.ycombinator.com`.
5. Set **Goal** to:

```
Extract the top 10 stories. For each return a JSON object with exactly
these keys: title, url, points, comment_count. Return the result as a
JSON object with a single key "stories" containing the array.
```

<img alt="TinyFish Web Agent node configuration with Hacker News URL and goal" />

<Tip>
  Always specify the exact JSON keys you want in your goal. This ensures the output is consistent and easy to map to downstream nodes.
</Tip>

#### Step 3: Split the Results

TinyFish returns a single JSON object containing the `stories` array. To write each story as a separate row in Google Sheets, we need to split it into individual items.

1. Add a **Split Out** node after TinyFish Web Agent.
2. Set **Fields To Split Out** to `result.stories`.
3. Set **Include** to **No Other Fields**.

<img alt="Split Out node configured to split result.stories" />

#### Step 4: Write to Google Sheets

1. Add a **Google Sheets** node after Split Out.
2. Connect your **Google Sheets account** credentials.
3. Set **Resource** to **Sheet Within Document**.
4. Set **Operation** to **Append Row**.
5. Select your target **Document** and **Sheet**.
6. Set **Mapping Column Mode** to **Map Each Column Manually**.
7. Map the columns:

| Sheet Column | Value |
| - | - |
| Title | `{{ $json.title }}` |
| URL | `{{ $json.url }}` |
| Points | `{{ $json.points }}` |
| Comment Count | `{{ $json.comment_count }}` |

<img alt="Google Sheets node with column mappings for title, url, points, and comment_count" />

#### Step 5: Run It

1. Click **Execute Workflow** to test.
2. Check your Google Sheet — you should see 10 rows of Hacker News stories with titles, URLs, points, and comment counts.

<Note>
  The first run may take 30–60 seconds as TinyFish navigates and extracts from the live page. Subsequent workflow executions will be similarly timed since each run performs a fresh browser session.
</Note>

### Next Steps

* Swap the Manual Trigger for a **Schedule Trigger** to run on a recurring schedule
* Add a **Filter** node to only capture stories above a certain point threshold
* Use **Run (SSE Streaming)** instead of Run (Sync) for longer-running extractions
* Try scraping other sites — TinyFish works on any website, including bot-protected pages

## HTTP Request Node (Alternative)

If you prefer not to install the community node, you can use n8n's built-in **HTTP Request** node with this configuration:

```json theme={null}
{
  "url": "https://agent.tinyfish.ai/v1/automation/run",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{$credentials.tinyfishApiKey}}",
    "Content-Type": "application/json"
  },
  "body": {
    "url": "{{$json.targetUrl}}",
    "goal": "{{$json.goal}}"
  }
}
```

Set up a **Header Auth** credential with name `X-API-Key` and your TinyFish API key, then reference it in the HTTP Request node.

## Resources

* [n8n Community Nodes Docs](https://docs.n8n.io/integrations/community-nodes/)
* [TinyFish Web Agent API Docs](/quick-start)
* [TinyFish Integrations GitHub](https://github.com/tinyfish-io/tinyfish-web-agent-integrations)


# Browser Context Profiles
Source: https://docs.tinyfish.ai/key-concepts/browser-context-profiles

Persist logged-in browser state across TinyFish runs

Stop logging in from scratch on every run.

Browser Context Profiles let TinyFish save browser state — cookies, local storage, and session storage — and
reuse it later. Recurring automations can start where a real returning user would: already signed in,
with the right workspace, preferences, and site context loaded.

<Note>
  **Browser Context Profiles are not Browser Profiles.**
  [Browser Profiles](/key-concepts/browser-profiles) choose the runtime mode with
  `browser_profile: "lite" | "stealth"`. Browser Context Profiles save session state across runs.
</Note>

<CardGroup>
  <Card title="Use the API" icon="code" href="/agent-api/browser-context-profiles">
    Create and run with Browser Context Profiles programmatically
  </Card>

  <Card title="Vault Credentials" icon="vault" href="/key-concepts/credentials">
    Add stale-session repair
  </Card>
</CardGroup>

## The flow

<CardGroup>
  <Card title="1. Set up once" icon="right-to-bracket">
    Open a setup browser, sign in, and save the session.
  </Card>

  <Card title="2. Run many times" icon="repeat">
    Reuse saved state so recurring runs start authenticated.
  </Card>

  <Card title="3. Repair when stale" icon="rotate">
    Add Vault so TinyFish can log back in if the session expires.
  </Card>
</CardGroup>

## Set up a Browser Context Profile

<Tabs>
  <Tab title="Dashboard">
    1. Go to **Browser Context Profiles** in the TinyFish dashboard.
    2. Click **Create Profile**.
    3. Name the profile.
    4. Optional: mark it as the default profile.
    5. Optional: choose a proxy location for the profile.
    6. Click **Create and set up**.
    7. Sign in to the target site in the setup browser.
    8. Save the setup session.

    <Tip>
      Use one Browser Context Profile per account or environment, such as `Salesforce Production` and
      `Salesforce Sandbox`.
    </Tip>
  </Tab>

  <Tab title="API">
    Create the profile, start a setup session, connect your own Playwright/Puppeteer/CDP controller
    to `cdp_url`, sign in, then save it with the returned `session_id`. The hosted setup UI is
    only a manual helper; API setup is controlled through these endpoints.

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/profiles \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Salesforce Production",
        "set_as_default": true
      }'
    ```

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/setup-session \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "url": "https://app.example.com/login" }'
    ```

    The setup-session response includes `session_id`, `cdp_url`, `base_url`, `timeout_seconds`, and
    `expires_at`. Use `cdp_url` for Playwright/Puppeteer/CDP. Use `base_url` only for TinyFish HTTP
    session endpoints such as `/pages`. After signing in, save the setup browser state:

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/profiles/prof_abc123def4567890/save \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "session_id": "sess_123" }'
    ```

    <Card title="Browser Context Profiles API" icon="code" href="/agent-api/browser-context-profiles">
      Full setup, upload, update, and cleanup reference
    </Card>
  </Tab>
</Tabs>

## Use a Browser Context Profile

<Tabs>
  <Tab title="Playground">
    1. Open the Playground.
    2. Click the profile icon in the toolbar.
    3. Turn on **Use Browser Context Profile**.
    4. Choose a profile, or use your default profile.
    5. Run the automation.

    If no profile exists, click **Go to Browser Context Profiles** to create one first.
  </Tab>

  <Tab title="API: default profile">
    Use your default Browser Context Profile with `use_profile: true`:

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/automation/run \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://app.example.com/dashboard",
        "goal": "Open the dashboard and summarize the latest alerts",
        "use_profile": true
      }'
    ```
  </Tab>

  <Tab title="API: specific profile">
    Target a specific Browser Context Profile by ID:

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/automation/run-async \
      -H "X-API-Key: $TINYFISH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "url": "https://app.example.com/dashboard",
        "goal": "Export the weekly usage report",
        "use_profile": true,
        "profile_id": "prof_abc123def4567890"
      }'
    ```
  </Tab>
</Tabs>

## Manage Browser Context Profiles

On the **Browser Context Profiles** page, you can:

* Rename Browser Context Profiles
* Set a default Browser Context Profile
* Copy a profile ID
* View saved domains
* Set or clear a profile proxy location
* Upload cookies manually
* Delete individual domains
* Delete Browser Context Profiles

<Note>
  You cannot delete your only active profile. Create another profile first.
</Note>

## Browser Context Profiles + Vault

The best authenticated setup is Browser Context Profiles plus [Vault Credentials](/key-concepts/credentials).

<CardGroup>
  <Card title="Browser Context Profiles" icon="window">
    Keep persistent logged-in browser state across runs.
  </Card>

  <Card title="Vault" icon="vault">
    Provide matching credentials when a login form appears.
  </Card>

  <Card title="Together" icon="rotate">
    Repair stale sessions instead of logging in cold every run.
  </Card>
</CardGroup>

Use this pairing for authenticated workflows where sessions expire over time. The Browser Context Profile starts
the run with saved state. If that state has gone stale and a matching Vault credential is available,
TinyFish can sign in again and refresh the profile state for future runs.

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Check the dashboard and summarize anything urgent",
  "use_profile": true,
  "use_vault": true
}
```

<Steps>
  <Step title="Start with saved state">
    TinyFish opens the site with the cookies and storage saved in the Browser Context Profile.
  </Step>

  <Step title="Detect stale login">
    If the site asks for login again, the agent proceeds through the normal login flow.
  </Step>

  <Step title="Repair with Vault">
    When `use_vault: true` is set and a matching credential exists, TinyFish can use it to restore
    the session and keep future profile runs healthy.
  </Step>
</Steps>

<Tip>
  Start with Browser Context Profiles for persistence, then add Vault for stale-session repair. This is usually
  more reliable than asking the agent to log in from scratch on every run.
</Tip>

## When to use Browser Context Profiles

| Use Browser Context Profiles when... | Start fresh when... |
| - | - |
| A run should stay logged in | The site is public or anonymous |
| You repeat the same workflow often | Browser history or cookies would bias the result |
| Logging in every run is slow, fragile, or MFA-heavy | The task must prove it can work from a blank browser |
| The account has site preferences, workspace context, or saved filters | You are testing a first-time visitor flow |

## Proxies and stealth mode

Browser Context Profiles answer “what state should this run start with?” Proxies and Browser Profiles answer
“how should the browser connect and behave?”

| Capability | Use it for |
| - | - |
| Browser Context Profile | Reusing saved cookies and storage |
| Profile proxy location | Keeping a logged-in session tied to one country |
| Per-run proxy | Choosing a location for one run when the profile has no proxy location |
| `browser_profile: "stealth"` | Using the anti-detection browser runtime |

Choose a profile proxy location when a logged-in session should consistently come from the same
country. Leave it blank when location should be decided per run with [Proxies](/key-concepts/proxies).
Use [Browser Profiles](/key-concepts/browser-profiles) when you need `lite` or `stealth` runtime mode.

## Limits and expectations

| Limit | What to expect |
| - | - |
| Account scope | Browser Context Profiles are scoped to your TinyFish account and API key owner |
| Session expiry | Sites can still expire cookies, require MFA, or force re-authentication |
| CAPTCHA | Browser Context Profiles reduce repeated-login friction, but do not solve reCAPTCHA or hCaptcha |
| Fresh-browser tasks | Disable `use_profile` when the run should start with no saved state |

## Next steps

<CardGroup>
  <Card title="Browser Context Profiles API" icon="code" href="/agent-api/browser-context-profiles">
    Manage profiles programmatically
  </Card>

  <Card title="Vault Credentials" icon="vault" href="/key-concepts/credentials">
    Add stale-session repair
  </Card>

  <Card title="Browser Profiles" icon="browser" href="/key-concepts/browser-profiles">
    Choose lite or stealth runtime mode
  </Card>
</CardGroup>


# Browser Profiles
Source: https://docs.tinyfish.ai/key-concepts/browser-profiles

Configure browser behavior for different sites

Browser profiles let you configure how TinyFish Web Agent's browser behaves for different sites.

## The Two Profiles

| Profile | Description |
| - | - |
| `lite` | Standard Chromium browser |
| `stealth` | Modified browser with anti-detection |

***

## Lite (Default)

Use for standard websites without bot protection.

```typescript theme={null}
{
  url: "https://example.com",
  goal: "Extract product data",
  browser_profile: "lite"
}
```

Lite is the default. If you don't specify a profile, TinyFish Web Agent uses lite.

***

## Stealth

Use for sites with Cloudflare, DataDome, CAPTCHAs, or other bot protection.

```typescript theme={null}
{
  url: "https://protected-site.com",
  goal: "Extract product data",
  browser_profile: "stealth"
}
```

Stealth mode includes anti-fingerprinting techniques that help bypass detection systems.

***

## When to Use Each

<Tabs>
  <Tab title="Use Lite">
    * Standard websites
    * Internal tools and dashboards
    * Sites you control
    * When speed matters
  </Tab>

  <Tab title="Use Stealth">
    * Sites showing CAPTCHAs
    * Getting "Access Denied" errors
    * Sites behind Cloudflare or similar
    * E-commerce sites with bot protection
  </Tab>
</Tabs>

***

## Limitations

Stealth mode helps bypass detection but has limits:

| Limitation | Notes |
| - | - |
| CAPTCHAs | Cannot solve reCAPTCHA or similar challenges |
| Infinite scroll | May not scroll to load all content automatically |
| Login persistence | Each run starts fresh, no session cookies carried over |

***

## Combining with Proxies

For maximum anti-detection, combine stealth mode with a proxy:

```typescript theme={null}
{
  url: "https://protected-site.com",
  goal: "Extract product data",
  browser_profile: "stealth",
  proxy_config: {
    enabled: true,
    country_code: "US"
  }
}
```

Learn more about proxies in the [Proxies](/key-concepts/proxies) page.

***

## Related

<CardGroup>
  <Card title="Proxies" icon="globe" href="/key-concepts/proxies">
    Geographic routing for requests
  </Card>

  <Card title="Endpoints" icon="plug" href="/key-concepts/endpoints">
    Choose how to call the API
  </Card>

  <Card title="Anti-Bot Guide" icon="shield" href="/anti-bot-guide">
    Diagnose and bypass bot detection on protected websites
  </Card>
</CardGroup>


# Vault Credentials
Source: https://docs.tinyfish.ai/key-concepts/credentials

How TinyFish uses your password manager credentials to log into websites during runs

When your vault is connected, you select which credentials TinyFish uses for each run. The AI agent handles navigation and identifies login forms. TinyFish fills in the actual credentials securely, without the agent ever seeing your passwords.

***

## Using the Playground

<Steps>
  <Step title="Open the vault selector">
    Click the lock icon in the playground toolbar.

    <img alt="Playground toolbar with vault lock icon in gray state" />
  </Step>

  <Step title="Select credentials">
    Check the credentials you want to use for the run. Items are grouped by provider and vault name, and you can use **Select all** or **Deselect all**.

    <img alt="Vault access popover with credentials grouped by provider and checkboxes" />
  </Step>

  <Step title="Run your automation">
    Write your goal, then click **Run**. TinyFish handles login during the run when a matching site requires it.

    <img alt="Playground with vault icon showing credential count badge and goal filled in" />
  </Step>
</Steps>

<Note>
  Your credential selections persist across sessions.
</Note>

***

## Using the API

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  # Use all vault credentials for the run
  response = client.agent.run(
      url="https://www.linkedin.com",
      goal="Log in and capture the latest 3 posts from the feed",
      use_vault=True,
  )

  # Scope the run to specific credentials only
  scoped = client.agent.run(
      url="https://www.linkedin.com",
      goal="Log in and capture the latest 3 posts from the feed",
      use_vault=True,
      credential_item_ids=[
          "cred:conn-abc:Work:item-123",
          "cred:conn-def:Personal:item-456",
      ],
  )
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  // Use all vault credentials for the run
  const response = await client.agent.run({
    url: "https://www.linkedin.com",
    goal: "Log in and capture the latest 3 posts from the feed",
    use_vault: true,
  });

  // Scope the run to specific credentials only
  const scoped = await client.agent.run({
    url: "https://www.linkedin.com",
    goal: "Log in and capture the latest 3 posts from the feed",
    use_vault: true,
    credential_item_ids: [
      "cred:conn-abc:Work:item-123",
      "cred:conn-def:Personal:item-456",
    ],
  });
  ```

  ```bash cURL theme={null}
  # Use all vault credentials for the run
  curl -X POST https://agent.tinyfish.ai/v1/automation/run \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.linkedin.com",
      "goal": "Log in and capture the latest 3 posts from the feed",
      "use_vault": true
    }'

  # Scope the run to specific credentials only
  curl -X POST https://agent.tinyfish.ai/v1/automation/run \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://www.linkedin.com",
      "goal": "Log in and capture the latest 3 posts from the feed",
      "use_vault": true,
      "credential_item_ids": [
        "cred:conn-abc:Work:item-123",
        "cred:conn-def:Personal:item-456"
      ]
    }'
  ```

  ```bash CLI theme={null}
  # Use all vault credentials for the run
  tinyfish agent run "Log in and capture the latest 3 posts from the feed" \
    --url https://www.linkedin.com \
    --use-vault

  # Scope the run to specific credentials only (IDs from `tinyfish vault item list`)
  tinyfish agent run "Log in and capture the latest 3 posts from the feed" \
    --url https://www.linkedin.com \
    --use-vault \
    --credential-item-id cred:conn-abc:Work:item-123 \
    --credential-item-id cred:conn-def:Personal:item-456
  ```
</CodeGroup>

***

## Parameters

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `use_vault` | boolean | No | `false` | Enable vault credentials for this run |
| `credential_item_ids` | string\[] | No | All synced items | Scope to specific credential URIs from [`GET /v1/vault/items`](/vault-setup#managing-your-vault). Requires `use_vault: true` |

***

## Domain Matching

Credentials are matched by domain.

For example, a credential with `linkedin.com` in its URL will be available when the agent navigates to `www.linkedin.com` or `login.linkedin.com`.

Credentials are not available on unrelated domains.

If you have multiple credentials for the same domain, TinyFish uses the ones you selected for that run.

***

## Security

### What the AI agent sees

Labels and field names only. Never actual values. The agent tells TinyFish where to type, and TinyFish handles what to type.

### What we don't do

Credentials never appear in agent prompts, run logs, screenshots, or streaming output. We do not rely on visual obfuscation as a security measure.

### Credential lifecycle

Credentials are resolved at the browser automation layer, not the AI planning layer. Values exist in memory only for the duration of the input action, then are discarded.

### Per-run access

Each run only gets the credentials you explicitly selected. The default is no vault access with `use_vault: false`.

### Encryption

Vault provider tokens are encrypted at rest and never stored in plaintext. You can revoke access by disconnecting the vault or rotating the token.

***

## Limitations

| Limitation | Notes |
| - | - |
| MFA / TOTP | Supported for time-based codes if the vault item has a TOTP field. Hardware keys and push notifications are not supported |
| Anti-bot | Some sites block automated login even with correct credentials. Use stealth mode and a proxy |
| Account lockout | Failed attempts count against normal lockout policies |
| OAuth / SSO | Redirect-based flows may not work for all providers |

<Tip>
  For logged-in workflows, combine vault credentials with
  [Browser Context Profiles](/key-concepts/browser-context-profiles). Browser Context Profiles maintain session state; Vault can
  repair it when a matching credential is available. For bot protection, also use
  [Proxies](/key-concepts/proxies).
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="credential_item_ids requires use_vault to be true" icon="triangle-exclamation">
    Add `use_vault: true` to the request body.
  </Accordion>

  <Accordion title="Credentials not being used during run" icon="circle-question">
    Verify the credential domain matches the target site.
  </Accordion>

  <Accordion title="use_vault is true but no vault connected" icon="plug-circle-xmark">
    Connect a vault first in **Settings → Vault**.
  </Accordion>

  <Accordion title="Wrong credential used" icon="key">
    Use `credential_item_ids` to scope the run to the exact credential you want.
  </Accordion>

  <Accordion title="Login failed or keeps repeating" icon="shield">
    Pair Vault with [Browser Context Profiles](/key-concepts/browser-context-profiles). Browser Context Profiles keep the browser
    logged in; if the session goes stale and a matching vault credential is available, TinyFish can
    use the credential to repair the session. For bot challenges, also add
    `browser_profile: "stealth"` and `proxy_config: { enabled: true }`.
  </Accordion>

  <Accordion title="Vault icon not in playground toolbar" icon="lock">
    Connect a vault first in **Settings → Vault**.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="Can TinyFish read all my passwords?" icon="eye">
    No. Values are only accessed at the moment of typing, and the AI agent never sees them.
  </Accordion>

  <Accordion title="Do credentials appear in run recordings?" icon="camera">
    No. Credentials are not captured in screenshots, streaming output, or logs.
  </Accordion>

  <Accordion title="What if I change a password?" icon="rotate">
    Click **Sync** in **Settings → Vault**. The next run uses the updated credential.
  </Accordion>

  <Accordion title="What happens if login fails?" icon="triangle-exclamation">
    TinyFish retries with available credentials for that domain. After multiple failures, the run continues without login.
  </Accordion>

  <Accordion title="What if I update my vault mid-run?" icon="clock">
    Runs use the credential state from when they started. Sync before starting a new run.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="Connect Your Vault" icon="vault" href="/vault-setup">
    Set up 1Password or Bitwarden
  </Card>

  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Parameters, lifecycle, and result handling
  </Card>

  <Card title="Browser Context Profiles" icon="window" href="/key-concepts/browser-context-profiles">
    Reuse Browser Context Profile state across runs
  </Card>
</CardGroup>


# Agent Endpoints
Source: https://docs.tinyfish.ai/key-concepts/endpoints

Choose the right TinyFish Agent endpoint based on sync, async, or streaming needs

TinyFish Web Agent offers three ways to run automations. Each endpoint serves a different need. Pick the one that matches how you want to handle the request and response.

## The Three Endpoints

| Endpoint | Pattern | Best For |
| - | - | - |
| `/run` | Synchronous | Quick tasks, simple integrations |
| `/run-async` | Start then check | Long tasks, batch processing |
| `/run-sse` | Live updates | Real-time progress, user-facing apps |

***

## Synchronous: `/run`

**Pattern:** Send request → Wait → Get result

The simplest approach. You call the API, it blocks until the automation completes, then returns the result.

```typescript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

const run = await client.agent.run({
  url: "https://example.com",
  goal: "Extract the page title",
});

console.log(run.result); // Your data
```

<Warning>
  Runs created via `/run` **cannot be cancelled**. The request blocks until the automation completes, so there is no window to issue a cancellation. If you need the ability to cancel runs, use `/run-async` or `/run-sse` instead.
</Warning>

<Tabs>
  <Tab title="When to use">
    * Tasks that complete in under 30 seconds
    * Simple scripts and one-off automations
    * When you don't need progress updates
  </Tab>

  <Tab title="When to avoid">
    * Long-running tasks (risk of timeout)
    * User-facing apps (no progress feedback)
    * Batch processing (blocks other requests)
    * When you need the ability to cancel a run
  </Tab>
</Tabs>

***

## Asynchronous: `/run-async`

**Pattern:** Send request → Get run ID → Poll for result

The request returns immediately with a `run_id`. You then poll a separate endpoint to check status and get the result when ready.

**1. Start the automation**

```typescript theme={null}
import { TinyFish } from "@tiny-fish/sdk";

const client = new TinyFish();

const queued = await client.agent.queue({
  url: "https://example.com",
  goal: "Extract all product data",
});

if (queued.error) {
  throw new Error(`Failed to queue run: ${queued.error.message}`);
}

const runId = queued.run_id;
```

**2. Poll for the result**

```typescript theme={null}
const run = await client.runs.get(runId);
// run.status: PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED
// run.result: Your data (when COMPLETED)
```

**3. Cancel a run (optional)**

If you need to stop a run before it completes, send a POST to the cancel endpoint:

```typescript theme={null}
await fetch(`https://agent.tinyfish.ai/v1/runs/${runId}/cancel`, {
  method: "POST",
  headers: { "X-API-Key": process.env.TINYFISH_API_KEY },
});
```

<Info>
  Learn more about run statuses and lifecycle in [Runs](/key-concepts/runs).
</Info>

<Tabs>
  <Tab title="When to use">
    * Long-running automations (30+ seconds)
    * Batch processing multiple URLs
    * Fire-and-forget workflows
    * When you need to track runs separately
  </Tab>

  <Tab title="When to avoid">
    * When you need real-time progress updates
    * Simple, quick extractions (adds complexity)
  </Tab>
</Tabs>

***

## Streaming: `/run-sse`

**Pattern:** Send request → Receive event stream → Process events as they arrive

Uses [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) to push updates to you in real-time. You'll receive events for each action the browser takes, plus a streaming URL you can embed in an iframe to watch the automation live.

**1. Start the automation and read events**

```typescript theme={null}
import { TinyFish, EventType } from "@tiny-fish/sdk";

const client = new TinyFish();

const stream = await client.agent.stream({
  url: "https://example.com",
  goal: "Extract all product data",
});

for await (const event of stream) {
  console.log(event.type, event);
}
```

### Event Types

| Event | Description |
| - | - |
| `STARTED` | Automation has begun, includes `run_id` |
| `STREAMING_URL` | URL to watch the browser live (valid 24hrs) |
| `PROGRESS` | Browser action taken (click, type, scroll, etc.) |
| `HEARTBEAT` | Connection keep-alive (no action needed) |
| `COMPLETE` | Automation finished, includes `status` and `result` |

### Cancelling an SSE Run

You can cancel a streaming run using the `run_id` from the `STARTED` event. The `onStarted` callback fires while you consume the stream, so capture `run_id` there and trigger the cancel from a separate context (here, a deadline timer):

```typescript theme={null}
let runId: string | undefined;

const stream = await client.agent.stream(
  { url: "https://example.com", goal: "Extract all product data" },
  { onStarted: (e) => { runId = e.run_id; } },
);

// Cancel from another context while the stream is being consumed.
const deadline = setTimeout(() => {
  if (runId) {
    fetch(`https://agent.tinyfish.ai/v1/runs/${runId}/cancel`, {
      method: "POST",
      headers: { "X-API-Key": process.env.TINYFISH_API_KEY },
    });
  }
}, 30000);

for await (const event of stream) {
  console.log(event);
}
clearTimeout(deadline);
```

### Handling Events

Use this pattern to process each event type as the automation progresses.

```typescript theme={null}
import { TinyFish, EventType, RunStatus } from "@tiny-fish/sdk";

const client = new TinyFish();

const stream = await client.agent.stream(
  { url: "https://example.com", goal: "Extract all product data" },
  {
    onStarted: (e) => console.log(`Run started: ${e.run_id}`),
    onStreamingUrl: (e) => console.log(`Watch live: ${e.streaming_url}`),
    onProgress: (e) => console.log(`Action: ${e.purpose}`),
    onComplete: (e) => {
      if (e.status === RunStatus.COMPLETED) {
        console.log("Result:", e.result);
      } else {
        console.error(e.error?.message || "Automation failed");
      }
    },
  },
);

for await (const event of stream) {
  // Callbacks fire automatically during iteration
}
```

<Tabs>
  <Tab title="When to use">
    * User-facing apps (show progress)
    * When you want to watch the browser live
    * Debugging and development
    * Long tasks where you want visibility
  </Tab>

  <Tab title="When to avoid">
    * Batch processing (complexity overhead)
    * Backend jobs that don't need progress
  </Tab>
</Tabs>

***

## Common Request Options

All three endpoints accept the same request body. Beyond the required `url` and `goal`, these optional fields apply across `/run`, `/run-async`, and `/run-sse`:

| Field | Type | Description |
| - | - | - |
| `agent_config.max_steps` | number | Maximum tool-call steps before the agent stops (in **beta** — join the beta to use it). 1–500, defaults to 150. See [Runs](/key-concepts/runs#max-steps). |
| `agent_config.max_duration_seconds` | number | Maximum wall-clock seconds before the agent stops. Defaults to no limit. |
| `agent_config.mode` | string | Agent behavior mode. `strict` (in **beta** — join the beta to use it) enables fail-fast for test automation. See [Runs](/key-concepts/runs#strict-agent-mode). |
| `capture_config` | object | Toggle which data to capture during the run (`screenshots`, `html`, `recording`, etc.). `html: true` is required for per-step HTML snapshots. |
| `webhook_url` | string | HTTPS URL to receive run lifecycle notifications. Must use HTTPS. |

```json theme={null}
{
  "url": "https://example.com",
  "goal": "Extract all product data",
  "agent_config": {
    "max_steps": 50,
    "max_duration_seconds": 300
  },
  "capture_config": { "html": true },
  "webhook_url": "https://your-app.example.com/webhooks/tinyfish"
}
```

For authenticated runs and runtime browser modes, see [Browser Profiles](/key-concepts/browser-profiles) and the [Browser Context Profiles API](/agent-api/browser-context-profiles).

***

## Quick Decision Guide

<Steps>
  <Step title="Need real-time progress updates?">
    **Yes** → Use `/run-sse`
  </Step>

  <Step title="Task takes longer than 30 seconds?">
    **Yes** → Use `/run-async` + polling
  </Step>

  <Step title="Submitting multiple tasks at once?">
    **Yes** → Use `/run-async` (parallel submission)
  </Step>

  <Step title="Simple, quick task?">
    Use `/run` (synchronous)
  </Step>
</Steps>

***

## Comparison Table

| Feature | `/run` | `/run-async` | `/run-sse` |
| - | - | - | - |
| Response type | Final result | Run ID | Event stream |
| Progress updates | No | No (poll status) | Yes |
| Streaming URL | In response | Poll to get | In events |
| Cancellable | No | Yes | Yes |
| Best for | Quick tasks | Batch/long tasks | Real-time UI |
| Complexity | Low | Medium | Medium |

***

## Related

<CardGroup>
  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Understand the automation lifecycle
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint specifications
  </Card>
</CardGroup>


# The Goal Parameter
Source: https://docs.tinyfish.ai/key-concepts/goals

Natural language instructions that tell TinyFish Web Agent what to do

A goal is the `goal` parameter you pass to the API: a plain English description of what you want TinyFish Web Agent to accomplish. Instead of writing code to click buttons or parse HTML, you describe the task and TinyFish Web Agent figures out how to do it.

## The Mental Model

Think of TinyFish Web Agent as a capable assistant sitting in front of a browser. It can see what's on the screen, click, type, scroll, and navigate, but it needs clear instructions.

**What it can do:**

* See exactly what you would see on the screen
* Click, type, scroll, and navigate
* Wait for dynamic content to load
* Follow instructions precisely
* Return structured data
* Navigate multi-page PDFs and extract content
* Remember information across workflow steps
* Parse natural language into form fields

**What it cannot do:**

* Read your mind about what you meant
* Guess what to do when something unexpected happens
* Know your business context unless you tell it
* Decide on output format without explicit instructions

Your job is to remove ambiguity. The more explicit your goal, the higher your success rate.

***

## Quick Examples

**Data extraction:**

```
Extract product name, price, and stock status. Return as JSON.
```

**Form filling:**

```
Fill the contact form with name "John Doe" and email "john@example.com", then click Submit.
```

**Multi-step workflow:**

```
1. Login with email "user@example.com" and password "pass123"
2. Navigate to the dashboard
3. Extract account balance
```

***

## Learn More

Learn how to write goals that succeed on the first try with our Goal Prompting Guide.

<Card title="Goal Prompting Guide" icon="bullseye" href="/prompting-guide">
  The anatomy of a great goal, task-specific patterns, and production-ready examples.
</Card>

***

## Related

<CardGroup>
  <Card title="Runs" icon="play" href="/key-concepts/runs">
    What happens after you send a goal
  </Card>

  <Card title="Endpoints" icon="plug" href="/key-concepts/endpoints">
    Choose how to call the API
  </Card>
</CardGroup>


# Proxies
Source: https://docs.tinyfish.ai/key-concepts/proxies

Route requests through specific geographic locations

Proxies let you route TinyFish Web Agent's browser requests through specific countries. Use them to access geo-restricted content or avoid regional blocks.

## How to Use

Add `proxy_config` to your request:

```typescript theme={null}
{
  url: "https://example.com",
  goal: "Extract product data",
  proxy_config: {
    enabled: true,
    country_code: "US"
  }
}
```

***

## Supported Countries

| Code | Country |
| - | - |
| `US` | United States |
| `GB` | United Kingdom |
| `CA` | Canada |
| `DE` | Germany |
| `FR` | France |
| `JP` | Japan |
| `AU` | Australia |

***

## When to Use Proxies

* Accessing geo-restricted content
* Avoiding regional IP blocks
* Testing localized content
* Combining with stealth mode for protected sites

***

## Combining with Stealth Mode

For sites with bot protection and geo-restrictions, use both:

```typescript theme={null}
{
  url: "https://protected-site.com",
  goal: "Extract product data",
  browser_profile: "stealth",
  proxy_config: {
    enabled: true,
    country_code: "US"
  }
}
```

Learn more about browser profiles in the [Browser Profiles](/key-concepts/browser-profiles) page.

***

## Related

<CardGroup>
  <Card title="Browser Profiles" icon="window" href="/key-concepts/browser-profiles">
    Standard vs stealth browser modes
  </Card>

  <Card title="Endpoints" icon="plug" href="/key-concepts/endpoints">
    Choose how to call the API
  </Card>

  <Card title="Anti-Bot Guide" icon="shield" href="/anti-bot-guide">
    Diagnose and bypass bot detection on protected websites
  </Card>
</CardGroup>


# Runs
Source: https://docs.tinyfish.ai/key-concepts/runs

The lifecycle of a TinyFish Web Agent automation

A run is a single execution of an automation. When you call any TinyFish Web Agent endpoint, you create a run that moves through a lifecycle from start to finish.

## Run Lifecycle

Every run moves through these statuses:

| Status | Meaning |
| - | - |
| `PENDING` | Queued, waiting to start |
| `RUNNING` | Browser is executing your goal |
| `COMPLETED` | Finished (check result for data) |
| `FAILED` | Infrastructure error occurred |
| `CANCELLED` | Manually stopped |

<Info>
  Cancellation is only supported for runs created via `/run-async` or `/run-sse`. Runs created via the synchronous `/run` endpoint cannot be cancelled because the request blocks until completion.
</Info>

***

## Strict Agent Mode

<Info>
  **Beta:** Strict Agent Mode is in beta — you must join the beta to use it (contact support to enable it
  for your account). Set `agent_config.mode` to `strict` when creating a run.
</Info>

```json theme={null}
{
  "url": "https://example.com",
  "goal": "Check that checkout succeeds with a saved test account",
  "agent_config": {
    "mode": "strict"
  }
}
```

Strict mode is designed for precise tests and repeatable automation. When the agent encounters an
unexpected state, it stops faster instead of exploring workarounds. Use the default mode for
open-ended browsing, search, or recovery-oriented tasks.

***

## Max Steps

<Info>
  **Beta:** Custom `max_steps` is in beta — you must join the beta to use it (contact support to
  enable it for your account). Set `agent_config.max_steps` when creating a run.
</Info>

```json theme={null}
{
  "url": "https://example.com",
  "goal": "Extract all pricing information",
  "agent_config": {
    "max_steps": 50
  }
}
```

`max_steps` caps how many tool-call steps the agent takes before it stops. Accepts an integer from
1 to 500; runs default to 150 when omitted. Lower it to fail fast and bound cost on simple goals,
raise it for multi-page workflows that legitimately need more steps to finish.

***

## The Run Object

When you fetch a run, you get back the following object:

```json theme={null}
{
  "run_id": "abc123",
  "status": "COMPLETED",
  "goal": "Extract all pricing information",
  "created_at": "2026-01-14T10:30:00Z",
  "started_at": "2026-01-14T10:30:05Z",
  "finished_at": "2026-01-14T10:31:30Z",
  "num_of_steps": 5,
  "result": { ... },
  "output_schema": null,
  "profile_attached": false,
  "profile_id": null,
  "error": null,
  "streaming_url": "https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0",
  "browser_config": { "proxy_enabled": false, "proxy_country_code": null },
  "video_url": null,
  "steps": [ ... ]
}
```

| Field | Description |
| - | - |
| `run_id` | Unique identifier for this run |
| `status` | Current lifecycle status |
| `goal` | Natural language goal for this run |
| `created_at` | ISO 8601 timestamp when the run was created |
| `started_at` | ISO 8601 timestamp when the run started executing. `null` while pending. |
| `finished_at` | ISO 8601 timestamp when the run finished. `null` until terminal. |
| `num_of_steps` | Number of steps taken during the run. `null` while in progress. |
| `result` | Your extracted data (when COMPLETED) |
| `output_schema` | Structured-output schema subset originally requested for this run. `null` when none was provided. |
| `profile_attached` | Whether this run attached a Browser Context Profile internally |
| `profile_id` | Browser Context Profile ID attached to this run, or `null` when none attached |
| `error` | Error details (when FAILED). See [The Error Object](#the-error-object). |
| `streaming_url` | URL to watch the browser live (available while running) |
| `browser_config` | Browser configuration used for the run (`proxy_enabled`, `proxy_country_code`) |
| `video_url` | Presigned URL to the run recording, if available. `null` when no recording exists. URL expires after 15 minutes. |
| `steps` | Steps the agent took during this run. See [Retrieving Steps and Screenshots](#retrieving-steps-and-screenshots). |

### The Error Object

When a run fails, `error` is a structured object (otherwise it is `null`):

```json theme={null}
{
  "code": "service_busy",
  "message": "Browser crashed during execution",
  "category": "SYSTEM_FAILURE",
  "retry_after": 60,
  "help_url": "https://docs.tinyfish.ai/prompting-guide",
  "help_message": "Need help? Check out our goal prompting guide for tips and examples."
}
```

| Field | Description |
| - | - |
| `code` | Machine-readable error code for programmatic handling (optional) |
| `message` | Human-readable error message describing why the run failed |
| `category` | One of `SYSTEM_FAILURE`, `AGENT_FAILURE`, `BILLING_FAILURE`, or `UNKNOWN` |
| `retry_after` | Suggested retry delay in seconds, or `null` if not retryable |
| `help_url` | URL to troubleshooting documentation (optional) |
| `help_message` | Human-readable guidance (optional) |

Use `category` to decide how to react: `SYSTEM_FAILURE` is a TinyFish issue (retry after `retry_after`), `AGENT_FAILURE` means the input needs fixing, `BILLING_FAILURE` means the run was rejected at the billing check before it started — add money at [agent.tinyfish.ai/wallet](https://agent.tinyfish.ai/wallet) (minimum top-up \$10), or add credits on a legacy account — and `UNKNOWN` should be treated as retryable.

Runs can also use [vault credentials](/key-concepts/credentials) for authenticated automation. Pass `use_vault: true` and optionally `credential_item_ids` when creating a run to let TinyFish log into sites using your connected password manager.

***

## Searching and Filtering Runs

`GET /v1/runs` supports filtering, text search, sorting, and pagination to help you find specific runs.

### Query Parameters

| Parameter | Type | Description |
| - | - | - |
| `status` | string | Filter by status: `PENDING`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED` |
| `goal` | string | Search runs by goal text (case-insensitive partial match) |
| `created_after` | ISO 8601 | Only return runs created after this timestamp |
| `created_before` | ISO 8601 | Only return runs created before this timestamp |
| `sort_direction` | `asc` \| `desc` | Sort order by creation date (default: `desc`) |
| `cursor` | string | Pagination cursor from a previous response |
| `limit` | number | Results per page, 1–100 (default: 20) |

### Examples

**Search by goal text:**

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/runs?goal=linkedin" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Filter by status and date range:**

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/runs?status=COMPLETED&created_after=2026-01-01T00:00:00Z&created_before=2026-02-01T00:00:00Z" \
  -H "X-API-Key: YOUR_API_KEY"
```

**Oldest first with pagination:**

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/runs?sort_direction=asc&limit=10" \
  -H "X-API-Key: YOUR_API_KEY"
```

### Response Shape

`GET /v1/runs` returns a `data` array of run objects and a `pagination` object:

```json theme={null}
{
  "data": [
    {
      "run_id": "run_abc123",
      "status": "COMPLETED",
      "goal": "Extract the page title",
      "created_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:01Z",
      "finished_at": "2026-01-01T00:00:30Z"
    }
  ],
  "pagination": {
    "total": 42,
    "next_cursor": null,
    "has_more": false
  }
}
```

### Cursor Pagination

When there are more results, the pagination object includes `next_cursor`:

```json theme={null}
{
  "data": [ ... ],
  "pagination": {
    "total": 142,
    "next_cursor": "eyJpZCI6...",
    "has_more": true
  }
}
```

Pass `next_cursor` as the `cursor` parameter to fetch the next page.

***

## Watching Runs Live

Every run includes a `streaming_url` where you can watch the browser execute in real-time. This is useful for debugging, demos, or showing users what's happening behind the scenes.

Embed the URL in an iframe to display the live browser view in your app:

```html theme={null}
<iframe
  src="https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0"
  width="800"
  height="600"
/>
```

The streaming URL is available while the run is active. After the run completes, use `video_url` from the run object to access the recording.

***

## Retrieving Steps and Screenshots

<Warning>
  `?screenshots=base64` is available to unblock current integrations but is temporary — it will be deprecated soon in favor of URL-based access. Avoid building long-term workflows that depend on this format.
</Warning>

`GET /v1/runs/{id}` always returns a `steps` array. The `screenshots` query param controls how the per-step `screenshot` field is delivered:

| `screenshots` | Behavior |
| - | - |
| `url` (default) | Each step's `screenshot` is an absolute URL to the screenshot image |
| `base64` | Each step's `screenshot` is an inline `data:image/jpeg;base64,...` data URI (\~50–100 KB each — use only for audit trails or visual debugging) |
| `none` | Screenshots are omitted (`screenshot` is `null`) |

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/runs/abc123?screenshots=base64" \
  -H "X-API-Key: YOUR_API_KEY"
```

The `html` query param controls the per-step `html` field, a URL to the full-page HTML snapshot captured at that step. It is only non-`null` when the run was created with `capture_config.html: true`.

| `html` | Behavior |
| - | - |
| `url` (default) | Each step's `html` is an absolute URL to the HTML snapshot |
| `none` | HTML URLs are omitted (`html` is `null`) |

Each step has the following shape (this example reflects the default `screenshots=url`):

```json theme={null}
{
  "run_id": "abc123",
  "status": "COMPLETED",
  "result": { ... },
  "steps": [
    {
      "id": "09de224d-fb2b-45b7-b067-585726194a2e",
      "timestamp": "2026-03-23T10:00:01Z",
      "status": "COMPLETED",
      "action": "Navigate to https://example.com",
      "screenshot": "https://agent.tinyfish.ai/runs/abc123/steps/09de224d/screenshot",
      "html": "https://agent.tinyfish.ai/runs/abc123/steps/09de224d/html",
      "duration": "1.2s"
    },
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "timestamp": "2026-03-23T10:00:03Z",
      "status": "COMPLETED",
      "action": "Click the 'Sign In' button",
      "screenshot": "https://agent.tinyfish.ai/runs/abc123/steps/3fa85f64/screenshot",
      "html": null,
      "duration": "0.8s"
    }
  ]
}
```

***

## Understanding COMPLETED Status

<Warning>
  `COMPLETED` means the infrastructure worked, not that your goal succeeded.
</Warning>

Always check the `result` field:

**Goal succeeded:**

```json theme={null}
{
  "status": "COMPLETED",
  "result": {
    "products": [
      { "name": "Widget", "price": 29.99 }
    ]
  }
}
```

**Infrastructure worked, goal failed:**

The browser worked fine, but TinyFish Web Agent couldn't achieve your goal.

```json theme={null}
{
  "status": "COMPLETED",
  "result": {
    "status": "failure",
    "reason": "Could not find any products on the page"
  }
}
```

***

## Handling Run Results

Use this pattern to handle both infrastructure failures and goal failures in your code.

```typescript theme={null}
import { TinyFish, RunStatus } from "@tiny-fish/sdk";
import type { Run } from "@tiny-fish/sdk";

const client = new TinyFish();

// Fetch a run by ID, then handle the result
const run = await client.runs.get(runId);
const result = await handleRunResult(run);

async function handleRunResult(run: Run) {
  switch (run.status) {
    case RunStatus.COMPLETED:
      if (!run.result) {
        return { success: false, error: "No result returned" };
      }

      // Check for goal-level failure in result
      if (run.result.status === "failure" || run.result.error) {
        return {
          success: false,
          error: run.result.reason || run.result.error || "Goal not achieved",
        };
      }

      return { success: true, data: run.result };

    case RunStatus.FAILED:
      return {
        success: false,
        error: run.error?.message || "Automation failed",
        retryable: true,
      };

    case RunStatus.CANCELLED:
      return { success: false, error: "Run was cancelled" };

    default:
      return { success: false, error: `Unexpected status: ${run.status}` };
  }
}
```

***

## Cancelling Runs

You can cancel a run that is `PENDING` or `RUNNING` by sending a POST request to `/v1/runs/{id}/cancel`. This works for runs created via `/run-async` or `/run-sse` only.

```typescript theme={null}
const response = await fetch(`https://agent.tinyfish.ai/v1/runs/${run_id}/cancel`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TINYFISH_API_KEY,
  },
});

const result = await response.json();
// result.status: CANCELLED, COMPLETED, or FAILED
// result.cancelled_at: timestamp if cancelled
// result.message: additional context (e.g. "Run already cancelled")
```

The cancel endpoint is **idempotent** — calling it on an already-cancelled or completed run returns the current state without error.

| Scenario | Response `status` | `cancelled_at` | `message` |
| - | - | - | - |
| Run cancelled | `CANCELLED` | Timestamp | `null` |
| Already cancelled | `CANCELLED` | Timestamp | `"Run already cancelled"` |
| Already completed | `COMPLETED` | `null` | `"Run already finished"` |

<Warning>
  Only runs created via the API (`/run-async` or `/run-sse`) can be cancelled using this endpoint. Runs created through the dashboard UI or via the synchronous `/run` endpoint cannot be cancelled.
</Warning>

***

## Related

<CardGroup>
  <Card title="Endpoints" icon="plug" href="/key-concepts/endpoints">
    Choose sync, async, or streaming
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Handle errors gracefully
  </Card>

  <Card title="Vault Credentials" icon="lock" href="/key-concepts/credentials">
    Use password manager credentials in runs
  </Card>
</CardGroup>


# Structured Output
Source: https://docs.tinyfish.ai/key-concepts/structured-output

Structured-output schema support for the output_schema request field

Use `output_schema` when you want TinyFish to return the final run result in a predictable JSON shape.

The same rules apply across the REST API, SDKs, CLI, Playground, and MCP integrations as they all forward to the same API validator.

## Example

```json theme={null}
{
  "output_schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "price": { "type": "number", "minimum": 0 },
      "published_at": {
        "type": "string",
        "format": "date-time",
        "nullable": true
      },
      "tags": {
        "type": "array",
        "items": { "type": "string" },
        "maxItems": 10
      }
    },
    "required": ["title", "price"],
    "propertyOrdering": ["title", "price", "published_at", "tags"]
  }
}
```

## The Schema Is the Contract

`output_schema` defines the exact shape of the result. When your schema and your prompt
disagree about whether to return a single object or a list, **the schema wins** — the
result is shaped to match the schema, not the wording of the prompt.

A schema that describes a single object returns a single object, even if the prompt asks
for "10 results". To return a list, the schema must say so explicitly (see below).

## Returning a List of Items

The top level must always be an object, so a list of results goes in an array field:

```json theme={null}
{
  "output_schema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "url": { "type": "string" }
          },
          "required": ["name", "url"]
        }
      }
    },
    "required": ["results"]
  }
}
```

Without the array field, a prompt like "list 10 tools" returns only the first match,
because the schema describes a single object.

## Top-Level Constraints

| Constraint | Rule |
| - | - |
| Top-level shape | Must be a JSON object. If `type` is present, it must be `object` |
| Top-level `anyOf` | Not supported. Put composition inside object fields instead |
| Size limit | Serialized schema must be 64KB or smaller |
| Nesting depth | Maximum depth is 10 |
| Boolean schema nodes | `true` and `false` schemas are not supported |
| Nullable values | Use `nullable: true`, not `type: ["string", "null"]` |

<Note>
  `type: "boolean"` is supported for fields in your result. What is not supported is using a schema node that is itself
  the literal boolean `true` or `false`.
</Note>

## Supported Types

| Type | Notes |
| - | - |
| `object` | Supports `properties`, `required`, and `propertyOrdering` |
| `array` | Supports `items`, `minItems`, and `maxItems` |
| `string` | Supports `enum` and `format` |
| `number` | Supports `minimum` and `maximum` |
| `integer` | Supports `minimum` and `maximum` |
| `boolean` | Supported as a field type |

## Supported Keywords

Any keyword outside this allowlist is rejected:

* `anyOf`
* `enum`
* `format`
* `items`
* `maxItems`
* `maximum`
* `minItems`
* `minimum`
* `nullable`
* `properties`
* `propertyOrdering`
* `required`
* `type`

## Important Rules

* Use `anyOf` for composition. `oneOf` is not supported.
* `enum` requires `type: "string"`, and every enum value must be a string.
* `format` requires `type: "string"`. Supported formats are `date`, `date-time`, `duration`, and `time`.
* `items`, `minItems`, and `maxItems` require `type: "array"`.
* `minimum` and `maximum` require `type: "number"` or `type: "integer"`.
* `propertyOrdering` requires `properties`, values must be unique, and every referenced field must exist in
  `properties`.
* `required` fields must also exist in `properties`, unless the requirement is being expressed inside an `anyOf` branch.
* Stored runs include the requested schema as `output_schema` on `GET /v1/runs/{id}` and `runs.list()`.

## Common Rewrites

| Instead of | Use |
| - | - |
| `oneOf` | `anyOf` |
| `const: "ready"` | `type: "string", enum: ["ready"]` |
| `type: ["string", "null"]` | `type: "string", nullable: true` |
| `type: ["number", "null"]` | `type: "number", nullable: true` |
| `type: ["integer", "null"]` | `type: "integer", nullable: true` |

## Commonly Rejected Keywords

These are not supported in `output_schema`:

* `additionalProperties`
* `const`
* `example`
* `examples`
* `oneOf`

Any other keyword outside the supported allowlist is also rejected.

## Example Errors

The API returns a `400` error before execution when the schema is invalid. Common validation messages include:

* `output_schema field "oneOf" is not supported at #. Use "anyOf" instead.`
* `output_schema top-level "anyOf" is not supported at #. Top-level schema must declare "type": "object".`
* `output_schema type arrays are not supported at #/properties/title. Use 'type: "string", nullable: true' instead.`
* `output_schema field "additionalProperties" is not supported at #.`
* `output_schema exceeds the maximum nesting depth of 10.`

## Related

* [Agent API Reference](/agent-api/reference)
* [Quick Start](/quick-start)
* [CLI Commands](/cli/commands)


# Live Browser Preview
Source: https://docs.tinyfish.ai/live-preview

Embed a real-time browser view in your app using the streaming URL

Every TinyFish automation provides a `streaming_url`, a live feed of the browser as it runs. Drop it in an iframe to show users what's happening in real time.

You'll see our little fish swimming through the web for you, navigating pages, clicking buttons, and extracting data while you watch.

<img alt="TinyFish live browser preview showing the fish navigating a webpage" />

## Getting the Streaming URL

When you use the [SSE endpoint](/key-concepts/endpoints#streaming-run-sse), one of the events you'll receive is `STREAMING_URL`:

```json theme={null}
{
  "type": "STREAMING_URL",
  "run_id": "abc123",
  "streaming_url": "https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0"
}
```

<Warning>
  The streaming URL may become unavailable after the run completes. To preserve run recordings, capture the stream content during execution.
</Warning>

## Embedding It

Once you have the URL, embed it in an iframe:

```html theme={null}
<iframe
  id="preview"
  src="YOUR_STREAMING_URL"
  width="100%"
  height="600"
  style="border: 1px solid #e5e7eb; border-radius: 8px;"
></iframe>
```

For a responsive container that maintains a 16:9 aspect ratio:

```html theme={null}
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe
    src="YOUR_STREAMING_URL"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none; border-radius: 8px;"
  ></iframe>
</div>
```

## Full Example

Start an automation, listen for the `STREAMING_URL` event in the SSE stream, and set it as the iframe source to display the live browser.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { TinyFish, EventType } from "@tiny-fish/sdk";

  const client = new TinyFish();

  const stream = await client.agent.stream(
    {
      url: "https://example.com/products",
      goal: "Extract all product names and prices",
    },
    {
      onStreamingUrl: (event) => {
        // Set iframe src to show the live browser
        const iframe = document.getElementById("preview");
        if (iframe) {
          iframe.setAttribute("src", event.streaming_url);
        }
      },
    },
  );

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

  ```python Python theme={null}
  from tinyfish import TinyFish, StreamingUrlEvent

  client = TinyFish()

  with client.agent.stream(
      url="https://example.com/products",
      goal="Extract all product names and prices",
  ) as stream:
      for event in stream:
          if isinstance(event, StreamingUrlEvent):
              # Use this URL in an iframe to show the live browser
              print("Embed this:", event.streaming_url)
              break
  ```
</CodeGroup>

## Tips

* **Keep your API key server-side.** Call the SSE endpoint from your backend and pass the `streaming_url` to the frontend. The streaming URL itself is safe to expose to the browser.
* **Show a loading state.** The streaming URL arrives a few seconds after the automation starts, so show a spinner or placeholder until then.
* **The iframe is read-only.** Users can watch but can't interact with the browser session.


# MCP Integration
Source: https://docs.tinyfish.ai/mcp-integration/index

Integrate TinyFish Web Agent with your AI assistant

Connect TinyFish to Claude, Codex, OpenCode, Command Code, Grok, Cursor, ChatGPT, or any MCP-compatible AI assistant. Once connected, your assistant can search the web, browse websites, and extract data on your behalf.

<Note>
  On **ChatGPT**, **Claude**, or **Grok**? The curated [TinyFish plugin](/plugins) bundles these tools with skills and safety rules and installs in one command or tap. This page covers the raw MCP endpoint for any client.
</Note>

## Quick Install

<Tabs>
  <Tab title="Codex">
    ```bash theme={null}
    codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
    ```
  </Tab>

  <Tab title="Grok">
    <Steps>
      <Step title="Install the plugin">
        ```bash theme={null}
        grok plugin install tinyfish --trust
        ```
      </Step>

      <Step title="Open the MCP server list">
        ```bash theme={null}
        grok /mcps
        ```
      </Step>

      <Step title="Authenticate">
        In the `/mcps` list, find the **tinyfish** MCP server entry and select **Authenticate**. Grok opens the OAuth flow in your browser — sign in with your TinyFish account to authorize the connection.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client claude-code
    ```
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    opencode mcp add tinyfish --url https://agent.tinyfish.ai/mcp
    ```
  </Tab>

  <Tab title="Command Code">
    ```bash theme={null}
    npx -y @tiny-fish/cli@latest connect command-code
    ```
  </Tab>

  <Tab title="Claude">
    Claude uses the official TinyFish connector — one tap in the browser, no config file:

    <Card title="Add TinyFish to Claude" icon="arrow-up-right-from-square" href="https://claude.ai/directory/tinyfish">
      Opens the TinyFish connector in a new tab
    </Card>

    See [Plugins → Claude](/plugins#claude) for the full steps.
  </Tab>

  <Tab title="ChatGPT">
    ChatGPT has an official TinyFish plugin — one tap in the browser, no config file:

    <Card title="Add TinyFish to ChatGPT" icon="arrow-up-right-from-square" href="https://chatgpt.com/plugins/plugin_asdk_app_695325bae7348191b58ae9349a963d22">
      Opens the TinyFish plugin in a new tab
    </Card>

    See [Plugins → ChatGPT](/plugins#chatgpt) for the full steps. To add it as a custom MCP connector instead, use this server URL:

    ```text theme={null}
    https://agent.tinyfish.ai/mcp/chatgpt
    ```
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client cursor
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    npx -y install-mcp@latest https://agent.tinyfish.ai/mcp --client windsurf
    ```
  </Tab>
</Tabs>

<Accordion title="Manual configuration" icon="gear">
  <Tabs>
    <Tab title="Codex">
      ```bash theme={null}
      codex mcp add tinyfish --url https://agent.tinyfish.ai/mcp
      ```
    </Tab>

    <Tab title="Grok">
      ```bash theme={null}
      grok mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
      ```

      Or add to `~/.grok/config.toml` (user-level) or `.grok/config.toml` (project-level):

      ```toml theme={null}
      [mcp_servers.tinyfish]
      url = "https://agent.tinyfish.ai/mcp"
      ```
    </Tab>

    <Tab title="Claude Code">
      ```bash theme={null}
      claude mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp
      ```
    </Tab>

    <Tab title="OpenCode">
      ```bash theme={null}
      opencode mcp add tinyfish --url https://agent.tinyfish.ai/mcp
      ```

      Or add to `~/.config/opencode/opencode.jsonc` (OpenCode reads JSON or JSONC):

      ```json theme={null}
      {
        "mcp": {
          "tinyfish": {
            "type": "remote",
            "url": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```

      Then run `opencode mcp auth tinyfish` to complete OAuth (or authenticate on first use).

      OpenCode needs a model that supports **tool use** — TinyFish runs on tool calls, so image-only models (e.g. Nano Banana Pro) will error with "No endpoints found that support tool use." Switch OpenCode's model if you hit that.
    </Tab>

    <Tab title="Command Code">
      Command Code connects with a TinyFish API key. The CLI writes it for you:

      ```bash theme={null}
      npx -y @tiny-fish/cli@latest connect command-code --api-key sk-tinyfish-...
      ```

      Drop `--api-key` if you have already run `tinyfish auth login`. There is no browser sign-in
      for this client, so without a key the command stops rather than registering something that
      cannot authenticate.

      To do it by hand, add to `~/.commandcode/mcp.json` with your key from the [dashboard](https://agent.tinyfish.ai/api-keys):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "transport": "http",
            "url": "https://agent.tinyfish.ai/mcp",
            "headers": {
              "Authorization": "Bearer YOUR_API_KEY"
            }
          }
        }
      }
      ```

      That file is the user-wide config. `cmd mcp add` writes a project-only entry by default, and it opens a browser sign-in even when you pass a header, so TinyFish connects to Command Code by API key only.
    </Tab>

    <Tab title="Claude">
      Nothing to configure by hand. The [TinyFish connector](https://claude.ai/directory/tinyfish) registers the server and completes OAuth in one tap — see [Plugins → Claude](/plugins#claude).
    </Tab>

    <Tab title="ChatGPT">
      Add a custom MCP connector in ChatGPT with:

      ```text theme={null}
      https://agent.tinyfish.ai/mcp/chatgpt
      ```

      ChatGPT will prompt you to authenticate via OAuth.
    </Tab>

    <Tab title="Cursor">
      Add to your Cursor MCP settings:

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "url": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>

    <Tab title="Windsurf">
      Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish": {
            "serverUrl": "https://agent.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

## Available Tools

### Web Automation

* **`run_web_automation`** — Execute multi-step web automation given a URL and natural language goal. Streams progress in real-time. Use this for tasks that require clicking, navigating, filling forms, logging in, or interacting with a website. For authenticated recurring workflows, pass `use_profile: true`; add `profile_id` to select a specific Browser Context Profile.
* **`run_web_automation_async`** — Same as `run_web_automation` but returns a `run_id` immediately without waiting. Use for long-running tasks where you don't need real-time progress. Poll with `get_run`. Supports the same `use_profile`, `profile_id`, and `use_vault` controls.
* **`get_run`** — Retrieve details of a specific automation run by ID. Returns status, result, and error info.
* **`list_runs`** — List your automation runs with optional filtering by status and pagination.
* **`cancel_run`** — Cancel a running or pending automation run by ID. Idempotent — already-terminal runs return their current status.

### Batch Automation

* **`batch_status`** — Check the status of multiple runs at once (up to 8). Poll every 30–60 seconds until `all_terminal` is true.
* **`batch_cancel`** — Cancel multiple running or pending runs by their IDs (up to 8). Idempotent.

### Web Search

* **`search`** — Search the web and get structured results with titles, snippets, and URLs. Use this to find information or discover URLs before automating a specific site. Optional filters: `recency_minutes`, `after_date`, `before_date`, `domain_type` (`"web"` | `"news"` | `"research_paper"`), `pub_year_min` / `pub_year_max`. When `domain_type=research_paper`, `recency_minutes`, `after_date`, and `before_date` are not supported — use `pub_year_min` / `pub_year_max` instead to scope by publication year (inclusive integers, `0`-`9999`, with `pub_year_min <= pub_year_max` when both are set). You can also narrow or bias results with `location` (country code, e.g. `"US"`), `language` (language code, e.g. `"en"`), and `include_domains` / `exclude_domains` (comma-separated domain allow/deny lists, combined length capped). Use `page` (0-indexed, `0`-`10`) to paginate. You can also pass an optional `purpose` — a short statement of why you're searching — to give the search additional intent signal for better-quality results.
* **`get_search_usage`** — List past search usage records with filtering by date range and status.

### Content Extraction

* **`fetch_content`** — Fetch web pages, render JavaScript-heavy pages when needed, and extract clean, structured content. Preferred over `run_web_automation` when you only need to read page content. Supports up to 10 URLs per request. Control the output with `format` (`"markdown"` default | `"html"` | `"json"`), `links` and `image_links` (extract outbound/image URLs), `ttl` (cache freshness tolerance in seconds), and `per_url_timeout_ms` (per-URL wall-clock budget). Scope extraction with `include_selectors` / `exclude_selectors` (1–20 CSS selectors each). For conditional requests, pass `if_none_match` / `if_modified_since` (single URL only) and set `include_etag_and_last_modified` to get the validators back. You can also pass an optional `purpose` — a short statement of why you're fetching the URLs — to give the fetch additional intent signal for better-quality results.
* **`list_fetch_usage`** — List past fetch requests with filtering by date range and status. Returns metadata only.

### Browser Sessions

* **`create_browser_session`** — Create a remote, stealth Chrome browser session and get CDP connection details. Use for direct programmatic browser control with Playwright, Puppeteer, or Selenium.
* **`list_browser_sessions`** — List your browser sessions with optional filtering by session ID, time range, and status.
* **`close_browser_session`** — Close a browser session by ID to release it early instead of waiting for its inactivity timeout. Idempotent — already-ended sessions return success.

### Wallet

* **`get_wallet`** — Read-only. Returns your current wallet balance, auto-reload state, per-product contract rates, and any in-flight top-up. Auto-reload changes happen in the dashboard.
* **`top_up_wallet`** — Adds money to your wallet, paid by the agent over the Machine Payments Protocol: the first call returns a payment challenge, the second call presents the paid credential. Out-of-funds refusals point at it, and your wallet asks you to approve the payment. Accounts outside the rollout don't see this tool in the tool list, and calling it anyway returns `Unknown tool: top_up_wallet`. See [Agent Payments](/agent-payments#mcp).

## Profile-Aware Automation

Browser Context Profiles let MCP automation reuse saved login state. If the user asks for an authenticated or recurring workflow, prefer a saved profile instead of logging in from scratch every run. Use `run_web_automation` with `use_profile: true`. If the user provides a profile ID, pass it as `profile_id`; `profile_id` requires `use_profile: true`. Pair with `use_vault: true` when the run should repair stale sessions with saved credentials.

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Summarize the account health dashboard",
  "use_profile": true,
  "use_vault": true
}
```

```json theme={null}
{
  "url": "https://app.example.com/dashboard",
  "goal": "Summarize the latest invoice, including the amount due and payment deadline.",
  "use_profile": true,
  "profile_id": "prof_abc123def4567890"
}
```

Create and save profiles from the [Browser Context Profiles API](/agent-api/browser-context-profiles) or dashboard before using them from MCP. API setup returns a `cdp_url` for Playwright/Puppeteer/CDP and a `base_url` for TinyFish HTTP session endpoints such as `/pages`. Browser Context Profiles are saved session state; [Browser Profiles](/key-concepts/browser-profiles) are the `browser_profile: "lite" | "stealth"` runtime modes.

## Example Usage

```
"Go to https://example.com and extract the product prices"

"Use my saved Salesforce profile to summarize the dashboard"

"Fill out the vendor onboarding form using these company details, then stop before submitting."

"Find overdue invoices in my billing dashboard and list each customer, amount due, and due date."

"Search for the best Italian restaurants in San Francisco"

"Scrape the pricing pages from these 5 competitor websites at the same time"

"Fetch https://docs.stripe.com/api/charges and summarize the API parameters"

"Create a browser session on https://example.com so I can control it with Playwright"
```

## Rates

| Tool | Rate |
| - | - |
| `search` | \$0.00 per request |
| `fetch_content` | \$0.00 per URL |
| `run_web_automation` | \$0.016 per step |
| `create_browser_session` | \$0.002 per browser-minute |
| `create_monitor` | \$0.005 per completed run, plus its Search or Fetch; failed runs are free |

Accounts on legacy credit plans bill 1 credit per step and 1 credit per 4 browser-minutes instead.

## Authentication

TinyFish MCP uses OAuth 2.1 for secure authentication. The first time you connect, your browser will open to complete the OAuth flow.

### Before You Start

Make sure you are signed in to both of these in your **default browser** before triggering the OAuth flow:

1. [claude.ai](https://claude.ai) — your Claude/Anthropic account
2. [agent.tinyfish.ai](https://agent.tinyfish.ai) — your TinyFish account

### Authentication Flow

When you first configure the TinyFish MCP server, your client will open your default browser to complete OAuth. Since you're already signed in to both services, the flow will redirect automatically and complete without manual input.

<Note>You need a TinyFish account. Search and Fetch are free within a daily allowance; Agent and Browser draw from your wallet (plan credits on legacy accounts). [Sign up here](https://agent.tinyfish.ai/api-keys).</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tool not showing up" icon="circle-question">
    1. Restart your AI client after adding the config
    2. Check that the config JSON is valid
    3. Ensure you're authenticated (OAuth prompt should appear)
  </Accordion>

  <Accordion title="Authentication failing" icon="lock">
    **Before starting the OAuth flow**, make sure you are already signed in to both services in your default browser:

    1. Open your default browser and sign in to [claude.ai](https://claude.ai)
    2. In the same browser, sign in to [agent.tinyfish.ai](https://agent.tinyfish.ai)
    3. Then restart your MCP client and trigger the OAuth flow again

    The OAuth redirect will open in your default browser. If you're not already signed in there, the flow will fail or get stuck.

    **Still not working?**

    * **Clear cookies** - Clear browser cookies for both claude.ai and agent.tinyfish.ai, then retry
    * **Check TinyFish account** - Verify your account is active at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys)
  </Accordion>

  <Accordion title="Server disconnected (Windows)" icon="windows">
    On Windows, if you see "Server disconnected" errors:

    1. **Close Claude Desktop completely** - Check Task Manager and end any Claude processes
    2. **Reinstall via the connector** - The [TinyFish connector](/plugins#claude) registers the server for you and avoids hand-edited config entirely
    3. **Complete OAuth quickly** - When the browser opens, complete the sign-in promptly to avoid timeout issues
  </Accordion>

  <Accordion title="Automation timing out" icon="clock">
    Complex automations may take 30-60 seconds. For sites with bot protection, the assistant should use `browser_profile: "stealth"`.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Get started with the REST API
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint documentation
  </Card>
</CardGroup>


# Monitor API Reference
Source: https://docs.tinyfish.ai/monitor/api-reference

Create and manage Page and Topic Monitors through the REST API

## Base URL

```text theme={null}
https://agent.tinyfish.ai
```

All requests require an `X-API-Key` header. See [Authentication](/authentication).

## Endpoints

| Method | Path | Description |
| - | - | - |
| `POST` | `/v1/monitors` | Create a Monitor and capture its baseline |
| `GET` | `/v1/monitors` | List your Monitors |
| `GET` | `/v1/monitors/{id}` | Get one Monitor |
| `PATCH` | `/v1/monitors/{id}` | Pause, resume, or edit a Monitor |
| `DELETE` | `/v1/monitors/{id}` | Delete a Monitor and its schedule |
| `POST` | `/v1/monitors/{id}/runs` | Run a Monitor immediately |

## Create a Monitor

<Tabs>
  <Tab title="Page">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://agent.tinyfish.ai/v1/monitors" \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "fetch",
          "name": "Competitor pricing",
          "config": {
            "url": "https://example.com/pricing",
            "format": "markdown"
          },
          "schedule_cron": "0 9 * * *",
          "purpose": "A plan price changes",
          "webhook_url": "https://example.com/webhooks/monitor"
        }'
      ```

      ```python Python theme={null}
      from tinyfish import TinyFish

      client = TinyFish()
      created = client.monitors.create(
          "fetch",
          {"url": "https://example.com/pricing", "format": "markdown"},
          "0 9 * * *",
          name="Competitor pricing",
          purpose="A plan price changes",
          webhook_url="https://example.com/webhooks/monitor",
      )
      print(created.monitor.id)
      ```

      ```typescript TypeScript theme={null}
      import { TinyFish } from "@tiny-fish/sdk";

      const client = new TinyFish();
      const { monitor, run } = await client.monitors.create({
        type: "fetch",
        name: "Competitor pricing",
        config: { url: "https://example.com/pricing", format: "markdown" },
        schedule_cron: "0 9 * * *",
        purpose: "A plan price changes",
        webhook_url: "https://example.com/webhooks/monitor",
      });
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Topic">
    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST "https://agent.tinyfish.ai/v1/monitors" \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "search",
          "name": "EV policy updates",
          "config": {
            "query": "new electric vehicle policies",
            "recency_minutes": 1440,
            "result_limit": 5
          },
          "schedule_cron": "0 */6 * * *",
          "purpose": "A new policy is announced"
        }'
      ```

      ```python Python theme={null}
      from tinyfish import TinyFish

      client = TinyFish()
      created = client.monitors.create(
          "search",
          {"query": "new electric vehicle policies", "recency_minutes": 1440, "result_limit": 5},
          "0 */6 * * *",
          name="EV policy updates",
          purpose="A new policy is announced",
      )
      print(created.monitor.id)
      ```

      ```typescript TypeScript theme={null}
      import { TinyFish } from "@tiny-fish/sdk";

      const client = new TinyFish();
      const { monitor, run } = await client.monitors.create({
        type: "search",
        name: "EV policy updates",
        config: {
          query: "new electric vehicle policies",
          recency_minutes: 1440,
          result_limit: 5,
        },
        schedule_cron: "0 */6 * * *",
        purpose: "A new policy is announced",
      });
      ```
    </CodeGroup>
  </Tab>
</Tabs>

The response is `201 Created` and contains the new Monitor plus its first baseline run:

```json theme={null}
{
  "monitor": {
    "id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
    "name": "Competitor pricing",
    "type": "fetch",
    "config": {
      "url": "https://example.com/pricing",
      "format": "markdown",
      "links": false,
      "image_links": false,
      "ttl": 0
    },
    "schedule_cron": "0 9 * * *",
    "status": "active",
    "last_error": null,
    "webhook_url": "https://example.com/webhooks/monitor",
    "created_at": "2026-09-09 09:00:00",
    "updated_at": "2026-09-09 09:00:00"
  },
  "run": {
    "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
    "is_baseline": true,
    "results": [
      {
        "url": "https://example.com/pricing",
        "final_url": "https://example.com/pricing",
        "title": "Pricing",
        "description": null,
        "language": "en",
        "format": "markdown",
        "text": "# Pricing",
        "author": null,
        "published_date": null,
        "latency_ms": 412
      }
    ],
    "errors": []
  }
}
```

Monitor responses do not currently echo `purpose` or dashboard-managed email settings.

### Common Fields

<ParamField type="string">
  `fetch` for a Page Monitor or `search` for a Topic Monitor.
</ParamField>

<ParamField type="object">
  Type-specific configuration. See the Page and Topic fields below.
</ParamField>

<ParamField type="string">
  A five-field cron expression. It runs in UTC unless prefixed with an IANA time zone, for example
  `CRON_TZ=America/New_York 0 9 * * 1-5`. Topic schedules must keep every run at least 30 minutes
  apart.
</ParamField>

<ParamField type="string">
  Optional Monitor name, up to 100 characters.
</ParamField>

<ParamField type="string">
  Optional description of the change that matters, up to 2000 characters. TinyFish evaluates
  detected changes against this purpose.
</ParamField>

<ParamField type="string">
  Optional public HTTP or HTTPS URL that receives every scheduled run result.
</ParamField>

<Note>
  Email delivery is currently configured in the dashboard. The REST API does not accept email
  settings.
</Note>

### Page Config

<ParamField type="string">
  Public HTTP or HTTPS webpage URL.
</ParamField>

<ParamField type="string">
  Extracted content format: `json`, `markdown`, or `html`.
</ParamField>

<ParamField type="boolean">
  Include links found on the webpage.
</ParamField>

<ParamField type="boolean">
  Include image links found on the webpage.
</ParamField>

Page Monitors always run Fetch with `ttl: 0` to prefer fresh content. The deprecated `config.ttl`
field is accepted for compatibility but does not change this behavior.

### Topic Config

<ParamField type="string">
  Search query to repeat, up to 2000 characters.
</ParamField>

<ParamField type="integer">
  Optional freshness window from 1 to 5,256,000 minutes.
</ParamField>

<ParamField type="integer">
  Number of results to compare per run, from 1 to 10.
</ParamField>

## List and Get Monitors

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://agent.tinyfish.ai/v1/monitors" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```

  ```python Python theme={null}
  monitors = client.monitors.list().monitors
  ```

  ```typescript TypeScript theme={null}
  const { monitors } = await client.monitors.list();
  ```
</CodeGroup>

The list response wraps Monitor objects in a `monitors` array. To retrieve one Monitor:

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```

  ```python Python theme={null}
  monitor = client.monitors.get(monitor_id)
  ```

  ```typescript TypeScript theme={null}
  const monitor = await client.monitors.get(monitorId);
  ```
</CodeGroup>

Saved run history is currently available in the dashboard. The REST API returns the baseline from
creation and the result of each run-now request, but does not provide a run-history list endpoint.

## Pause or Resume

Send a status-only update. `active` resumes the schedule and `paused` stops future scheduled runs
without removing history.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"status":"paused"}'
  ```

  ```python Python theme={null}
  client.monitors.pause(monitor_id)
  client.monitors.resume(monitor_id)
  ```

  ```typescript TypeScript theme={null}
  await client.monitors.pause(monitorId);
  await client.monitors.resume(monitorId);
  ```
</CodeGroup>

## Edit a Monitor

Schedule edits must include `schedule_cron`. You can also replace or clear the name, purpose, and
webhook URL. Omitted optional fields keep their existing values.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "schedule_cron": "CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
      "name": "Weekday pricing",
      "purpose": "The enterprise plan price changes",
      "webhook_url": null
    }'
  ```

  ```python Python theme={null}
  client.monitors.update(
      monitor_id,
      schedule_cron="CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
      name="Weekday pricing",
      purpose="The enterprise plan price changes",
      webhook_url=None,  # None clears; omit a field to keep it
  )
  ```

  ```typescript TypeScript theme={null}
  await client.monitors.update(monitorId, {
    schedule_cron: "CRON_TZ=America/Los_Angeles 0 8 * * 1-5",
    name: "Weekday pricing",
    purpose: "The enterprise plan price changes",
    webhook_url: null,
  });
  ```
</CodeGroup>

The target type and its `config` cannot be changed after creation. Create a new Monitor to watch a
different page or topic.

<Warning>
  Do not combine `status` with schedule or metadata fields in one request. Send lifecycle and edit
  updates separately.
</Warning>

## Run Now

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID/runs" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```

  ```python Python theme={null}
  run = client.monitors.run(monitor_id).run
  ```

  ```typescript TypeScript theme={null}
  const { run } = await client.monitors.run(monitorId);
  ```
</CodeGroup>

The response is `201 Created` with the Page Fetch result or Topic Search result under `run`. Run now
works for active, paused, and failed Monitors.

A Topic Monitor run can return `409 Conflict` with `error.code` set to `RETRY_REQUIRED` when the run
could not be created. Retry the request.

<Note>
  Run now records the result but does not send webhook or email notifications. Those delivery paths
  run only for scheduled checks.
</Note>

## Delete a Monitor

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://agent.tinyfish.ai/v1/monitors/$MONITOR_ID" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```

  ```python Python theme={null}
  client.monitors.cancel(monitor_id)
  ```

  ```typescript TypeScript theme={null}
  await client.monitors.cancel(monitorId);
  ```
</CodeGroup>

Deleting a Monitor permanently removes the Monitor and its schedule. Its run history is no longer
available from Monitor.

```json theme={null}
{
  "deleted": true,
  "id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7"
}
```

## Scheduled Webhook Payloads

Webhooks are sent for every scheduled run, including runs with no changes. Page payloads include a
`fetch_monitor_id`; Topic payloads include a `search_monitor_id`.

<Tabs>
  <Tab title="Page">
    ```json theme={null}
    {
      "fetch_monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
      "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
      "is_baseline": false,
      "results": [
        {
          "url": "https://example.com/pricing",
          "final_url": "https://example.com/pricing",
          "title": "Pricing",
          "description": null,
          "language": "en",
          "format": "markdown",
          "text": "# Pricing",
          "author": null,
          "published_date": null,
          "latency_ms": 398
        }
      ],
      "errors": []
    }
    ```
  </Tab>

  <Tab title="Topic">
    ```json theme={null}
    {
      "search_monitor_id": "e047c12d-5e82-43db-a826-cd45bc3ca4b7",
      "id": "a497ee29-e1d4-4477-a285-ec86b35cff2c",
      "request_id": "search-monitor:e047c12d:scheduled:message-id",
      "query": "new electric vehicle policies",
      "status_code": 200,
      "result_count": 1,
      "results": [
        {
          "position": 1,
          "site_name": "example.gov",
          "title": "New electric vehicle policy",
          "snippet": "The policy takes effect next year.",
          "url": "https://example.gov/ev-policy"
        }
      ],
      "new_result_positions": [],
      "created_at": "2026-09-09T16:00:00.000Z"
    }
    ```
  </Tab>
</Tabs>

Webhook delivery is best effort and retried up to three times. A delivery failure does not change
the completed Monitor run.


# Monitor
Source: https://docs.tinyfish.ai/monitor/index

Track a webpage or topic on a schedule and receive updates when it changes

Monitor checks a webpage or web topic on a recurring schedule, keeps a history of each run, and
shows what changed. You can review results in the TinyFish dashboard or send them to a webhook or
email address.

## Choose What to Monitor

| Monitor | Best for | How changes are detected | API type |
| - | - | - | - |
| **Page** | A known webpage, such as a pricing or status page | Compares the extracted page content with the previous run | `fetch` |
| **Topic** | Updates that may appear across the web | Identifies new URLs in the latest search results | `search` |

Page Monitors run Fetch with `ttl: 0` so they prefer fresh content. Topic Monitors can return 1-10
results per run and cannot run more often than every 30 minutes.

## Pricing

Each completed run costs $0.005 from your wallet, for Page and Topic Monitors alike. Each run also
makes one Search (Topic Monitor) or one Fetch (Page Monitor), billed the same as calling Search or
Fetch yourself, so it counts toward your daily free Search or Fetch allowance. Failed runs are not
charged. The run fee for a Monitor that runs daily is about $0.15 a month; hourly, about \$3.65.
Email, webhook delivery, and change detection are included.

## Create a Monitor

<Steps>
  <Step title="Open Monitor">
    Go to [agent.tinyfish.ai/monitor](https://agent.tinyfish.ai/monitor) and select **New monitor**.
  </Step>

  <Step title="Choose Page or Topic">
    For a Page Monitor, enter a public HTTP or HTTPS URL. For a Topic Monitor, enter the search
    query you want TinyFish to repeat.
  </Step>

  <Step title="Set the schedule">
    Choose how often the Monitor should run. Topic Monitors must be scheduled at least 30 minutes
    apart.
  </Step>

  <Step title="Choose delivery">
    Optionally add a webhook URL or turn on email updates. The account email is used as the default
    recipient, and you can replace it with another address.
  </Step>
</Steps>

You can also give the Monitor a name and describe the change that matters, such as `The price drops
below $500`. When content changes, TinyFish evaluates the change against that purpose and displays
the assessment with the run.

<Info>
  Creating a Monitor runs it immediately to capture a baseline. Future runs are compared with the
  latest completed result.
</Info>

Each account can have up to 50 Monitors. Delete a Monitor you no longer need to create another.

## Understand Run Results

Each run has one of three outcomes:

| Outcome | Meaning |
| - | - |
| **Baseline captured** | The first successful result was saved for future comparisons. |
| **Changed** | A Page's extracted content changed, or a Topic returned at least one new URL. |
| **No changes** | The result matched the previous comparable run. |

For Page Monitors, open a changed run to switch between the current result and a unified diff. For
Topic Monitors, the run identifies the new result positions.

## Delivery

| Destination | Behavior |
| - | - |
| **Dashboard** | Every run is recorded in the Monitor's run history. |
| **Webhook** | Every scheduled run is posted to the configured public URL, including runs with no changes. Failed deliveries are retried up to three times. |
| **Email updates** | With **Email every run** off, email is sent only when a change is detected. With it on, every completed scheduled run sends an email, including runs with no changes. |

<Note>
  **Run now** saves a new result in the dashboard but does not send webhook or email notifications.
  Notifications are sent by scheduled runs only.
</Note>

## Manage a Monitor

Open a Monitor from the dashboard to:

* **Run now** without waiting for the next scheduled check
* **Pause** future scheduled checks and resume them later
* **Edit** its name, purpose, schedule, webhook, and email delivery settings
* **Delete** the Monitor and its schedule

Pausing does not remove existing run history. Resuming recreates the schedule from the Monitor's
current configuration.

## Use the API

The REST API supports creating, listing, reading, updating, pausing, resuming, deleting, and running
Monitors.

<CardGroup>
  <Card title="Monitor API Reference" icon="code" href="/monitor/api-reference">
    Create and manage Monitors over REST
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Set up an API key
  </Card>

  <Card title="Fetch API" icon="bolt" href="/fetch-api">
    Learn how Page content is extracted
  </Card>
</CardGroup>


# Plugins
Source: https://docs.tinyfish.ai/plugins/index

Install the TinyFish plugin in ChatGPT, Claude, or Grok — curated skills, safety rules, and OAuth with no API keys

The TinyFish plugin gives your AI assistant live web powers: search the web, read any page, and run multi-step browser automations. Unlike pointing a client at our raw [MCP server](/mcp-integration), a plugin bundles the automation tools **plus** curated skills, safety rules, and a one-command (or one-tap) OAuth install — no API keys to paste.

<CardGroup>
  <Card title="ChatGPT" icon="comment" href="#chatgpt">
    One-tap add in your browser
  </Card>

  <Card title="Claude" icon="message" href="#claude">
    One-tap add from the Claude directory
  </Card>

  <Card title="Grok" icon="terminal" href="#grok">
    Install from the Grok CLI marketplace
  </Card>
</CardGroup>

<Note>
  Just want the raw MCP endpoint for another client (Codex, Cursor, Windsurf, Claude Code)? See [MCP Integration](/mcp-integration).
</Note>

## What you can do

Every plugin exposes the same TinyFish web powers:

* **Search the live web** — current, real results instead of the model's memory.
* **Read any page** — hand it a link and it pulls the page back clean, ready to reason over.
* **Get things done** — navigate sites, fill forms, and finish multi-step tasks in a live browser.

For the full tool list, see [Available Tools](/mcp-integration#available-tools).

## ChatGPT

A one-tap add in the browser — no code and no keys.

<Steps>
  <Step title="Open the plugin">
    Open the official TinyFish plugin on chatgpt.com:

    <Card title="Add TinyFish to ChatGPT" icon="arrow-up-right-from-square" href="https://chatgpt.com/plugins/plugin_asdk_app_695325bae7348191b58ae9349a963d22">
      Opens the TinyFish plugin in a new tab
    </Card>
  </Step>

  <Step title="Add it and authenticate">
    Tap **Install plugin** to enable the plugin, then complete the OAuth sign-in with your TinyFish account when prompted.
  </Step>
</Steps>

## Claude

A one-tap add in the browser — no code and no keys.

<Steps>
  <Step title="Open the connector">
    Open the official TinyFish connector in the Claude directory:

    <Card title="Add TinyFish to Claude" icon="arrow-up-right-from-square" href="https://claude.ai/directory/tinyfish">
      Opens the TinyFish connector in a new tab
    </Card>
  </Step>

  <Step title="Connect your account">
    Tap **Connect**, then **Allow** on the `accounts.tinyfish.ai` page to authorize with your TinyFish account.
  </Step>
</Steps>

Once installed, try your first run — paste this into a new Claude chat:

```text theme={null}
Use /tinyfish:search to find newly released or rapidly growing AI developer projects this week, fetch their documentation and READMEs, and explain what each is useful for
```

## Grok

Install from the Grok CLI marketplace. The TinyFish plugin ships five skills (`tinyfish-web`, `tinyfish-research`, `tinyfish-automation`, `tinyfish-authenticated`, `tinyfish-browser`) and a safety-rules layer covering credential handling, untrusted content, and bot-detection confirmations.

<Steps>
  <Step title="Install the plugin">
    ```bash theme={null}
    grok plugin install tinyfish --trust
    ```

    Or install it interactively from `/marketplace` inside Grok.
  </Step>

  <Step title="Authenticate">
    Open `/mcps`, select **tinyfish**, and authenticate through the browser. The plugin uses OAuth 2.1 — no API key storage — and connects to TinyFish's hosted MCP server at `https://agent.tinyfish.ai/mcp`. A TinyFish account is required.
  </Step>
</Steps>

<Accordion title="No CLI? Add it in the browser" icon="globe">
  You can add TinyFish as a connector from the Grok web app instead — this wires up the raw MCP server (search, fetch, and automation tools) without the bundled skills.

  1. Go to [grok.com/connectors](https://grok.com/connectors) and click **New Connector → Custom**.

  2. Enter the MCP server URL:

     ```text theme={null}
     https://agent.tinyfish.ai/mcp
     ```

  3. Save, then authenticate with your TinyFish account via OAuth when prompted.
</Accordion>

<Tip>
  Prefer the command line for the raw MCP server? Use `grok mcp add --transport http tinyfish https://agent.tinyfish.ai/mcp` — see [MCP Integration](/mcp-integration#quick-install).
</Tip>


# Goal Prompting Guide
Source: https://docs.tinyfish.ai/prompting-guide

Write goals that make TinyFish Web Agent work like magic

This guide teaches you how to write goals that succeed on the first try. The examples are tested against real production traffic. The patterns work. Copy them, modify them, use them.

<Info>
  **Quantified impact:** In testing, specific goals completed **4.9x faster** and returned **16x less unnecessary data** compared to vague goals for the same task.
</Info>

## The Mental Model

Think of TinyFish Web Agent as a capable but literal-minded assistant sitting in front of a browser.

**What it can do:**

* See exactly what you would see on the screen
* Click, type, scroll, and navigate
* Wait for dynamic content to load
* Follow instructions precisely
* Return structured data
* Navigate multi-page PDFs and extract content
* Remember information across workflow steps
* Parse natural language into form fields

**What it cannot do:**

* Read your mind about what you meant
* Guess what to do when something unexpected happens
* Know your business context unless you tell it
* Decide on output format without explicit instructions

Your job is to remove ambiguity. The more explicit your goal, the higher your success rate.

## Match Goal Style to Task Type

Different tasks benefit from different goal-writing approaches:

| Task Type | Recommended Style | Key Principle |
| - | - | - |
| Price/product extraction | Specific, constrained | List exact fields, exclude extras |
| Form filling | Natural language | Describe the person/entity, let agent map fields |
| Multi-step workflows | Numbered steps | Enable cross-step memory references |
| Batch execution | Minimal, strict schema | Only essential fields for consistency |

## The Anatomy of a Great Goal

Every effective goal has up to seven components. Simple tasks may need only two or three. Complex extractions benefit from all seven.

| Component | Purpose | Example |
| - | - | - |
| Objective | What to achieve | "Extract pricing information" |
| Target | Where to focus | "from the pricing table" |
| Fields | What data to extract | "product name, price, availability" |
| Schema | Output structure | "Return as JSON with keys: name, price" |
| Steps | Sequence of actions | "Close the cookie banner first" |
| Guardrails | What NOT to do | "Do not click purchase buttons" |
| Edge cases | Handle the unexpected | "If price shows 'Contact Us', set to null" |

## The Transformation Pattern

Here's how the same task looks at three quality levels:

<Tabs>
  <Tab title="Vague (fails)">
    ```
    Get the pricing from this page
    ```

    The agent doesn't know what "pricing" means to you. Annual vs monthly? Features included? What format?
  </Tab>

  <Tab title="Better (might work)">
    ```
    Extract the product name, price, and stock status. Return as JSON.
    ```

    Clearer, but still ambiguous. What if there are multiple prices? What JSON structure?
  </Tab>

  <Tab title="Production-ready">
    ```
    Extract the following from this product page:
    - Product name (full title as displayed)
    - Current price (number only, no currency symbol)
    - Original price if on sale, otherwise null
    - Currency code
    - In stock (true/false)

    If a cookie banner appears, close it first.
    Do not click any Add to Cart or purchase buttons.
    If price shows "Contact for price", set current_price to null.

    Return as JSON with this structure:
    {
      "product_name": "string",
      "current_price": number or null,
      "original_price": number or null,
      "currency": "string",
      "in_stock": boolean
    }
    ```

    This tells the agent exactly what to do at every decision point.
  </Tab>
</Tabs>

## Task-Specific Examples

<Tabs>
  <Tab title="Data Extraction">
    For extraction, be specific and constrained to prevent over-fetching:

    ```
    Extract ONLY the following from the pricing table:
    - plan_name: string
    - monthly_price: number (no currency symbol)
    - annual_price: number (no currency symbol)
    - feature_count: integer

    Do not extract feature descriptions or marketing copy.
    Return as JSON array.
    ```
  </Tab>

  <Tab title="Form Filling">
    For forms, use natural language—the agent handles field mapping:

    ```
    Fill out the contact form with this information:

    John Smith is a software engineer at Acme Corp in San Francisco.
    His email is john.smith@acme.com and phone is 415-555-0123.
    He's interested in the Enterprise plan and wants a demo next week.

    Submit the form when complete.
    ```

    The agent maps "software engineer" to job title, "Acme Corp" to company, etc.
  </Tab>

  <Tab title="Multi-Step Workflow">
    For workflows, use numbered steps to enable cross-step memory:

    ```
    Complete this account verification workflow:

    1. Navigate to the login page and click "Forgot Password"
    2. Enter the email address: test@example.com
    3. Note the confirmation message shown (save this for later)
    4. Check the email inbox at the provided URL for the code
    5. Return to the original site and enter the code from step 4
    6. Confirm the new password form appears

    Return the confirmation message from step 3 and success/failure status.
    ```
  </Tab>
</Tabs>

## Single Runs vs. Batch Execution

Understanding when you're running a single task versus scaling to many is critical for goal design.

### Single Runs (Playground & Individual API Calls)

**When you use this:**

* Testing and validating goals in the Playground
* One-off extractions or automations
* Prototyping before scaling

**Goal design principles:**

* Focus on completeness—you want rich results from this one run
* Include detailed edge case handling since you can iterate
* Add verbose output instructions for debugging

### Batch Execution (Projects & Concurrent API Calls)

**When you use this:**

* Processing hundreds or thousands of URLs
* Scheduled monitoring jobs
* Building datasets at scale

**Goal design principles:**

* Optimize for consistency—every run should return identical structure
* Minimize fields to only what you need
* Use strict schemas for reliable downstream processing

| Aspect | Single Run | Batch Execution |
| - | - | - |
| Field count | More fields, richer data | Minimal fields, only essentials |
| Error handling | Verbose, for debugging | Structured, for automation |
| Schema strictness | Flexible | Exact match required |
| Edge cases | Detailed instructions | Fail-fast with error flags |
| Goal length | Longer, comprehensive | Shorter, focused |

## Schema Enforcement for Batch Runs

When running the same goal repeatedly, schema consistency is critical. Without explicit enforcement, the agent may return slightly different field names across runs.

**Best practice:** Provide an example schema with exact field names AND sample values.

```
Return JSON matching this exact structure:
{
  "product_name": "Example Product Title",
  "current_price": 29.99,
  "currency": "USD",
  "in_stock": true
}
```

Why sample values matter:

* Field names alone can be ambiguous (`price` vs `"price": "29.99"` vs `"price": 29.99`)
* Sample values clarify expected types (number vs string, boolean vs "yes/no")
* The agent mirrors the pattern it sees

<Warning>
  **Anti-pattern:** `Return as JSON with product name, price, and availability.`

  This might return `{"name": "..."}` one time and `{"product_name": "..."}` another.
</Warning>

## Goal Writing Tips

<AccordionGroup>
  <Accordion title="Specify output format" icon="code">
    Tell TinyFish Web Agent how to structure the response:

    ```
    Extract product data. Return as JSON with this structure:
    {
      "products": [
        { "name": string, "price": string, "rating": number }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Handle edge cases" icon="code-branch">
    Anticipate what might go wrong:

    ```
    Extract the price from the product page.
    If the product is out of stock, return { "price": null, "outOfStock": true }.
    If no price is found, return { "price": null, "error": "Price not found" }.
    ```
  </Accordion>

  <Accordion title="Use numbered steps for sequences" icon="list-ol">
    For multi-step workflows, number the steps:

    ```
    1. Click "Login"
    2. Enter username "demo@example.com"
    3. Enter password "demo123"
    4. Click "Submit"
    5. Wait for dashboard to load
    6. Extract the account balance shown in the header
    ```
  </Accordion>

  <Accordion title="Trigger cross-step memory explicitly" icon="brain">
    When data from one step is needed later, tell the agent to remember it:

    ```
    IMPORTANT: On Step 6, a verification code will be displayed.
    You MUST remember this code and enter it exactly on Step 7.
    ```

    Other phrases that work:

    * "Remember these values—you'll need them for verification"
    * "Note the confirmation number displayed"
    * "Save this for later"
  </Accordion>

  <Accordion title="Describe elements visually" icon="eye">
    When element IDs aren't known, describe visually:

    ```
    Click the blue "Add to Cart" button below the price
    ```

    Instead of:

    ```
    Click the button with id="add-to-cart-btn"
    ```
  </Accordion>

  <Accordion title="Set explicit boundaries" icon="ruler">
    Limit scope to avoid over-extraction:

    ```
    Extract the FIRST 10 products only from the current page.
    Do not click pagination or load more items.
    ```
  </Accordion>

  <Accordion title="Include termination conditions" icon="stop">
    Tell the agent when to stop:

    ```
    Stop when ANY of these is true:
    - You have extracted 20 items
    - No more "Load More" button exists
    - You have processed 5 pages
    - The page shows a login prompt
    ```
  </Accordion>

  <Accordion title="Use explicit fallbacks" icon="arrows-split-up-and-left">
    When a page might have multiple layouts:

    ```
    Extract the product price from this page.

    Primary approach: Look for the price in the main product details section.
    If not found: Check the "Buy Box" sidebar on the right.
    If still not found: Look for a "See price in cart" button.

    Return:
    {
      "price": number or null,
      "price_location": "main" or "sidebar" or "cart_required" or "not_found"
    }
    ```
  </Accordion>
</AccordionGroup>

## The Intern Test

Ask yourself: If I handed this goal to a smart but literal-minded intern who has never seen this website, would they:

* Know exactly where to look first?
* Know when to stop?
* Know what to do if something unexpected happens?
* Know the exact format I want the answer in?

If any answer is "they would have to guess," add more detail.

## Ready-to-Use Templates

Copy and modify these templates for your use cases.

<AccordionGroup>
  <Accordion title="Template A: Product Extraction" icon="box">
    ```
    Extract the following from this product page:
    - Product name (full title)
    - Current price (number only, no currency symbol)
    - Original price if on sale, otherwise null
    - Currency code
    - Availability status
    - Shipping information if shown

    If a cookie or consent banner appears, close it.
    Wait for the price to fully load before extracting.

    Return as JSON.
    ```
  </Accordion>

  <Accordion title="Template B: Listing Extraction" icon="list">
    ```
    Extract the first [N] listings from this page.

    For each listing, extract:
    - [Primary identifier: name, title, etc.]
    - [Key attributes: location, price, size, etc.]
    - [Secondary attributes as needed]
    - Listing URL

    If there is a "Load More" button, click it once before extracting.
    Scroll down to ensure all visible listings are loaded.

    Return as a JSON array.
    ```
  </Accordion>

  <Accordion title="Template C: Company Research" icon="building">
    ```
    Extract the following from this company/profile page:
    - Name
    - Description or tagline
    - Industry or category
    - Size or scale indicators
    - Location
    - Website or contact info if shown
    - Any key metrics displayed

    Return as JSON.
    ```
  </Accordion>

  <Accordion title="Template D: Multi-Page Navigation" icon="forward">
    ```
    Extract [data type] from this page.

    For each item, extract:
    - [Field definitions]

    After extracting from the current page:
    1. Look for a "Next" button or pagination link
    2. If found and you have fewer than [N] items, click it
    3. Wait for the new page to load
    4. Continue extracting

    Stop when you have [N] items or no more pages exist.

    Return all results as a single JSON array.
    ```
  </Accordion>

  <Accordion title="Template E: Search and Filter" icon="magnifying-glass">
    ```
    On this page:

    1. Find the search box
    2. Enter "[search query]"
    3. Click search or press Enter
    4. Wait for results to load
    5. Extract the first [N] results

    For each result, extract:
    - [Field definitions]

    Return as a JSON array.
    ```
  </Accordion>

  <Accordion title="Template F: PDF Extraction" icon="file-pdf">
    ```
    Extract the following from this PDF document:

    1. Navigate through all pages of the PDF
    2. For each page, extract:
       - [Specific content: tables, headings, paragraphs]
       - Page number

    If the PDF has a table of contents, use it to locate [specific section].
    Scroll through the entire document to ensure all pages are processed.

    Return as JSON with structure:
    {
      "document_title": "string",
      "total_pages": number,
      "extracted_content": [
        { "page": number, "content": "string or structured data" }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Template G: Form with Verification" icon="square-check">
    ```
    Complete this form workflow:

    1. Navigate to the form at [URL or describe location]
    2. Fill in the form with this information:
       [Natural language description of the data]
    3. Click Submit/Continue
    4. On the confirmation page, note the reference number or confirmation message
    5. If a verification step appears:
       - Note what verification is required
       - Complete it if possible
    6. Return to confirm final success state

    Return:
    {
      "form_submitted": boolean,
      "confirmation_reference": "string or null",
      "verification_required": "string description or null",
      "final_status": "success" or "pending_verification" or "failed"
    }
    ```
  </Accordion>

  <Accordion title="Template H: Extraction with Fallbacks" icon="arrows-split-up-and-left">
    ```
    Extract [data] from this page.

    Primary location: [main expected location]
    Fallback 1: [alternative location if primary missing]
    Fallback 2: [second alternative]

    For each item found, extract:
    - [Field definitions]
    - source_location: where the data was found

    If no data found in any location, return:
    {
      "success": false,
      "error": "data_not_found",
      "locations_checked": ["primary", "fallback1", "fallback2"]
    }
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting

Common issues and how to fix them:

| Issue | Likely Cause | Solution |
| - | - | - |
| Empty results | JavaScript didn't finish rendering | Add "Wait for \[specific element] to fully load" |
| Missing fields | Data hidden until interaction | Add "Click \[button] to expand" or "Scroll down first" |
| Wrong data | Goal was ambiguous | Be more specific about which section to extract from |
| Partial results | Pagination not handled | Add explicit "click Next" instructions with a limit |
| Blocked | Site has bot protection | Try `browser_profile: "stealth"` with proxy |
| Slow completion | Goal too vague | Add specific field constraints, reduce scope |
| Timeout | Task too complex | Break into smaller runs or add termination conditions |

<Note>
  Runs have a 10-minute timeout. Design goals to complete their core task well within that limit. For complex multi-step workflows, break them into smaller runs.
</Note>

## Observed Behaviors

TinyFish Web Agent handles common natural language variations automatically:

| Input | Interpreted As |
| - | - |
| "March 15, 1985" | 1985-03-15 |
| "tech" | Technology |
| "mornings" | Morning (9am-12pm) |
| "TX" | Texas |

<Note>
  Letter-based phone numbers like `555-WORK-123` may be converted to keypad digits (`555-967-5123`).
</Note>

## Known Limitations

| Limitation | Notes |
| - | - |
| CAPTCHAs | Cannot solve reCAPTCHA or similar challenges |
| Infinite scroll | May not scroll to load all content automatically |
| Login persistence | Use [Browser Context Profiles](/key-concepts/browser-context-profiles) when runs should reuse saved session state |

## Related

<CardGroup>
  <Card title="AI Integration Guide" icon="robot" href="/ai-integration">
    Integrate TinyFish Web Agent with your LLM
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete endpoint documentation
  </Card>

  <Card title="Examples" icon="flask" href="/examples/scraping">
    Real-world code examples
  </Card>

  <Card title="FAQ" icon="circle-question" href="/faq">
    Common questions answered
  </Card>
</CardGroup>


# Quick Start
Source: https://docs.tinyfish.ai/quick-start

Get your first web automation running in under 5 minutes

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.

```json Expected result theme={null}
{
  "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.

<Steps>
  <Step title="Sign in to TinyFish">
    [Sign up](https://agent.tinyfish.ai/sign-up) for a new account, or
    [log in](https://agent.tinyfish.ai/sign-in) if you already have one. New
    accounts start with \$8 of free usage, so you can run this example right
    away. If a billing error does come up, see
    [Troubleshooting](#troubleshooting) for how to fix it.
  </Step>

  <Step title="Get your API key">
    1. Go to the [API Keys page](https://agent.tinyfish.ai/api-keys)
    2. Click "Create API Key"
    3. Save the key to your shell environment so the SDKs and CLI can read it automatically

    <Warning>API keys are shown only once, at creation. Store them securely and never commit them to version control.</Warning>

    ```bash theme={null}
    export TINYFISH_API_KEY=sk-tinyfish-*****
    ```
  </Step>

  <Step title="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.

    <CodeGroup>
      ```bash Python theme={null}
      # 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
      ```

      ```bash TypeScript theme={null}
      npm i @tiny-fish/sdk
      # The SDK is ESM-only. Add "type": "module" so tsx loads it correctly.
      npm pkg set type=module
      ```

      ```bash CLI theme={null}
      npm install -g @tiny-fish/cli
      ```

      ```bash cURL theme={null}
      # No install needed — cURL ships with macOS and most Linux distros.
      curl --version
      ```
    </CodeGroup>
  </Step>

  <Step title="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.)

    <CodeGroup>
      ```python Python theme={null}
      # 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)
      ```

      ```typescript TypeScript theme={null}
      // first-automation.ts
      import { TinyFish } from "@tiny-fish/sdk";

      async function main() {
        const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

        const stream = await client.agent.stream({
          url: "https://scrapeme.live/shop",  // Target website to automate
          goal: "Extract the first 2 product names and prices",  // Natural language instruction
        });

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

      main();
      ```

      ```bash CLI theme={null}
      # No file to write — the CLI takes the goal and URL as arguments (see the next step).
      ```

      ```bash cURL theme={null}
      # No file to write — send the goal and URL as a JSON body (see the next step).
      ```
    </CodeGroup>

    <Tip>
      The `goal` is a plain-English instruction. See the [Prompting Guide](/prompting-guide) and [Structured Output](/key-concepts/structured-output) to reliably get JSON shaped exactly how you want it.
    </Tip>
  </Step>

  <Step title="Run it">
    Execute your automation. Each tab runs against the same goal and URL.

    <CodeGroup>
      ```bash Python theme={null}
      python first_automation.py
      ```

      ```bash TypeScript theme={null}
      npx tsx first-automation.ts
      ```

      ```bash CLI theme={null}
      tinyfish agent run "Extract the first 2 product names and prices" \
        --url https://scrapeme.live/shop --pretty
      ```

      ```bash cURL theme={null}
      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"
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify the output">
    What you see depends on how you ran the automation.

    **Python, TypeScript, and cURL** stream raw [Server-Sent Events](/key-concepts/runs) as the agent works. The final `COMPLETE` event carries your result:

    ```bash theme={null}
    {'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.
  </Step>
</Steps>

## Check your wallet balance

If your account is on TinyFish's wallet billing, automations draw from your wallet balance. Check your balance, auto-reload state, and rates any time:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()  # Reads TINYFISH_API_KEY from environment

  wallet = client.wallet.get()
  print(f"{wallet.available_balance} {wallet.currency}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

  const wallet = await client.wallet.get();
  console.log(`${wallet.available_balance} ${wallet.currency}`);
  ```

  ```bash CLI theme={null}
  tinyfish wallet status --pretty
  ```
</CodeGroup>

<Note>
  Accounts are on either wallet billing or a legacy subscription/credits plan. If yours is on the legacy plan, `GET /v1/wallet` returns a 404 with `error.code: "FEATURE_NOT_AVAILABLE"` — check your account at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys) instead.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Missing dependency or command not found" icon="box">
    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`
  </Accordion>

  <Accordion title="pip install fails on macOS" icon="python">
    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:

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="tsx fails with ERR_PACKAGE_PATH_NOT_EXPORTED" icon="js">
    `@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`:

    ```bash theme={null}
    npm pkg set type=module
    ```

    Then re-run `npx tsx first-automation.ts`.
  </Accordion>

  <Accordion title="Invalid or missing API key" icon="key">
    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](https://agent.tinyfish.ai/api-keys) — keys are shown only once on creation, so you can't recover an old one.
  </Accordion>

  <Accordion title="Insufficient credits" icon="credit-card">
    The run is rejected because your account doesn't have enough balance to start it. Accounts are on either wallet billing or a legacy subscription/credits plan.

    * **Wallet accounts:** check your balance with `GET /v1/wallet` (or `client.wallet.get()`, `tinyfish wallet status`) and add funds on the [wallet page](https://agent.tinyfish.ai/wallet) — minimum top-up is \$10.
    * **Legacy subscription/credit accounts:** top up credits, or switch to a workspace that has them, then retry.
    * Not sure which you're on? `GET /v1/wallet` returns 404 `FEATURE_NOT_AVAILABLE` if your account isn't wallet-enabled.
    * See [Error Codes](/error-codes) for the full error shape.
  </Accordion>
</AccordionGroup>

## Next Steps

Where you go next depends on what you're trying to build.

| Your goal | Start here |
| - | - |
| Building an app on the API | [Agent API Reference](/agent-api/reference) |
| Need stable, predictable output | [Structured Output](/key-concepts/structured-output) |
| Real-world scraping examples | [Examples](/examples/scraping) |
| Hard sites or bot protection | [Anti-Bot Guide](/anti-bot-guide) · [Browser Profiles](/key-concepts/browser-profiles) |

<CardGroup>
  <Card title="Agent API Reference" icon="code" href="/agent-api/reference">
    Streaming, async runs, and endpoint selection
  </Card>

  <Card title="Structured Output" icon="brackets-curly" href="/key-concepts/structured-output">
    Get consistent JSON shaped to your schema
  </Card>

  <Card title="Examples" icon="lightbulb" href="/examples/scraping">
    Copy-paste ready code for real use cases
  </Card>

  <Card title="Anti-Bot Guide" icon="shield-halved" href="/anti-bot-guide">
    Handle protected and high-friction sites
  </Card>
</CardGroup>


# Research Examples
Source: https://docs.tinyfish.ai/research-api/examples

Examples for filtering, continuations, and saved runs

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

## 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`.

```python theme={null}
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
```

## 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

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

## Retrieve Saved Runs

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

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

## Cancel a Running Run

```bash theme={null}
curl -X POST \
  "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID/cancel" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

```json theme={null}
{
  "research_run_id": "019...",
  "status": "CANCELLED",
  "cancelled": true
}
```


# Research API
Source: https://docs.tinyfish.ai/research-api/index

Create source-backed research reports and stream their progress

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

The TinyFish Research API searches, evaluates sources, and synthesizes a cited report from a natural-language query. Use
it when a question needs evidence across several sources rather than one search result or webpage.

```bash theme={null}
POST https://agent.tinyfish.ai/v1/automation/run-research
```

## Before You Start

<Steps>
  <Step title="Get your API key">
    Create an API key at [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys).
  </Step>

  <Step title="Store it in your environment">
    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for setup and troubleshooting.

## Your First Request

<CodeGroup>
  ```python Python theme={null}
  import os
  import httpx

  with httpx.stream(
      "POST",
      "https://agent.tinyfish.ai/v1/automation/run-research",
      headers={"X-API-Key": os.environ["TINYFISH_API_KEY"]},
      json={"query": "Compare long-duration energy storage approaches", "mode": "deep"},
      timeout=2700,
  ) as response:
      response.raise_for_status()
      for line in response.iter_lines():
          if line.startswith("data: "):
              print(line[6:])
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://agent.tinyfish.ai/v1/automation/run-research", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.TINYFISH_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "Compare long-duration energy storage approaches",
      mode: "deep",
    }),
  });

  for await (const chunk of response.body!) {
    process.stdout.write(new TextDecoder().decode(chunk));
  }
  ```

  ```bash cURL theme={null}
  curl --no-buffer https://agent.tinyfish.ai/v1/automation/run-research \
    -H "X-API-Key: $TINYFISH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Compare long-duration energy storage approaches",
      "mode": "deep"
    }'
  ```
</CodeGroup>

## What Success Looks Like

Each Server-Sent Events message is a `data:` line containing JSON. Save the run ID from `created` and stop reading after
`done`.

```text theme={null}
data: {"event":"created","research_run_id":"..."}
data: {"event":"plan_updated","iteration":1,...}
data: {"event":"final_result","result":"...","citations":[...]}
data: {"event":"done"}
```

## When to Use Research vs the Other APIs

* Use **Research** for a cited synthesis across multiple sources.
* Use **Search** for ranked links, snippets, and source discovery.
* Use **Fetch** when you already know which pages to extract.
* Use **Agent** when TinyFish should interact with websites.
* Use **Browser** when you need direct Playwright or CDP control.

## Read Next

<CardGroup>
  <Card title="Research reference" icon="code" href="/research-api/reference">
    Request fields, modes, stream events, limits, and retrieval
  </Card>

  <Card title="Research examples" icon="flask" href="/research-api/examples">
    Filtering, continuations, and saved runs
  </Card>
</CardGroup>


# Research API Reference
Source: https://docs.tinyfish.ai/research-api/reference

Complete reference for research requests, streams, and saved runs

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

## Endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/v1/automation/run-research` | `POST` | Start a research run and stream progress |
| `/v1/automation/run-research-async` | `POST` | Start asynchronously and return a run ID |
| `/v1/research-run/{research_run_id}/events` | `GET` | Attach or reconnect to progress |
| `/v1/research-run` | `GET` | List saved research runs |
| `/v1/research-run/{research_run_id}` | `GET` | Retrieve one saved run |
| `/v1/research-run/{research_run_id}/cancel` | `POST` | Cancel a running research run |

All endpoints use `https://agent.tinyfish.ai` and require the `X-API-Key` header.

<Note>
  Research must be enabled for the API key's account. `POST /v1/automation/run-research` returns `403` when it is not.
</Note>

## Modes

| Mode | Best for | Typical time |
| - | - | - |
| `deep` | Broader coverage and synthesis | 5–20 minutes |
| `max` | Complex research | 5–45 minutes |

An omitted mode selects `deep`. Both modes research with search and static fetches.

## Request Body

| Field | Type | Required | Notes |
| - | - | - | - |
| `query` | `string` | Yes | Research question, 1–2,000 characters |
| `mode` | `deep \| max` | No | Defaults to `deep` |
| `stream` | `boolean` | No | Emits synthesis text through `synthesis_delta` |
| `output_language` | `string` | No | BCP 47 tag such as `en`, `ja`, or `pt-BR` |
| `weak_sources_enabled` | `boolean` | No | Allows relevant social and community sources |
| `domain_type` | `web \| news \| research_paper` | No | Defaults to `web` |
| `after_date` | `YYYY-MM-DD` | No | Include results on or after this date |
| `before_date` | `YYYY-MM-DD` | No | Include results on or before this date |
| `recency_minutes` | `integer` | No | Include results from the last 1–5,256,000 minutes |
| `domain_filter` | `object` | No | Prefer, require, or block specified domains |
| `prior_run_id` | `string` | No | Seed a run with a completed report |
| `session_id` | `UUID` | No | Continue an earlier research session |

<Note>
  Do not combine `recency_minutes` with date filters. Date and recency filters are unavailable for `research_paper`.
  `session_id` and `prior_run_id` are mutually exclusive.
</Note>

## Event Stream

Accepted requests return `text/event-stream`, including when `stream` is omitted or false. Invalid input and other
pre-run failures return the standard JSON error body.

| Event | Purpose |
| - | - |
| `created` | Supplies the research run ID |
| `session` | Supplies a reusable conversation session ID |
| `plan_updated` | Reports current subquestions and searches |
| `sources_searched` | Lists candidate sources |
| `source_fetched` | Reports static source extraction |
| `partial_summary` | Supplies an intermediate synthesis |
| `synthesis_delta` | Streams report text when enabled |
| `synthesis_discarded` | Discard provisional content for the named checkpoint |
| `heartbeat` | Keep the long-running connection open |
| `evidence_snapshot` | Supplies the current evidence set |
| `final_result` | Supplies the report, citations, and termination reason |
| `run_stats` | Supplies final source and claim counts |
| `error` | Reports a pipeline failure |
| `done` | Terminates the stream |

Ordered `synthesis_delta` values reconstruct their matching summary or final result. Discard a provisional partial
checkpoint after `synthesis_discarded`. Heartbeats keep long-running connections open.

## Run Statuses

| Status | Meaning |
| - | - |
| `QUEUED` | Accepted and waiting for a research worker. |
| `RUNNING` | The run is in progress. |
| `COMPLETED` | The run finished and its report is saved. |
| `FAILED` | The pipeline failed before producing a report. |
| `CANCELLED` | The run was cancelled through the cancel endpoint. |
| `TIMED_OUT` | The run exceeded the time budget for its mode. |

`COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT` are terminal.

## List Saved Runs

`GET /v1/research-run` supports `status`, `query`, `created_after`, and `created_before`. Pagination uses `limit` from
1–100, `sort_direction=asc|desc`, and the returned `next_cursor`. Reuse a cursor only with the same sort direction.

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

```json theme={null}
{
  "data": [
    {
      "research_run_id": "019...",
      "status": "COMPLETED",
      "query": "Compare long-duration energy storage approaches",
      "quick_result": { "answer": "...", "citations": ["https://example.com"] },
      "quick_result_summary": "...",
      "deep_result": { "result": "...", "citations": ["https://example.com"] },
      "run_ids": [],
      "created_at": "2026-09-09T16:00:00.000Z",
      "completed_at": "2026-09-09T16:07:41.000Z"
    }
  ],
  "pagination": {
    "total": 34,
    "next_cursor": "eyJ...",
    "has_more": true
  }
}
```

`quick_result` holds answers from runs made before standard mode was removed; `deep_result` holds the report. Both are objects: read the
report from `deep_result.result`, not from `deep_result` itself. `quick_result_summary` is the one plain string.
`run_ids` lists the Agent runs a Max run started. Fields that do not apply to the run are `null`.

## Retrieve One Run

`GET /v1/research-run/{research_run_id}` returns the list fields plus the working state kept for the run.

```bash theme={null}
curl "https://agent.tinyfish.ai/v1/research-run/$RESEARCH_RUN_ID" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

| Field | Notes |
| - | - |
| `research_plan` | Subquestions and searches the run planned |
| `evidence` | Sources gathered, with the claims they support |
| `iterations` | Number of plan-search-synthesize iterations completed |

A run that does not exist returns HTTP `404`. A run owned by another API key returns HTTP `403`.

## Cancel a Run

Call `POST /v1/research-run/{research_run_id}/cancel` to cancel a running research run. The response reports whether
this request changed the run to `CANCELLED` and includes its current status.

```json theme={null}
{
  "research_run_id": "019...",
  "status": "CANCELLED",
  "cancelled": true
}
```

Cancellation is idempotent. A run that is already terminal returns HTTP `200` with `cancelled: false` and its current
status. A missing run, or a run owned by another API key, returns HTTP `404`.

## Limits

Research creation is limited by concurrent runs and by runs started per Pacific calendar day. While Research is in beta
both default to 5 per account. Contact support if you need higher limits.

The daily count includes runs still in progress as well as completed ones, so five in-flight runs exhaust the day's
allowance. Runs that fail, time out, or are cancelled do not count.

Daily-limit responses use HTTP `429` with `error.code` set to `DAILY_LIMIT_EXCEEDED`, carry `Retry-After` and
`X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` headers, and report the window in `error.details`.

```json theme={null}
{
  "error": {
    "code": "DAILY_LIMIT_EXCEEDED",
    "message": "Today's Research limit has been reached. Please try again later.",
    "details": {
      "capability": "big_search_completion",
      "limit": 5,
      "used": 5,
      "remaining": 0,
      "reason": "exhausted",
      "window": "pacific_day",
      "resets_at": "2026-09-10T07:00:00.000Z"
    }
  }
}
```

If the limit cannot be evaluated, the request returns HTTP `503` with `error.code` set to `SERVICE_BUSY`. Retry after a
short pause.

## Start asynchronously

Use `POST /v1/automation/run-research-async` to enqueue research and return immediately:

```bash theme={null}
curl -X POST https://agent.tinyfish.ai/v1/automation/run-research-async \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Compare long-duration energy storage approaches","mode":"deep"}'
```

After durable dispatch, the endpoint returns HTTP `200` with:

```json theme={null}
{ "research_run_id": "019a1234-1234-7000-8000-123456789abc", "error": null }
```

This follows TinyFish's asynchronous automation convention. Poll by ID to retrieve current status and results; the
worker may already be running when you receive it.

* `GET /v1/research-run/{id}` returns current state and saved partial/final results.
* `GET /v1/research-run/{id}/events` streams progress; reconnect with `Last-Event-ID`.
* `POST /v1/research-run/{id}/cancel` explicitly cancels work.

States are `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`, `CANCELLED`, and `TIMED_OUT`. The last four are terminal; stop
polling when one is returned. Partial results can exist on unsuccessful runs, so inspect `status` before treating a
report as complete. Disconnecting an event stream does not cancel the job. Retained progress events expire; polling
remains the durable source for saved results.

For a single-request stream, keep using `POST /v1/automation/run-research`. The request field `stream` controls
synthesis text deltas, not async versus SSE delivery. Both start endpoints accept the same research parameters and
limits.

Polling responses also include `error`: `null` for queued, running, or completed runs, otherwise `{code, message}` with
`TASK_FAILED`, `CANCELLED`, or `TIMEOUT`. These describe the persisted terminal outcome, not a
detailed provider failure. Existing result fields remain available, including partial reports.

Async starts are not idempotent. Retrying a POST after a timeout can create a
second run and incur additional usage. Keep the returned `research_run_id` and
poll or reconnect to that run. If no ID was received, the run may still have been
accepted; check your run list before starting another.

Incompatible optional fields in older saved runs return `null` and are logged;
other valid report fields remain readable.


# Search Examples
Source: https://docs.tinyfish.ai/search-api/examples

Real-world examples for the Search API

## Basic Search

Search the web and get structured results:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="web automation tools", location="US")

  for r in response.results:
      print(f"{r.position}. {r.title}")
      print(f"   {r.url}\n")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "web automation tools",
    location: "US",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title}`);
    console.log(`   ${r.url}\n`);
  }
  ```

  ```bash cURL theme={null}
  curl -s "https://api.search.tinyfish.ai?query=web+automation+tools&location=US" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

**Output:**

```json theme={null}
{
  "query": "web automation tools",
  "results": [
    {
      "position": 1,
      "site_name": "www.firecrawl.dev",
      "title": "Top 9 Browser Automation Tools for Web Testing and Scraping in ...",
      "snippet": "This guide covers 9 of the best tools across testing, scraping, and workflow automation...",
      "url": "https://www.firecrawl.dev/blog/browser-automation-tools-comparison"
    },
    {
      "position": 2,
      "site_name": "www.skyvern.com",
      "title": "Best Free Open Source Browser Automation Tools in 2025 - Skyvern",
      "snippet": "Developed by Microsoft, Playwright is the next generation of web automation tools...",
      "url": "https://www.skyvern.com/blog/best-free-open-source-browser-automation-tools-in-2025/"
    }
  ],
  "total_results": 10,
  "page": 0
}
```

## Search with Intent

Pass the optional `purpose` parameter to state *why* you are searching — the goal
the results will be used for. It is always optional, but supplying it gives the
search additional intent signal beyond the raw keywords, helping deliver
better-quality results.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(
      query="pdf invoice parser",
      purpose="Find an open-source library for parsing PDF invoices in Python",
  )

  for r in response.results:
      print(f"{r.position}. {r.title}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "pdf invoice parser",
    purpose: "Find an open-source library for parsing PDF invoices in Python",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title}`);
  }
  ```

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=pdf invoice parser" \
    --data-urlencode "purpose=Find an open-source library for parsing PDF invoices in Python" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## Include or Exclude Sites

Use `include_domains` to restrict results to specific domains, and `exclude_domains`
to remove domains from the results. Both take a comma-separated list of domains.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(
      query="python tutorial",
      include_domains="docs.python.org",
      location="US",
  )

  for r in response.results:
      print(f"{r.position}. {r.title} ({r.site_name})")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "python tutorial",
    include_domains: "docs.python.org",
    location: "US",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title} (${r.site_name})`);
  }
  ```

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=python tutorial" \
    --data-urlencode "include_domains=docs.python.org" \
    --data-urlencode "location=US" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

To exclude specific sites, use `exclude_domains`:

```bash cURL theme={null}
curl -G "https://api.search.tinyfish.ai" \
  --data-urlencode "query=recipe ideas" \
  --data-urlencode "exclude_domains=facebook.com,youtube.com" \
  --data-urlencode "location=US" \
  -H "X-API-Key: $TINYFISH_API_KEY"
```

<Note>
  **Deprecated:** domain filtering via `site:`/`-site:` operators inside the `query`
  string still works, but prefer `include_domains` / `exclude_domains` above.

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=python tutorial site:docs.python.org" \
    --data-urlencode "location=US" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=recipe ideas -site:facebook.com -site:youtube.com" \
    --data-urlencode "location=US" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</Note>

## Geo-Targeted Search

Get results localized to a specific country and language:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  # Search in French — location auto-resolves to FR
  response = client.search.query(query="meilleurs restaurants", language="fr")

  for r in response.results:
      print(f"{r.position}. {r.title} ({r.site_name})")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  // Search in French — location auto-resolves to FR
  const response = await client.search.query({
    query: "meilleurs restaurants",
    language: "fr",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title} (${r.site_name})`);
  }
  ```

  ```bash cURL theme={null}
  curl -s "https://api.search.tinyfish.ai?query=meilleurs+restaurants&language=fr" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

<Note>
  When only `language` is provided, `location` auto-resolves to the most common pairing (e.g. `fr` → `FR`, `ja` → `JP`). See the [Reference](/search-api/reference) for details.
</Note>

## Search + Fetch Pipeline

Combine Search with Fetch to get full page content from top results:

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()

  # Step 1: Search
  results = client.search.query(query="TinyFish web agent", location="US")
  top_urls = [r.url for r in results.results[:3]]

  # Step 2: Fetch full content
  pages = client.fetch.get_contents(urls=top_urls, format="markdown")
  for page in pages.results:
      print(f"## {page.title}")
      print(page.text[:200], "\n")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();

  // Step 1: Search
  const results = await client.search.query({
    query: "TinyFish web agent",
    location: "US",
  });
  const topUrls = results.results.slice(0, 3).map((r) => r.url);

  // Step 2: Fetch full content
  const pages = await client.fetch.getContents({
    urls: topUrls,
    format: "markdown",
  });
  for (const page of pages.results) {
    console.log(`## ${page.title}`);
    console.log(page.text.slice(0, 200), "\n");
  }
  ```
</CodeGroup>

***

## Freshness Filter

Use `recency_minutes` when you want a freshness window relative to now.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="FIFA", recency_minutes=60)

  for r in response.results:
      print(f"{r.position}. {r.title}")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "FIFA",
    recency_minutes: 60,
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title}`);
  }
  ```

  ```bash cURL theme={null}
  curl "https://api.search.tinyfish.ai?query=FIFA&recency_minutes=60" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## Date Window Search

Use `after_date` and `before_date` when you want a calendar date range.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(
      query="FIFA",
      after_date="2026-06-01",
      before_date="2026-06-18",
  )
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "FIFA",
    after_date: "2026-06-01",
    before_date: "2026-06-18",
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.search.tinyfish.ai?query=FIFA&after_date=2026-06-01&before_date=2026-06-18" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## News Search

Use `domain_type=news` to retrieve recent news articles. Results include `publisher` and `date` fields.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="AI regulation", domain_type="news", location="US")

  for r in response.results:
      print(f"{r.position}. {r.title}")
      print(f"   {getattr(r, 'publisher', '')} — {getattr(r, 'date', '')}")
      print(f"   {r.url}\n")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "AI regulation",
    domain_type: "news",
    location: "US",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title}`);
    console.log(`   ${r.publisher ?? ""} — ${r.date ?? ""}`);
    console.log(`   ${r.url}\n`);
  }
  ```

  ```bash cURL theme={null}
  curl "https://api.search.tinyfish.ai?query=AI+regulation&domain_type=news&location=US" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## Research Paper Search

Use `domain_type=research_paper` to search academic papers. Results include `authors`, `venue`, `year`, and `cited_by_count` fields.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="attention is all you need", domain_type="research_paper")

  for r in response.results:
      print(f"{r.position}. {r.title}")
      authors = getattr(r, 'authors', None) or []
      print(f"   Authors: {', '.join(authors)}")
      print(f"   Venue: {getattr(r, 'venue', '')}  Year: {getattr(r, 'year', '')}")
      print(f"   Citations: {getattr(r, 'cited_by_count', '')}")
      print(f"   {r.url}\n")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "attention is all you need",
    domain_type: "research_paper",
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title}`);
    console.log(`   Authors: ${(r.authors ?? []).join(", ")}`);
    console.log(`   Venue: ${r.venue ?? ""}  Year: ${r.year ?? ""}`);
    console.log(`   Citations: ${r.cited_by_count ?? ""}`);
    console.log(`   ${r.url}\n`);
  }
  ```

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=attention is all you need" \
    --data-urlencode "domain_type=research_paper" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## Research Paper Search by Publication Year

Use `pub_year_min` / `pub_year_max` with `domain_type=research_paper` to scope results to a publication-year range (inclusive integers, `0`-`9999`, with `pub_year_min <= pub_year_max` when both are set). These replace `after_date` / `before_date` / `recency_minutes`, which are not supported for `domain_type=research_paper`.

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(
      query="transformer architecture",
      domain_type="research_paper",
      pub_year_min=2019,
      pub_year_max=2022,
  )

  for r in response.results:
      print(f"{r.position}. {r.title} ({getattr(r, 'year', '')})")
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "transformer architecture",
    domain_type: "research_paper",
    pub_year_min: 2019,
    pub_year_max: 2022,
  });

  for (const r of response.results) {
    console.log(`${r.position}. ${r.title} (${r.year ?? ""})`);
  }
  ```

  ```bash cURL theme={null}
  curl -G "https://api.search.tinyfish.ai" \
    --data-urlencode "query=transformer architecture" \
    --data-urlencode "domain_type=research_paper" \
    --data-urlencode "pub_year_min=2019" \
    --data-urlencode "pub_year_max=2022" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

***

## Related

<CardGroup>
  <Card title="Search Reference" icon="magnifying-glass" href="/search-api/reference">
    Full parameter and response docs
  </Card>

  <Card title="Fetch Examples" icon="bolt" href="/fetch-api/examples">
    Extract page content from URLs
  </Card>
</CardGroup>


# Search API
Source: https://docs.tinyfish.ai/search-api/index

Search the web and get structured results via API

<Note>
  Search is free up to 12,000 requests per day. Beyond that, requests need a positive wallet balance.
</Note>

The TinyFish Search API lets you run web searches and get back structured results — titles, snippets, and URLs — ready for LLM consumption or programmatic use.

```bash theme={null}
GET https://api.search.tinyfish.ai
```

`api.search.tinyfish.ai` is the public Search API endpoint.

## Before You Start

<Steps>
  <Step title="Get your API key">
    Visit [agent.tinyfish.ai/api-keys](https://agent.tinyfish.ai/api-keys) and create a key. Store it in your environment:

    ```bash theme={null}
    export TINYFISH_API_KEY="your_api_key_here"
    ```
  </Step>
</Steps>

All requests require the `X-API-Key` header. See [Authentication](/authentication) for the full setup and troubleshooting guide.

## Your First Request

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="web automation tools")
  for r in response.results:
      print(r.title, "→", r.url)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({ query: "web automation tools" });
  response.results.forEach((r) => console.log(r.title, "→", r.url));
  ```

  ```bash cURL theme={null}
  curl "https://api.search.tinyfish.ai?query=web+automation+tools" \
    -H "X-API-Key: $TINYFISH_API_KEY"
  ```
</CodeGroup>

## What Success Looks Like

```json theme={null}
{
  "query": "web automation tools",
  "results": [
    {
      "position": 1,
      "site_name": "tinyfish.ai",
      "title": "TinyFish — AI Web Automation Platform",
      "snippet": "Automate any website with natural language instructions...",
      "url": "https://tinyfish.ai"
    },
    {
      "position": 2,
      "site_name": "github.com",
      "title": "Top Web Automation Tools in 2026",
      "snippet": "A curated list of browser automation frameworks...",
      "url": "https://github.com/example/web-automation-tools"
    }
  ],
  "total_results": 10,
  "page": 0
}
```

## When to Use Search vs the Other APIs

* Use **Search** when you need ranked search engine results, snippets, and URLs.
* Use **Fetch** when you already have the URLs and want extracted page content.
* Use **Agent** when you want TinyFish to browse and execute a workflow on the site.
* Use **Browser** when you need direct browser control from your own code.

***

## Geo-Targeted Results

Use the `location` and `language` parameters to get results tailored to a specific region.

***

## Freshness and Date Filters

Use `recency_minutes` when you want a freshness window, or `after_date` / `before_date` when you want a calendar date cutoff.

* `recency_minutes` accepts an integer from `1` to `5256000` (10 years).
* `after_date` and `before_date` must use `YYYY-MM-DD`.
* Do not combine `recency_minutes` with `after_date` or `before_date`.
* If you send both `after_date` and `before_date`, `after_date` must be less than or equal to `before_date`.

***

## Domain Types

Use `domain_type` to search a specific content category:

* `web` (default) — standard web results
* `news` — news articles with publisher and date fields
* `research_paper` — academic papers with authors, venue, year, and citation count

Date and recency filters (`after_date`, `before_date`, `recency_minutes`) are not supported for `domain_type=research_paper`. Use `pub_year_min` / `pub_year_max` instead to scope results by publication year (inclusive, `0`-`9999`).

***

## Search Intent

The optional `purpose` parameter lets you state *why* you are searching — the underlying goal or task the results will be used for. A query is often a terse set of keywords, and the intent behind it isn't always obvious from the keywords alone. Passing `purpose` gives us additional signal to further inform and deliver better-quality results.

* `purpose` is always optional. Omitting it leaves search behaviour unchanged.
* Keep it to a short phrase or sentence (maximum 2000 characters), for example `Find an open-source library for parsing PDF invoices in Python`.

***

## Read Next

<CardGroup>
  <Card title="API Reference" icon="code" href="/search-api/reference">
    Full request and response schema
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup
  </Card>

  <Card title="For coding agents" icon="robot" href="/for-coding-agents">
    One page that routes an agent to the right TinyFish API
  </Card>

  <Card title="Search Examples" icon="bolt" href="/search-api/examples">
    Common Search request patterns
  </Card>
</CardGroup>


# Search API Reference
Source: https://docs.tinyfish.ai/search-api/reference

Complete reference for the Search API endpoint

## Endpoint

```
GET https://api.search.tinyfish.ai
```

All requests require an `X-API-Key` header. See [Authentication](/authentication).

***

## Request

```
GET https://api.search.tinyfish.ai?query=web+automation+tools&location=US&language=en
```

### Parameters

<ParamField type="string">
  The search query string. **Deprecated for domain filtering:** the query string still
  accepts `site:`/`-site:` operators (e.g. `python tutorial site:docs.python.org` or
  `recipe ideas -site:facebook.com -site:youtube.com`), but prefer the dedicated
  `include_domains` / `exclude_domains` params below — they don't collide with other
  query syntax.
</ParamField>

<ParamField type="string">
  An optional short statement of **why** you are searching — the underlying goal or task the
  results will be used for. A query is often a terse set of keywords; supplying the intent behind
  it gives us additional signal to further inform and deliver better-quality results. When omitted,
  search behaves exactly as before. Maximum 2000 characters. For example,
  `Find an open-source library for parsing PDF invoices in Python`.
</ParamField>

<ParamField type="string">
  Country code for geo-targeted results (e.g. `US`, `GB`, `FR`, `DE`). When omitted, auto-resolves based on `language` (e.g. `fr` → `FR`). Defaults to `US` if both `location` and `language` are omitted.
</ParamField>

<ParamField type="string">
  Language code for result language (e.g. `en`, `fr`, `de`). When omitted, auto-resolves based on `location` (e.g. `FR` → `fr`). Defaults to `en` if both `location` and `language` are omitted.
</ParamField>

<ParamField type="string">
  Comma-separated list of domains to restrict results to (e.g. `github.com,arxiv.org`).
</ParamField>

<ParamField type="string">
  Comma-separated list of domains to exclude from results (e.g. `pinterest.com,quora.com`).
</ParamField>

<ParamField type="number">
  Freshness window in minutes. Must be an integer from `1` to `5256000` (10 years). Use this when you want recent results relative to now, such as `60` for the last hour.
</ParamField>

<ParamField type="string">
  Lower date bound in `YYYY-MM-DD` format. Use this when you want results after a calendar date cutoff, such as `2026-06-01`.
</ParamField>

<ParamField type="string">
  Upper date bound in `YYYY-MM-DD` format. Use this when you want results before a calendar date cutoff, such as `2026-06-18`.
</ParamField>

<ParamField type="string">
  Type of search to perform. One of `"web"` (default), `"news"`, or `"research_paper"`. Use `"news"` to retrieve recent news articles with publisher and date; use `"research_paper"` to search academic papers with authors, venue, and citation count.
</ParamField>

<ParamField type="number">
  Lower publication-year bound, inclusive. Must be an integer from `0` to `9999`, and no greater than `pub_year_max` if both are set. Only supported for `domain_type=research_paper`.
</ParamField>

<ParamField type="number">
  Upper publication-year bound, inclusive. Must be an integer from `0` to `9999`, and no less than `pub_year_min` if both are set. Only supported for `domain_type=research_paper`.
</ParamField>

<ParamField type="number">
  Page number for pagination, starting from `0` (e.g. `2` to retrieve the third page of results). Maximum value is `10`.
</ParamField>

<Note>
  **Freshness and date filter rules:** `recency_minutes` cannot be combined with `after_date` or `before_date`. If you send both `after_date` and `before_date`, they must be valid `YYYY-MM-DD` values and `after_date` must be less than or equal to `before_date`.
</Note>

<Note>
  **Research paper date restrictions:** `after_date`, `before_date`, and `recency_minutes` are not supported for `domain_type=research_paper`. Use `pub_year_min` / `pub_year_max` to scope by publication year instead (e.g. `pub_year_min=2017&pub_year_max=2017`).
</Note>

<Note>
  **Location & language auto-resolution:** If only one of `location` or `language` is provided, the other is automatically resolved to the most predominant pairing. For example, setting `location=BR` without `language` resolves to `language=pt`. Setting `language=ja` without `location` resolves to `location=JP`. If neither is set, they default to `US` and `en`.
</Note>

***

## Response

```json theme={null}
{
  "query": "web automation tools",
  "results": [...],
  "total_results": 10,
  "page": 0
}
```

### Top-level fields

<ResponseField name="query" type="string">
  The search query that was executed.
</ResponseField>

<ResponseField name="results" type="object[]">
  Array of search results.
</ResponseField>

<ResponseField name="total_results" type="number">
  Total number of results returned.
</ResponseField>

<ResponseField name="page" type="number">
  The current page number, starting from `0`.
</ResponseField>

### `results[]`

<ResponseField name="position" type="number">
  Position in search results (1-indexed).
</ResponseField>

<ResponseField name="site_name" type="string">
  Domain name of the result.
</ResponseField>

<ResponseField name="title" type="string">
  Page title.
</ResponseField>

<ResponseField name="snippet" type="string">
  Text snippet from the result.
</ResponseField>

<ResponseField name="url" type="string">
  URL of the result.
</ResponseField>

<ResponseField name="date" type="string">
  Publication date. Present for news results and some web results.
</ResponseField>

<ResponseField name="publisher" type="string">
  Publisher name. Present for news results (`domain_type=news`).
</ResponseField>

<ResponseField name="authors" type="string[]">
  Author list. Present for academic results (`domain_type=research_paper`).
</ResponseField>

<ResponseField name="venue" type="string">
  Journal or conference name. Present for academic results (`domain_type=research_paper`).
</ResponseField>

<ResponseField name="year" type="number">
  Publication year. Present for academic results (`domain_type=research_paper`).
</ResponseField>

<ResponseField name="cited_by_count" type="number">
  Citation count. Present for academic results (`domain_type=research_paper`).
</ResponseField>

<ResponseField name="pdf_url" type="string">
  PDF URL. Present for academic results when a PDF is available (`domain_type=research_paper`).
</ResponseField>

## SDK Methods

<CodeGroup>
  ```python Python theme={null}
  from tinyfish import TinyFish

  client = TinyFish()
  response = client.search.query(query="web automation tools", location="US")
  for r in response.results:
      print(r.title, "→", r.url)
  ```

  ```typescript TypeScript theme={null}
  import { TinyFish } from "@tiny-fish/sdk";

  const client = new TinyFish();
  const response = await client.search.query({
    query: "web automation tools",
    location: "US",
  });
  response.results.forEach((r) => console.log(r.title, "→", r.url));
  ```
</CodeGroup>

***

## Error Codes

| Status | Meaning |
| - | - |
| `400` | Invalid request — missing `query` parameter or bad parameter value |
| `401` | Missing or invalid API key |
| `402` | Daily free allowance used and wallet balance is zero or below (`INSUFFICIENT_CREDITS`) — add funds at the [wallet page](https://agent.tinyfish.ai/wallet) or wait for the daily reset. `FREE_ALLOWANCE_EXHAUSTED` when the allowance is used and the product does not charge the wallet (beta) — wait for the daily reset |
| `403` | Search request forbidden by the upstream service |
| `404` | Search API is not available |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `503` | Search service or rate limiting unavailable — retry with backoff |

## Rate Limits

Limits apply per API key, measured in requests per minute across all requests. Accounts default to 30 requests / minute. When the limit is exceeded, the API returns `HTTP 429`.

***

## Billing

Search is free up to 12,000 requests per day; the allowance resets at 00:00 UTC. Beyond it, requests need a positive wallet balance: with a balance of zero or below the API returns `HTTP 402` with code `INSUFFICIENT_CREDITS` until you add funds or the allowance resets. After a top-up, allow a few seconds for the balance to apply. A product that does not charge the wallet (beta) returns `FREE_ALLOWANCE_EXHAUSTED` instead once its allowance is used; only the daily reset lifts it.

***

## Related

<CardGroup>
  <Card title="Search Overview" icon="magnifying-glass" href="/search-api">
    First request, success shape, and product routing
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    API key setup and troubleshooting
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/error-codes">
    Full list of API error codes
  </Card>
</CardGroup>


# Build with AI
Source: https://docs.tinyfish.ai/using-with-ai

Give your AI coding assistant context on TinyFish Web Agent

Set up TinyFish Web Agent in minutes using your AI coding assistant. Just copy the prompt below, drop it into Claude, Cursor, or ChatGPT, and start building your web agent.

## Three Ways to Get Started

<CardGroup>
  <Card title="Automation MCP" icon="robot" href="#automation-mcp-server">
    Let your AI assistant run web automations directly
  </Card>

  <Card title="Docs MCP" icon="book" href="#docs-mcp-server">
    Give your AI assistant searchable access to TinyFish docs
  </Card>

  <Card title="Integration Prompt" icon="clipboard" href="#integration-prompt">
    Paste into any AI assistant to generate custom integration code
  </Card>
</CardGroup>

## Automation MCP Server

Connect TinyFish as a tool in your AI assistant so it can browse websites, extract data, and complete multi-step automations on your behalf. Supports Claude Code, Codex, Cursor, Windsurf, and any MCP client. On Claude, ChatGPT, or Grok, use the [TinyFish plugin](/plugins) instead.

See the [MCP Integration guide](/mcp-integration) for setup instructions, available tools, and troubleshooting.

***

## Docs MCP Server

Give your AI assistant searchable access to TinyFish documentation so it can look up API references, code examples, and guides while helping you build integrations.

### Quick Install

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client claude-code
    ```

    Restart Claude Code for the MCP to load.
  </Tab>

  <Tab title="Cursor">
    ```bash theme={null}
    npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client cursor
    ```
  </Tab>

  <Tab title="Windsurf">
    ```bash theme={null}
    npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client windsurf
    ```
  </Tab>

  <Tab title="Claude Desktop">
    ```bash theme={null}
    npx -y install-mcp@latest https://docs.tinyfish.ai/mcp --client claude
    ```
  </Tab>
</Tabs>

<Accordion title="Manual configuration" icon="gear">
  <Tabs>
    <Tab title="Claude Code">
      ```bash theme={null}
      claude mcp add --transport http tinyfish-docs https://docs.tinyfish.ai/mcp
      ```
    </Tab>

    <Tab title="Cursor">
      Add to your Cursor MCP settings:

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish-docs": {
            "url": "https://docs.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>

    <Tab title="Windsurf">
      Add to `~/.codeium/windsurf/mcp_config.json` (macOS/Linux) or `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (Windows):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish-docs": {
            "serverUrl": "https://docs.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>

    <Tab title="Claude Desktop">
      Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

      ```json theme={null}
      {
        "mcpServers": {
          "tinyfish-docs": {
            "url": "https://docs.tinyfish.ai/mcp"
          }
        }
      }
      ```
    </Tab>
  </Tabs>
</Accordion>

***

## Integration Prompt

Use this prompt to have your AI assistant generate TinyFish Web Agent integration code tailored to your project.

<Note>
  Copy the entire code block and paste it into Claude, ChatGPT, Cursor, or any AI coding assistant.
</Note>

<Accordion title="Expand to copy prompt" icon="clipboard">
  ````
  I need help integrating TinyFish Web Agent into my project. TinyFish Web Agent is a web automation API that uses natural language to control browsers - no CSS selectors or XPath needed.

  **TinyFish Web Agent capabilities:**
  - Navigate to websites and perform actions (clicks, form fills, scrolling)
  - Extract structured data from any page as JSON
  - Handle multi-step workflows with a single API call
  - Work on authenticated and bot-protected sites

  Please ask me these questions first:

  1. What am I building?
     - Data extraction / scraping
     - Form automation
     - Web monitoring
     - AI agent with web browsing
     - Something else

  2. Which endpoint should I use?
     - Synchronous (/run) - wait for result, simple code
     - Async (/run-async) - start task, poll for result later
     - Streaming (/run-sse) - real-time progress updates

  3. What's my tech stack?
     - TypeScript / JavaScript
     - Python
     - Other

  4. Will I need anti-detection?
     - No - standard websites
     - Yes - sites with Cloudflare, CAPTCHAs, or bot protection

  Then generate code using these patterns:

  ---

  **Environment Setup**

  ```bash
  # Get your API key at https://agent.tinyfish.ai/api-keys
  # Add to .env file:
  TINYFISH_API_KEY=sk-tinyfish-*****
  ```

  ---

  **TypeScript - Streaming (Recommended)**

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

  const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

  async function runAutomation(url: string, goal: string) {
    const stream = await client.agent.stream({ url, goal });

    for await (const event of stream) {
      if (event.type === EventType.PROGRESS) {
        console.log(`Action: ${event.purpose}`);
      } else if (event.type === EventType.COMPLETE) {
        if (event.status === RunStatus.COMPLETED) {
          return event.result;
        }
        throw new Error(event.error?.message || "Automation failed");
      }
    }
  }

  // Example usage
  const products = await runAutomation(
    "https://example.com/products",
    "Extract all product names and prices as JSON"
  );
  ```

  ---

  **TypeScript - Synchronous**

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

  const client = new TinyFish();  // Reads TINYFISH_API_KEY from environment

  async function runAutomation(url: string, goal: string) {
    const run = await client.agent.run({ url, goal });
    if (run.status === RunStatus.COMPLETED) return run.result;
    throw new Error(run.error?.message || "Automation failed");
  }
  ```

  ---

  **Python - Streaming**

  ```python
  from tinyfish import TinyFish, EventType, RunStatus

  client = TinyFish()  # Reads TINYFISH_API_KEY from environment

  def run_automation(url: str, goal: str):
      with client.agent.stream(url=url, goal=goal) as stream:
          for event in stream:
              if event.type == EventType.PROGRESS:
                  print(f"Action: {event.purpose}")
              elif event.type == EventType.COMPLETE:
                  if event.status == RunStatus.COMPLETED:
                      return event.result_json
                  raise Exception(event.error)

  # Example usage
  products = run_automation(
      "https://example.com/products",
      "Extract all product names and prices as JSON"
  )
  ```

  ---

  **Python - Synchronous**

  ```python
  from tinyfish import TinyFish, RunStatus

  client = TinyFish()  # Reads TINYFISH_API_KEY from environment

  def run_automation(url: str, goal: str):
      result = client.agent.run(url=url, goal=goal)
      if result.status == RunStatus.COMPLETED:
          return result.result
      raise Exception(result.error)
  ```

  ---

  **Anti-Detection Mode**

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

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

  const run = await client.agent.run({
    url: "https://protected-site.com",
    goal: "Extract pricing data",
    browser_profile: BrowserProfile.STEALTH,
    proxy_config: {
      enabled: true,
      country_code: ProxyCountryCode.US,  // Or any ISO 3166-1 alpha-2 code, e.g. "IN"
    },
  });
  ```

  ---

  **Writing Good Goals**

  Be specific about what you want:

  ```
  // Good - specific output format
  "Extract product name, price, and availability. Return as JSON array."

  // Good - multi-step with numbered actions
  "1. Click 'Load More' 3 times  2. Extract all product cards  3. Return as JSON"

  // Bad - too vague
  "Get the data"
  ```

  ---

  **Quick Test**

  ```bash
  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 3 product names and prices"
    }'
  ```

  ---

  After asking the questions, generate the appropriate code for my use case. Reference https://docs.tinyfish.ai for additional details.
  ````
</Accordion>

***

## When to Use TinyFish Web Agent

TinyFish Web Agent excels at tasks that require a real browser with full JavaScript execution.

| Use Case | Example |
| - | - |
| **Multi-step workflows** | Login → navigate to dashboard → extract account data |
| **JavaScript-rendered content** | SPAs, infinite scroll, lazy-loaded content |
| **Interactive elements** | Click dropdowns, dismiss modals, paginate results |
| **Authenticated sessions** | Access content behind login walls |
| **Bot-protected sites** | Cloudflare, DataDome protected pages |

***

## Writing Goals for AI Agents

When your AI generates goals for TinyFish Web Agent, follow these patterns for reliable results.

### Specify Output Schema

Pass an `output_schema` field to make TinyFish enforce a supported structured-output schema at the API level. See
[Structured Output](/key-concepts/structured-output).

```
Extract product data and return as JSON matching this structure:
{
  "product_name": "string",
  "price": number or null,
  "in_stock": boolean
}
```

### Include Termination Conditions

```
Stop when ANY of these is true:
- You have extracted 20 items
- No more "Load More" button exists
- You have processed 5 pages
- The page shows a login prompt
```

### Handle Edge Cases

```
If price shows "Contact Us" or "Request Quote":
  Set price to null
  Set price_type to "contact_required"

If a CAPTCHA appears:
  Stop immediately
  Return partial results with an error flag
```

### Request Structured Errors

```
If extraction fails, return:
{
  "success": false,
  "error_type": "timeout" or "blocked" or "not_found",
  "error_message": "Description of what went wrong",
  "partial_results": [any data captured before failure]
}
```

***

## Parsing Results

When your AI receives results from TinyFish Web Agent, handle both success and failure cases.

### Success Response

```json theme={null}
{
  "status": "COMPLETED",
  "result": {
    "products": [
      { "name": "Widget", "price": 29.99, "in_stock": true }
    ]
  }
}
```

### Goal Failure

The browser worked, but the goal wasn't achieved. Try a different approach or inform the user.

```json theme={null}
{
  "status": "COMPLETED",
  "result": {
    "success": false,
    "error_type": "not_found",
    "error_message": "No products found on this page"
  }
}
```

### Infrastructure Failure

The browser itself failed. Retry with stealth mode or a proxy.

```json theme={null}
{
  "status": "FAILED",
  "error": {
    "message": "Navigation timeout"
  }
}
```

***

## Next Steps

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/quick-start">
    Manual step-by-step setup
  </Card>

  <Card title="Prompting Guide" icon="bullseye" href="/prompting-guide">
    Write goals that work on the first try
  </Card>

  <Card title="MCP Integration" icon="robot" href="/mcp-integration">
    Connect with Claude and Cursor
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Full endpoint documentation
  </Card>
</CardGroup>


# Connect Your Vault
Source: https://docs.tinyfish.ai/vault-setup

Connect your password manager so TinyFish can securely log into websites during automations

TinyFish can log into websites on your behalf using credentials from your existing password manager. Connect your vault once, then select which credentials to use for each run.

## How It Works

Connect your password manager account, TinyFish syncs your vault items, and then you select specific credentials for each run. Each run only gets the credentials you explicitly choose, so no run has access to your full vault.

<img alt="Vault settings page with Connect a password manager button" />

## Connect Your Provider

<Note>More providers coming soon.</Note>

<Tabs>
  <Tab title="Dashboard">
    In TinyFish, go to **Settings > Vault** and click **Connect a password manager**.

    <img alt="Provider selection dialog showing 1Password and Bitwarden options" />

    <AccordionGroup>
      <Accordion title="1Password" icon="key">
        Paste your Service Account Token (starts with `ops_`), then click **Connect**.

        <img alt="1Password credentials form with Service Account Token field" />

        Your items sync automatically. Confirm they appear grouped by vault name.

        <img alt="Vault settings with connected 1Password showing credentials grouped by vault" />

        <Tip>
          Need a token? Create a service account with read access to your vault. See the [1Password service account docs](https://developer.1password.com/docs/service-accounts/).
        </Tip>
      </Accordion>

      <Accordion title="Bitwarden" icon="shield-halved">
        Enter your `Client ID`, `Client Secret`, and `Master Password`, then click **Connect**.

        Use the format `user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` for the Client ID.

        <img alt="Bitwarden credentials form with Client ID, Client Secret, and Master Password fields" />

        If you use a self-hosted instance, toggle **Self-hosted server** and enter your server URL.

        <img alt="Vault settings with connected Bitwarden showing synced credentials" />

        <Tip>
          Find your API key in Bitwarden under `Settings` > `Security` > `Keys` > `View API Key`. See the [Bitwarden personal API key guide](https://bitwarden.com/help/personal-api-key/).
        </Tip>

        <Note>
          The first sync may take up to 15 seconds. Subsequent syncs are faster.
        </Note>
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="API">
    Connect a provider programmatically with `POST /v1/vault/connections`. Credentials are validated immediately — if they're invalid, the request fails with a `400`.

    <CodeGroup>
      ```bash 1Password theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "1password",
          "token": "ops_your_service_account_token"
        }'
      ```

      ```bash Bitwarden theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "bitwarden",
          "clientId": "user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "clientSecret": "your_client_secret",
          "masterPassword": "your_master_password"
        }'
      ```

      ```bash Bitwarden (self-hosted) theme={null}
      curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
        -H "X-API-Key: $TINYFISH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "provider": "bitwarden",
          "clientId": "user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "clientSecret": "your_client_secret",
          "masterPassword": "your_master_password",
          "serverUrl": "https://bitwarden.example.com"
        }'
      ```
    </CodeGroup>

    A successful response includes the `connectionId` and the initial list of synced items:

    ```json theme={null}
    {
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
      "connected": true,
      "provider": "1password",
      "items": [
        {
          "item_id": "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Personal:item-xyz",
          "label": "Amazon Login",
          "vault_name": "Personal",
          "websites": ["https://amazon.com"],
          "has_totp": false,
          "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
        }
      ]
    }
    ```

    If the connection already exists for the same provider, it is replaced — not duplicated.
  </Tab>

  <Tab title="CLI">
    Connect a provider with `tinyfish vault connection add`. Provider secrets are read from environment variables — never passed as flags — so they stay out of shell history.

    <CodeGroup>
      ```bash 1Password theme={null}
      TINYFISH_VAULT_TOKEN=ops_your_service_account_token \
        tinyfish vault connection add --provider 1password
      ```

      ```bash Bitwarden theme={null}
      TINYFISH_VAULT_CLIENT_SECRET=your_client_secret \
      TINYFISH_VAULT_MASTER_PASSWORD=your_master_password \
        tinyfish vault connection add \
          --provider bitwarden \
          --client-id user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
      ```

      ```bash Bitwarden (self-hosted) theme={null}
      TINYFISH_VAULT_CLIENT_SECRET=your_client_secret \
      TINYFISH_VAULT_MASTER_PASSWORD=your_master_password \
        tinyfish vault connection add \
          --provider bitwarden \
          --client-id user.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
          --server-url https://bitwarden.example.com
      ```
    </CodeGroup>

    If the connection already exists for the same provider, it is replaced — not duplicated.

    <Tip>
      Need a 1Password token? Create a service account with read access to your vault. See the [1Password service account docs](https://developer.1password.com/docs/service-accounts/).
    </Tip>
  </Tab>
</Tabs>

## Managing Your Vault

<Tabs>
  <Tab title="Dashboard">
    ### Sync

    Click `Sync` to fetch the latest items from your connected provider.

    ### Disconnect

    Click `Disconnect` and confirm to remove the provider. All cached credentials are removed immediately, but runs already in progress are not affected. You can reconnect at any time.
  </Tab>

  <Tab title="API">
    ### List connections

    ```bash theme={null}
    curl https://agent.tinyfish.ai/v1/vault/connections \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "connections": [
        {
          "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "provider": "1password",
          "connectionStatus": "active",
          "lastValidatedAt": "2026-04-10 12:00:00"
        }
      ]
    }
    ```

    ### List vault items

    Retrieve the credential items available for runs. These are read from the local cache, so the response is fast.

    ```bash theme={null}
    curl https://agent.tinyfish.ai/v1/vault/items \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "items": [
        {
          "itemId": "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Personal:item-xyz",
          "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
          "label": "Amazon Login",
          "vaultName": "Personal",
          "domains": ["amazon.com"],
          "fieldMetadata": [
            { "fieldId": "username", "label": "username", "type": "STRING" },
            { "fieldId": "password", "label": "password", "type": "STRING" }
          ],
          "hasTotp": false
        }
      ]
    }
    ```

    The `itemId` is the value you pass as `credential_item_ids` when [starting a run](/key-concepts/credentials#using-the-api).

    <Note>
      Items without website URLs in your password manager will still sync, but they won't have any `domains` and can't be matched to a site during a run.
    </Note>

    ### Sync items

    Pull the latest state from your connected providers. Use this before starting a run if you've recently changed passwords.

    ```bash theme={null}
    curl -X POST https://agent.tinyfish.ai/v1/vault/items/sync \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "items": [ ... ],
      "sync_summary": {
        "added": 3,
        "updated": 1,
        "removed": 0
      }
    }
    ```

    ### Disconnect a provider

    Removes the connection and all cached credentials. Runs already in progress are not affected.

    ```bash theme={null}
    curl -X DELETE https://agent.tinyfish.ai/v1/vault/connections/a1b2c3d4-5678-90ab-cdef-1234567890ab \
      -H "X-API-Key: $TINYFISH_API_KEY"
    ```

    ```json theme={null}
    {
      "disconnected": true,
      "connectionId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="CLI">
    ### List connections

    ```bash theme={null}
    tinyfish vault connection list
    ```

    ### Sync items

    Pull the latest credentials from your connected providers. Run this after adding new credentials or changing passwords.

    ```bash theme={null}
    tinyfish vault item sync
    ```

    ### List items

    List all synced credential items. The `itemId` is what you pass to `--credential-item-id` when running an automation.

    ```bash theme={null}
    tinyfish vault item list
    ```

    ### Disconnect a provider

    Removes the connection and all cached credentials. Runs already in progress are not affected.

    ```bash theme={null}
    tinyfish vault connection remove a1b2c3d4-5678-90ab-cdef-1234567890ab
    ```
  </Tab>
</Tabs>

## Using the Vault API

### Quick start

Connect a provider, retrieve item IDs, and start a run with specific credentials:

```bash theme={null}
# 1. Connect your vault (one-time setup)
curl -X POST https://agent.tinyfish.ai/v1/vault/connections \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "1password", "token": "ops_your_token" }'
# → returns connectionId and initial items

# 2. List available credentials (reads from cache — fast)
curl -s https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY"
# → grab the itemId for the credential you need

# 3. Start a run with that credential
curl -X POST https://agent.tinyfish.ai/v1/automation/run \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.linkedin.com",
    "goal": "Log in and capture the latest 3 posts from the feed",
    "use_vault": true,
    "credential_item_ids": [
      "cred:a1b2c3d4-5678-90ab-cdef-1234567890ab:Work:item-linkedin"
    ]
  }'
```

### Matching credentials to URLs

Filter items by the `domains` field to find the right credential for your target site:

```bash theme={null}
curl -s https://agent.tinyfish.ai/v1/vault/items \
  -H "X-API-Key: $TINYFISH_API_KEY" \
  | jq '.items[] | select(.domains[] | contains("linkedin.com")) | .itemId'
```

Scoping to specific `credential_item_ids` is more reliable than `use_vault: true` alone — it prevents the agent from picking the wrong login when you have multiple accounts on the same domain.

### When to sync

`GET /v1/vault/items` reads from a local cache and is fast. You don't need to sync before every run.

Call `POST /v1/vault/items/sync` when:

* You've recently changed a password in your vault
* You've added new credentials you want to use
* A run failed to log in and you suspect stale credentials

For most pipelines, syncing once at startup or on a daily schedule is sufficient.

### Handling expired connections

Provider tokens can expire. When they do, `POST /v1/vault/items/sync` returns a `401`. Your pipeline should:

1. Catch the `401` from sync
2. Re-connect with `POST /v1/vault/connections` using a fresh token
3. Retry the sync

1Password service account tokens don't expire unless revoked. Bitwarden tokens may expire based on your server configuration.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection failed — invalid credentials" icon="xmark">
    For 1Password, verify the token starts with `ops_` and has read access to the vault you want to sync.

    For Bitwarden, verify that the `Client ID` and `Client Secret` match the same API key.

    The API returns a `400` with `"Invalid vault token"` when credentials fail validation.
  </Accordion>

  <Accordion title="Vault items not appearing after sync" icon="circle-question">
    Vault items must have website URLs in your password manager to sync into TinyFish.

    Credentials without URLs are not synced.
  </Accordion>

  <Accordion title="Self-hosted Bitwarden not connecting" icon="server">
    Ensure the server URL includes `https://` and that the server is accessible from TinyFish.
  </Accordion>

  <Accordion title="Token expired or reconnect required" icon="rotate">
    Provider tokens can expire. Disconnect the provider, then reconnect using a fresh token or updated credentials.

    `POST /v1/vault/items/sync` returns a `401` when all connections require reconnect and no items can be returned.
  </Accordion>

  <Accordion title="First sync is slow" icon="clock">
    The first Bitwarden sync can take up to 15 seconds while the connection initializes. Subsequent syncs are faster.
  </Accordion>

  <Accordion title="All providers already connected" icon="link">
    You can connect a maximum of 2 providers at the same time.
  </Accordion>

  <Accordion title="API returns 404 on vault items" icon="circle-exclamation">
    No vault connections exist yet. Connect a provider first with `POST /v1/vault/connections`.
  </Accordion>

  <Accordion title="API returns 503" icon="server">
    The vault integration is unavailable or the backing vault service returned an error.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup>
  <Card title="Vault Credentials" icon="key" href="/key-concepts/credentials">
    Learn how credentials are selected and used in runs
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    Understand TinyFish authentication methods
  </Card>
</CardGroup>


# Webhooks
Source: https://docs.tinyfish.ai/webhooks

Get notified when runs complete, fail, or are cancelled

Webhooks let you receive an HTTP callback when a run reaches a terminal state, so you don't need to poll for results.

## How It Works

1. Pass a `webhook_url` when you create a run
2. When the run finishes (`COMPLETED`, `FAILED`, or `CANCELLED`), TinyFish sends a `POST` request to your URL
3. The payload contains the full run data — the same shape as `GET /v1/runs/{id}`

<Info>
  Webhook delivery is non-blocking. If your endpoint is down, the run still succeeds — you can always fetch the result via the API.
</Info>

***

## Configuration

Add `webhook_url` to any run creation endpoint. The URL must use HTTPS.

```bash theme={null}
curl -X POST "https://agent.tinyfish.ai/v1/automation/run-async" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "goal": "Extract the page title",
    "webhook_url": "https://your-server.com/webhooks/tinyfish"
  }'
```

Webhooks are supported on all run endpoints: `/run`, `/run-async`, `/run-sse`, and `/run-batch`.

***

## Payload

Your endpoint receives a `POST` request with `Content-Type: application/json`:

```json theme={null}
{
  "event": "run.completed",
  "run_id": "4562765d-156e-4c47-b217-55b3ec4a9720",
  "status": "COMPLETED",
  "data": {
    "run_id": "4562765d-156e-4c47-b217-55b3ec4a9720",
    "status": "COMPLETED",
    "goal": "Extract the page title",
    "created_at": "2026-03-25T10:30:00Z",
    "started_at": "2026-03-25T10:30:05Z",
    "finished_at": "2026-03-25T10:30:45Z",
    "num_of_steps": 3,
    "result": { "title": "Example Domain" },
    "error": null,
    "streaming_url": "https://tf-abc123.fra0-tinyfish.unikraft.app/stream/0",
    "browser_config": {
      "proxy_enabled": false,
      "proxy_country_code": null
    },
    "steps": [
      {
        "id": "09de224d-fb2b-45b7-b067-585726194a2e",
        "timestamp": "2026-03-25T10:30:05Z",
        "status": "COMPLETED",
        "action": "Navigate to https://example.com",
        "screenshot": null,
        "duration": "1.2s"
      }
    ]
  }
}
```

### Minimal Example

A simplified view of the webhook payload with just the key fields:

```json theme={null}
{
  "event": "run.completed",
  "run_id": "run_abc123",
  "status": "COMPLETED",
  "data": {
    "started_at": "2026-01-15T10:30:00Z",
    "finished_at": "2026-01-15T10:30:45Z",
    "result": {
      "product_name": "Example Product",
      "price": 29.99
    },
    "error": null
  }
}
```

### Event Types

| Event | When |
| - | - |
| `run.completed` | Run finished (check `result` for data) |
| `run.failed` | Infrastructure error occurred |
| `run.cancelled` | Run was manually cancelled |

### Payload Fields

| Field | Type | Description |
| - | - | - |
| `event` | string | Event type (e.g. `run.completed`) |
| `run_id` | string | Unique run identifier |
| `status` | string | `COMPLETED`, `FAILED`, or `CANCELLED` |
| `data` | object | Full run data — same shape as `GET /v1/runs/{id}` |
| `data.result` | object \| null | Extracted data (when completed) |
| `data.error` | object \| null | Error details (when failed) |
| `data.steps` | array | List of actions the agent took |

<Note>
  Screenshots are not included in webhook payloads to keep the payload size small. To get screenshots, call `GET /v1/runs/{id}?screenshots=base64` after receiving the webhook.
</Note>

***

## Error Payload

When a run fails, `data.error` contains details about what went wrong:

```json theme={null}
{
  "event": "run.failed",
  "run_id": "run-2",
  "status": "FAILED",
  "data": {
    "error": {
      "message": "Site blocked access",
      "category": "AGENT_FAILURE"
    },
    "result": null
  }
}
```

***

## Retry Behavior

TinyFish retries failed webhook deliveries automatically:

| Behavior | Detail |
| - | - |
| Total attempts | 4 (1 initial + 3 retries) |
| Backoff | Exponential: 1s, 2s, 4s |
| Timeout | 10 seconds per attempt |
| 4xx responses | No retry (fails immediately) |
| 5xx responses | Retried with backoff |
| Network errors | Retried with backoff |

***

## Receiving Webhooks

Here's how to handle webhook events on your server:

<CodeGroup>
  ```typescript Express theme={null}
  import express from "express";

  const app = express();
  app.use(express.json());

  app.post("/webhooks/tinyfish", (req, res) => {
    const { event, run_id, data } = req.body;

    switch (event) {
      case "run.completed":
        console.log(`Run ${run_id} completed:`, data.result);
        // Process the result
        break;
      case "run.failed":
        console.error(`Run ${run_id} failed:`, data.error?.message);
        // Handle the error
        break;
      case "run.cancelled":
        console.log(`Run ${run_id} was cancelled`);
        break;
    }

    // Respond quickly — TinyFish has a 10s timeout
    res.status(200).send("OK");
  });
  ```

  ```python Flask theme={null}
  from flask import Flask, request

  app = Flask(__name__)

  @app.route("/webhooks/tinyfish", methods=["POST"])
  def handle_webhook():
      payload = request.json
      event = payload["event"]
      run_id = payload["run_id"]
      data = payload["data"]

      if event == "run.completed":
          print(f"Run {run_id} completed:", data["result"])
          # Process the result
      elif event == "run.failed":
          print(f"Run {run_id} failed:", data.get("error", {}).get("message"))
          # Handle the error
      elif event == "run.cancelled":
          print(f"Run {run_id} was cancelled")

      # Respond quickly — TinyFish has a 10s timeout
      return "OK", 200
  ```
</CodeGroup>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Respond within 10 seconds">
    TinyFish waits up to 10 seconds for your response. Do heavy processing asynchronously — acknowledge the webhook immediately and handle the data in the background.
  </Accordion>

  <Accordion title="Handle duplicates idempotently">
    In rare cases (network retries, server restarts), you may receive the same webhook more than once. Use `run_id` to deduplicate.
  </Accordion>

  <Accordion title="Verify by fetching the run">
    For sensitive workflows, confirm the webhook data by calling `GET /v1/runs/{run_id}` before acting on the payload.
  </Accordion>

  <Accordion title="Return 2xx to acknowledge">
    Any 2xx response acknowledges the webhook. Non-2xx responses trigger retries (except 4xx, which fail immediately).
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup>
  <Card title="Runs" icon="play" href="/key-concepts/runs">
    Understand run lifecycle and statuses
  </Card>

  <Card title="Endpoints" icon="plug" href="/key-concepts/endpoints">
    Choose sync, async, or streaming
  </Card>
</CardGroup>