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.
Structured-output schema subset for the run result. Unsupported fields are rejected before execution. See Structured Output.
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.Run-level behavior controls. Not entirely beta — only
mode and max_steps require the beta
program; max_duration_seconds is generally available.HTTPS URL to receive run lifecycle notifications. Must use
https://. See Webhooks.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 the default saved TinyProfile for this run.
Enable vault credentials for this run. When
true, TinyFish can log into sites using your connected password manager.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.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.
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.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).