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.
- When to use
- When to avoid
- 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
Learn more about run statuses and lifecycle in Runs.
- When to use
- When to avoid
- 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.
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.
- When to use
- When to avoid
- 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 therun_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.- When to use
- When to avoid
- 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:
Quick Decision Guide
1
Need real-time progress updates?
Yes → Use
/run-sse2
Submitting multiple URLs or goals at once?
Yes → Use
/run-batch3
Task takes longer than 30 seconds?
Yes → Use
/run-async + polling4
Simple, quick, single task?
Use
/run (synchronous)Comparison Table
Related
Agent Reference
Exact request and response schema for every Agent endpoint
Runs
Understand the automation lifecycle