Agent API Reference - TinyFish Web Agent

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.

Common Request Body

All three automation endpoints accept the same JSON body.

{
  "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": "tetra",
    "country_code": "US"
  },
  "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	Beta structured-output schema subset for the run result. Unsupported fields are rejected before execution. See Structured Output
`browser_profile`	`lite \| stealth`	No	Defaults to `lite`
`proxy_config.enabled`	`boolean`	No	Enables proxying for the run
`proxy_config.type`	`tetra \| custom`	No	`tetra` uses TinyFish proxy infrastructure; `custom` requires your own proxy URL
`proxy_config.country_code`	`US \| GB \| CA \| DE \| FR \| JP \| AU`	No	Used with `type: "tetra"`
`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
`use_profile`	`boolean`	No	Beta. Use the default saved BBU Profile for this run. Requires BBU Profiles beta access
`profile_id`	`string`	No	Beta. Select a specific profile. Requires `use_profile: true` and BBU Profiles beta access
`use_vault`	`boolean`	No	Enable vault 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

output_schema, use_profile, and profile_id are beta features. BBU Profiles only take effect for accounts with beta access; profile_id requires beta access and use_profile: true. Join the beta program at agent.tinyfish.ai/beta.

See Structured Output for the supported keyword allowlist, size and depth limits, and common rewrites for invalid schemas. See BBU Profiles, BBU Profiles API, Browser Profiles, Proxies, and Vault Credentials for operational guidance.

`POST /v1/automation/run`

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

{
  "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.

{
  "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?`, `help_url?`, `help_message?`, `timestamp`

Example stream:

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":"..."}

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

Raw HTTP (no SDK)

Parse SSE events directly without the TinyFish SDK:

import httpx
import json

url = "https://agent.tinyfish.ai/v1/automation/run-sse"
headers = {"x-api-key": "sk-tinyfish-..."}
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
`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`	Beta 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.

{
  "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
`403`	`FORBIDDEN`	Access denied, including when an account without beta access includes `output_schema`
`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 INSUFFICIENT_CREDITS.

Agent overview

First request, endpoint selection, and goal-writing basics

Structured Output

Beta schema support, limits, and common rewrites

Runs

Statuses, polling, and lifecycle behavior

Goal prompting guide

Improve automation reliability

Authentication

API key setup and troubleshooting

Vault Credentials

Use password manager credentials in runs

BBU Profiles

Reuse saved logged-in browser state

​Endpoints

​Common Request Body

​POST /v1/automation/run

​POST /v1/automation/run-async

​POST /v1/automation/run-sse

​Raw HTTP (no SDK)

​GET /v1/runs/{id}

​POST /v1/runs/{id}/cancel

​Error Codes

​Related

Agent overview

Structured Output

Runs

Goal prompting guide

Authentication

Vault Credentials

BBU Profiles

Endpoints

Common Request Body

`POST /v1/automation/run`

`POST /v1/automation/run-async`

`POST /v1/automation/run-sse`

Raw HTTP (no SDK)

`GET /v1/runs/{id}`

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

Error Codes

Related