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.

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",
  "browser_profile": "lite",
  "proxy_config": {
    "enabled": true,
    "type": "tetra",
    "country_code": "US"
  }
}

Field	Type	Required	Notes
url	string	Yes	Target website URL to automate
goal	string	Yes	Natural-language instruction for the automation
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

See Browser Profiles and Proxies 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
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	Meaning
400	Invalid request body or missing required fields
401	Missing or invalid API key
429	Rate limit exceeded
500	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.

Related

Agent overview

First request, endpoint selection, and goal-writing basics

Runs

Statuses, polling, and lifecycle behavior

Goal prompting guide

Improve automation reliability

Authentication

API key setup and troubleshooting