distilled

DocsAPI

.md

Runs

All pages

A run carries out one skill on up to 50 phones. Leave phones out to use the running phones no other run has. Each phone is worked on its own, and the run records every action with a screenshot.

Starting a run

terminal
curl https://api.distilled.cx/v1/runs \
  -H "Authorization: Bearer $DISTILLED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: save-playlist-0001" \
  -d '{ "skill": "sk_2hq8", "phones": ["phone-1"] }'
skillstring | SkillDefinitionrequired
A saved skill's id, or a full definition for a one-off run.
phonesstring[]
1 to 50 phone ids.

Send an Idempotency-Key header, and repeating the request returns the run it first made rather than starting another. A run moves from queued to running and ends as done, failed or stopped. A phone the run cannot carry on with alone, because a secret it needs is not set or a person took over the phone, waits in needs_human until you resume it.

Endpoints

GET
/v1/runsruns:read
Recent runs. Takes limit (up to 200) and state.
POST
/v1/runsruns:write
Starts a run.
GET
/v1/runs/{id}runs:read
One run, with the state of each phone in it.
POST
/v1/runs/{id}/stopruns:write
Stops the run on every phone and lets them go.
POST
/v1/runs/{id}/phones/{phoneId}/resumeruns:write
Carries on with a phone that was waiting in needs_human.
GET
/v1/runs/{id}/stepsruns:read
Every action taken, in order, up to 500 a page. Page with after; a page shorter than limit is the last.
GET
/v1/runs/{id}/steps/{phoneId}/{n}/screenshotruns:read
The screenshot taken at one step. Kept for 30 days.
GET
/v1/runs/{id}/eventsruns:read
A server-sent event stream of the run's progress.

Following a run

Each event has a seq number, a type of state, step or message, and the phone it concerns. To pick up where you left off, reconnect with the last seq you saw in Last-Event-ID. A connection lasts at most 30 minutes. Once a finished run has nothing more to send, the endpoint answers 204.

terminal
curl -N https://api.distilled.cx/v1/runs/run_5t1x/events \
  -H "Authorization: Bearer $DISTILLED_KEY" \
  -H "Last-Event-ID: 41"

Something missing or unclear? Tell us and we will fix the page. The API also describes itself in OpenAPI.