# Runs

> A run carries out one skill on up to 50 phones and records every action with a screenshot. How to start, follow, stop and resume one.

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

```bash
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"] }'
```

- `skill` (string | SkillDefinition, required): A saved skill's id, or a full definition for a one-off run.
- `phones` (string[]): 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/runs` (scope `runs:read`): Recent runs. Takes `limit` (up to 200) and `state`.
- `POST /v1/runs` (scope `runs:write`): Starts a run.
- `GET /v1/runs/{id}` (scope `runs:read`): One run, with the state of each phone in it.
- `POST /v1/runs/{id}/stop` (scope `runs:write`): Stops the run on every phone and lets them go.
- `POST /v1/runs/{id}/phones/{phoneId}/resume` (scope `runs:write`): Carries on with a phone that was waiting in `needs_human`.
- `GET /v1/runs/{id}/steps` (scope `runs: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}/screenshot` (scope `runs:read`): The screenshot taken at one step. Kept for 30 days.
- `GET /v1/runs/{id}/events` (scope `runs: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`.

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

Source: https://distilled.cx/docs/runs/