X-API-Key header unless noted
otherwise. See Authentication.
Endpoints
List and Search Runs
GET /v1/runs
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.
ID of the attached TinyProfile, if any. Both profile fields are omitted when an
organization workflow key reads a run that used a profile.
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.
Get Multiple Runs by ID
POST /v1/runs/batch
Get multiple runs by ID in one call.
Cancel Multiple Runs by ID
POST /v1/runs/batch/cancel
Cancel multiple runs by ID in one call.
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.
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.