> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TinyAgent Reference

> Create agent runs synchronously, asynchronously, in a batch, or via SSE

Create and manage TinyAgent runs. All requests require the `X-API-Key` header unless noted
otherwise. See [Authentication](https://docs.tinyfish.ai/authentication.md).

## 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 |
| `https://agent.tinyfish.ai/v1/automation/run-batch` | `POST` | `run_ids` immediately | Yes (per run) |

## Common Request Body

The three single-run endpoints — `run`, `run-async`, and `run-sse` — accept this JSON body directly. `run-batch` wraps an array of these bodies under `runs`, except `profile_id` and `output_schema`, which are top-level only on the batch request; see [Create a Batch of Agent Runs](#create-a-batch-of-agent-runs).

```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"]
}
```

**url** `string` *required*

Target website URL to automate.

**goal** `string` *required*

Natural-language instruction for the automation.

**output\_schema** `object`

Structured-output schema subset for the run result. Unsupported fields are rejected before execution. See [Structured Output](https://docs.tinyfish.ai/tinyagent/api/agent/structured-output.md).

**browser\_profile** `string` (default: lite)

`lite` or `stealth` — the browser *runtime* (standard vs. anti-detection). This is unrelated to a
**TinyProfile**, which is saved login state reused across runs; see [Browser
Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md) vs. [Browser Context
Profiles](https://docs.tinyfish.ai/key-concepts/tinyprofile.md) for the distinction.

**proxy\_config** `object`

How the run connects to the internet.

| Field | Type | Default | Description |
| - | - | - | - |
| `enabled` | `boolean` | `true` | Enables proxying for the run |
| `type` | `"tinyfish"` \| `"custom"` | `"tinyfish"` | `tinyfish` uses the built-in TinyFish proxy; `custom` requires your own proxy URL and is **custom/enterprise plans only** |
| `country_code` | `string` | `"US"` | Any ISO 3166-1 alpha-2 code (e.g. `US`, `IN`). Used with `type: "tinyfish"` |
| `url` | `string` | — | Required when `type: "custom"` |
| `username` | `string` | — | Custom proxy username |
| `password` | `string` | — | Custom proxy password |

**agent\_config** `object`

Run-level behavior controls. Not entirely beta — only `mode` and `max_steps` require the beta
program; `max_duration_seconds` is generally available.

| Field | Type | Default | Description |
| - | - | - | - |
| `mode` | `"default"` \| `"strict"` | `"default"` | **Beta** — enroll at [agent.tinyfish.ai/beta](https://agent.tinyfish.ai/beta) to use it. Use `strict` for fail-fast automation where the agent should stop instead of exploring workarounds. |
| `max_steps` | `integer` | `150` | **Beta** — enroll at [agent.tinyfish.ai/beta](https://agent.tinyfish.ai/beta) to use it. Step limit from 1 to 500. Non-beta requests that include it return `403 FORBIDDEN`; requests without it are unaffected. |
| `max_duration_seconds` | `integer` | — | Generally available. Maximum wall-clock seconds before the agent stops. No limit by default |

**webhook\_url** `string`

HTTPS URL to receive run lifecycle notifications. Must use `https://`. See [Webhooks](https://docs.tinyfish.ai/webhooks.md).

**capture\_config** `object`

Opt into extra run artifacts (`screenshots`, `recording`, `html`, `snapshots`, `elements`). Only `recording` and `elements` are gated — **custom/enterprise plans only**, returns `403` if your account isn't enabled. `html` is open to everyone. `snapshots` and `screenshots` haven't shipped yet.

**use\_profile** `boolean`

Use the default saved [TinyProfile](https://docs.tinyfish.ai/key-concepts/tinyprofile.md) for this run.

**profile\_id** `string`

Select a specific TinyProfile. Requires `use_profile: true`.

**use\_vault** `boolean`

Enable [vault credentials](https://docs.tinyfish.ai/key-concepts/credentials.md) for this run. When `true`, TinyFish can log into sites using your connected password manager.

**credential\_item\_ids** `string[]`

Scope the run to specific credential URIs from `GET /v1/vault/items`. Requires `use_vault: true`. If omitted, all synced items are available.

> [!NOTE]
>
> Use `use_profile: true` for your default TinyProfile. Add `profile_id` when the run must use a
> specific saved profile. Create and set up profiles from the dashboard or the
> [TinyProfiles API](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md).

See [Structured Output](https://docs.tinyfish.ai/tinyagent/api/agent/structured-output.md) for the supported keyword allowlist, size and depth limits, and common rewrites for invalid schemas.

See [TinyProfiles](https://docs.tinyfish.ai/key-concepts/tinyprofile.md), [TinyProfiles API](https://docs.tinyfish.ai/tinyagent/api/profiles/tinyprofile.md), [Browser Profiles](https://docs.tinyfish.ai/key-concepts/browser-profiles.md), [Proxies](https://docs.tinyfish.ai/key-concepts/proxies.md), and [Vault Credentials](https://docs.tinyfish.ai/key-concepts/credentials.md) for operational guidance.

## Create a Synchronous Agent Run

`POST /v1/automation/run`

Blocking request, returns the final result in one response. Cannot be cancelled. Request body:
see [Common Request Body](#common-request-body) above.

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

This is the same run object returned by `GET /v1/runs/{id}` — see [Runs
Reference](https://docs.tinyfish.ai/tinyagent/api/runs.md#get-a-run-by-id) for the full field-by-field schema, including the
`error` object shape.

## Create an Asynchronous Agent Run

`POST /v1/automation/run-async`

Returns a `run_id` immediately; fetch the full run later with `GET /v1/runs/{id}`.

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

## Create a Batch of Agent Runs

`POST /v1/automation/run-batch`

Starts multiple automations asynchronously in one call.

**runs** `array` *required*

1-100 items. Each item takes the same fields as a single automation request, except
`profile_id` and `output_schema` — set those once at the top level instead; they're rejected
inside individual run items.

**profile\_id** `string`

Default profile applied to every run in the batch.

**output\_schema** `object`

Default schema applied to every run in the batch.

```json theme={null}
{ "run_ids": ["run_1", "run_2"], "error": null }
```

## Stream an Agent Run via SSE

`POST /v1/automation/run-sse`

Streams a live event feed while the automation runs. The protocol itself is documented here since
it isn't captured by a request/response schema.

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

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

> [!NOTE]
>
> **Heartbeats:** `HEARTBEAT` events carry no `run_id` and arrive periodically to keep the connection alive during longer gaps between `PROGRESS` events. Ignore any event `type` your client doesn't explicitly handle.

> [!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`).

### 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', {})}")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.