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
Browser Context Profile, 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.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 Browser Context Profile for this run.
string
Select a specific Browser Context Profile. 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 Browser Context Profile. Add profile_id when the run must use a
specific saved profile. Create and set up profiles from the dashboard or the
Browser Context Profiles API.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:
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).