X-API-Key header unless noted
otherwise. See Authentication.
Endpoints
List and Search Runs
GET /v1/runs
string
Filter by run status.
string
Text search over the goal field.
string
ISO 8601 timestamp lower bound.
string
ISO 8601 timestamp upper bound.
string
default:"desc"
asc or desc.string
Pagination cursor from a previous response.
integer
default:"20"
Results per page, 1–100.
Get a Run by ID
GET /v1/runs/{id}
Use this endpoint to retrieve the current or final state of an async or streaming run.
In an organization, a workflow key reads only runs started by its team’s workflow keys, never its creator’s own; see Who sees what.
string
required
The run’s
run_id.string
default:"url"
url, base64, or none — controls how each step’s screenshot field is delivered.string
default:"url"
url or none — controls how each step’s html field is delivered.string
Unique run identifier.
string
PENDING, RUNNING, COMPLETED, FAILED, or CANCELLED.string
Original goal text.
string | null
ISO 8601 timestamp.
string | null
ISO 8601 timestamp.
string | null
ISO 8601 timestamp.
integer | null
Number of steps taken.
object | null
Extracted JSON result.
object | null
Schema originally requested, if any.
boolean
Whether a Browser Context Profile was attached to the run.
string | null
ID of the attached Browser Context Profile, if any. Both profile fields are omitted when an
organization workflow key reads a run that used a profile.
object | null
string | null
Live browser stream URL while running.
object | null
Proxy settings used for the run.
string | null
Presigned run recording URL, if available.
array
Recorded step events for the run.
Cancel a Run by ID
POST /v1/runs/{id}/cancel
Runs created via /run-async, /run-sse, or /run-batch can be cancelled — this route resolves
the batch ID for you, so cancelling a batch run works the same way. Only synchronous /run
requests can’t be cancelled, since they block until the run finishes. Idempotent — calling it on
an already-cancelled or completed run returns the current state without error.
A run your key can read but not cancel returns 403 FORBIDDEN with the message You can view this run but not cancel it.
string
required
The run’s
run_id.string
string
CANCELLED, COMPLETED, or FAILED — actual status after the cancel attempt.string | null
string | null
Idempotency or terminal-state message, e.g.
"Run already cancelled".Get Multiple Runs by ID
POST /v1/runs/batch
Get multiple runs by ID in one call.
string[]
required
array
The found run objects.
string[]
Any IDs that didn’t match a run.
Cancel Multiple Runs by ID
POST /v1/runs/batch/cancel
Cancel multiple runs by ID in one call.
string[]
required
array
A cancel outcome per run, same shape as the single-cancel response.
string[]
Any IDs that didn’t match a run.
Get a Step’s Screenshot
GET /v1/runs/{id}/steps/{stepId}/screenshot
Returns the raw screenshot image for one recorded step. Only populated when the run was created
with capture_config.screenshots enabled.
string
required
The run’s
run_id.string
required
The step’s
id, from the run’s steps array.Get a Step’s HTML Snapshot
GET /v1/runs/{id}/steps/{stepId}/html
Returns the raw HTML snapshot for one recorded step. Only populated when the run was created with
capture_config.html enabled.
string
required
The run’s
run_id.string
required
The step’s
id, from the run’s steps array.