Skip to main content
TinyFish Web Agent offers four ways to run automations. Each endpoint serves a different need. Pick the one that matches how you want to handle the request and response. Exact request/response schemas: Agent Reference.

The Four Endpoints


Synchronous: /run

Pattern: Send request → Wait → Get result The simplest approach. You call the API, it blocks until the automation completes, then returns the result.
Runs created via /run cannot be cancelled. The request blocks until the automation completes, so there is no window to issue a cancellation. If you need the ability to cancel runs, use /run-async, /run-batch, or /run-sse instead.
  • Tasks that complete in under 30 seconds
  • Simple scripts and one-off automations
  • When you don’t need progress updates

Asynchronous: /run-async

Pattern: Send request → Get run ID → Poll for result The request returns immediately with a run_id. You then poll a separate endpoint to check status and get the result when ready. 1. Start the automation
2. Poll for the result
3. Cancel a run (optional) If you need to stop a run before it completes, send a POST to the cancel endpoint:
Learn more about run statuses and lifecycle in Runs.
  • Long-running automations (30+ seconds)
  • One task at a time, fire-and-forget
  • When you need to track a run separately

Batch: /run-batch

Pattern: Send many requests in one call → Get run IDs → Poll each result Starts multiple automations (1–100 runs) asynchronously in a single call instead of issuing one request per URL or goal. There’s no dedicated SDK batch method yet — call the REST endpoint directly, or use the CLI.
Poll each run_id individually with GET /v1/runs/{id}, the same way you would for /run-async. For a handful of runs you want started right away without the batch envelope, concurrent client.agent.queue() calls (Promise.all() / asyncio.gather()) work just as well — see Concurrent Requests and Async Bulk Requests.
  • Many URLs or goals submitted together
  • You want one request/response pair instead of N
  • Batch processing pipelines

Streaming: /run-sse

Pattern: Send request → Receive event stream → Process events as they arrive Uses Server-Sent Events (SSE) to push updates to you in real-time. You’ll receive events for each action the browser takes, plus a streaming URL you can embed in an iframe to watch the automation live. 1. Start the automation and read events

Event Types

Cancelling an SSE Run

You can cancel a streaming run using the run_id from the STARTED event. The onStarted callback fires while you consume the stream, so capture run_id there and trigger the cancel from a separate context (here, a deadline timer):

Handling Events

Use this pattern to process each event type as the automation progresses.
  • User-facing apps (show progress)
  • When you want to watch the browser live
  • Debugging and development
  • Long tasks where you want visibility

Common Request Options

/run, /run-async, and /run-sse accept this request body directly; /run-batch wraps an array of these same bodies under runs (see Batch: /run-batch). Beyond the required url and goal, these optional fields apply to every run, whether sent directly or inside a batch:
For the complete field list with types and defaults, see Common Request Body in the Agent Reference. For authenticated runs and runtime browser modes, see Browser Profiles and the TinyProfiles API.

Quick Decision Guide

1

Need real-time progress updates?

Yes → Use /run-sse
2

Submitting multiple URLs or goals at once?

Yes → Use /run-batch
3

Task takes longer than 30 seconds?

Yes → Use /run-async + polling
4

Simple, quick, single task?

Use /run (synchronous)

Comparison Table


Agent Reference

Exact request and response schema for every Agent endpoint

Runs

Understand the automation lifecycle