Skip to main content
Create and manage TinyAgent runs. All requests require the X-API-Key header unless noted otherwise. See Authentication.

Endpoints

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.
string
required
Target website URL to automate.
string
required
Natural-language instruction for the automation.
object
Structured-output schema subset for the run result. Unsupported fields are rejected before execution. See Structured Output.
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 vs. Browser Context Profiles for the distinction.
object
How the run connects to the internet.
object
Run-level behavior controls. Not entirely beta — only mode and max_steps require the beta program; max_duration_seconds is generally available.
string
HTTPS URL to receive run lifecycle notifications. Must use https://. See Webhooks.
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.
boolean
Use the default saved TinyProfile for this run.
string
Select a specific TinyProfile. Requires use_profile: true.
boolean
Enable vault credentials for this run. When true, TinyFish can log into sites using your connected password manager.
string[]
Scope the run to specific credential URIs from GET /v1/vault/items. Requires use_vault: true. If omitted, all synced items are available.
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.
See Structured Output for the supported keyword allowlist, size and depth limits, and common rewrites for invalid schemas. See TinyProfiles, TinyProfiles API, Browser Profiles, Proxies, and Vault Credentials 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 above. Response:
This is the same run object returned by GET /v1/runs/{id} — see Runs Reference 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}.

Create a Batch of Agent Runs

POST /v1/automation/run-batch Starts multiple automations asynchronously in one call.
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.
string
Default profile applied to every run in the batch.
object
Default schema applied to every run in the batch.

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. Example stream:
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.
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: