---
title: "Start a script run on given profiles; returns the run immediately (its `id` is the run_id)."
method: POST
path: "/v1/scripts/run"
---

# Start a script run on given profiles; returns the run immediately (its \`id\` is the run_id).

`POST /v1/scripts/run`

## Request

- Base URL: `http://127.0.0.1:10108`
- URL: `http://127.0.0.1:10108/v1/scripts/run`
- Auth: HTTP bearer

Starts the script on the given profiles in the background: each profile's browser opens and the script drives it. An unapproved script runs on at most 3 profiles and without the profiles' stored variables. Returns the run at once; read its result with GET /v1/runs/:id.

## Request body

- object
  - `headless` boolean: Launch the run's profiles headless, without a window — the same launch as launch_profile's `headless` (see there): the profile's fingerprint is unchanged. Default false.
  - `profile_ids` string[]
  - `script_id` string, uuid, required
  - `variables` object

## Response `200`

The run as recorded now, still `running`; poll GET /v1/runs/:id with its `id`.

- object
  - `completedAt` string, date-time, nullable, required
  - `error` string, nullable, required
  - `id` string, uuid, required
  - `profileIds` string[], required
  - `profilesDone` integer, required
  - `profilesFailed` integer, required
  - `profilesTotal` integer, required
  - `scheduleId` string, uuid, nullable, required
  - `scriptId` string, uuid, nullable, required
  - `source` 'schedule' | 'app' | 'agent' | 'null', nullable, required
  - `startedAt` string, date-time, required
  - `status` 'running' | 'completed' | 'partial' | 'failed' | 'skipped', required

## Other responses

- `400`: `script_id` or `profile_ids` is missing, a variable is invalid, the plan lacks Veilus Flow, or an unapproved script targets more than 3 profiles.
- `401`: No bearer token, or not a token this app issued. The body is empty: it never says which.
- `403`: Refused by the plan: it no longer includes the local API (checked on every request), or it does not allow this action (profile or schedule limit, parallel runs). A request whose Host header is not loopback is also 403, with an empty body.
- `404`: No script with this id.
- `429`: Too many expensive calls from this token: launch, script run, batch, run schedule now, create profiles and import proxies count together, 30 per rolling 60 s. The Retry-After header gives the seconds to wait.
- `500`: Veilus failed: storage could not be read or written, or a task panicked. The message says what failed; retrying rarely helps.

---

[API](https://skmtc.dev/veilus/apis/veilus-local-api.md) · [All operations](https://skmtc.dev/veilus/apis/veilus-local-api/llms.txt) · [OpenAPI document](https://skmtc.dev/veilus/apis/veilus-local-api/revisions/67ac3818f9d2?raw)