Skip to content

Start a run

Queues a run on one of the workspace’s sites. The site must already be in the workspace.

POST/v1/runs

Needs the runs:write scope.

Body

sitestringRequired
The site’s id, from List sites (for example kilnandcove).
goalstringRequired
One task, written the way a visitor would put it. Up to 200 characters.
personaslist of strings
The personas to send: general, hurry, reader, language, explorer, first, vision, or custom:<id> for one of your own. Leave it out to use the workspace’s defaults: General alone, unless the workspace has chosen others.
testAccountstring
The id of one of the site’s test accounts, from List sites, for pages behind a sign-in.

Credits and time

The run is queued straight away, holding its credits: 1 for each persona. cost is what it holds. A cancelled run gives them all back; a persona that fails on our side gives back its own.

Every persona gets 10 minutes, so there is no time limit to send. minutesPerPersona in the answer is always 10.

Safe retries

Send an Idempotency-Key header (up to 255 visible characters, such as a UUID) to make a retry safe. The same key with the same body within 24 hours returns the first response, marked Idempotent-Replayed: true, instead of starting a second run.

While the first request is still being handled, a second one fails with conflict.