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, orcustom:<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.