Agent API Reference

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

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

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

Start Here

APIs

Guides

Examples

Reference

Endpoints

Common Request Body

`POST /v1/automation/run`

`POST /v1/automation/run-async`

`POST /v1/automation/run-sse`

`GET /v1/runs/{id}`

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

Error Codes

Agent overview

Runs

Goal prompting guide

Authentication

Start Here

APIs

Guides

Examples

Reference

​Endpoints

​Common Request Body

​POST /v1/automation/run

​POST /v1/automation/run-async

​POST /v1/automation/run-sse

​GET /v1/runs/{id}

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

​Error Codes

​Related

Agent overview

Runs

Goal prompting guide

Authentication

Endpoints

Common Request Body

`POST /v1/automation/run`

`POST /v1/automation/run-async`

`POST /v1/automation/run-sse`

`GET /v1/runs/{id}`

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

Error Codes

Related