---
title: "Start a run"
method: POST
path: "/migrations/{migration_id}/runs"
tags: ["Runs"]
---

# Start a run

`POST /migrations/{migration_id}/runs`

## Request

- Base URL: `https://app.vern.so/api/v1`
- URL: `https://app.vern.so/api/v1/migrations/{migration_id}/runs`
- Auth: API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/vern-so/apis/vern-api/docs/migrations/:migration_id/runs/post.ts> (a function with typed inputs; its response is checked against the schema)

Start one managed-agent run. `generate` authors the recipe and stops at a preview; `update` edits it per `message`; `clarify` asks a read-only question; `execute` runs the approved preview for real. `generate` opens a preview run and `update`/`clarify`/`execute` resume that same run, so the `run_id` stays stable from preview through execution (a resuming call returns `status: "running"`). Only one run runs at a time per migration (409 with the active run_id otherwise).

## Request body

- object
  - `kind` 'generate' | 'update' | 'clarify' | 'execute', required
  - `message` string: Required for update and clarify — your instruction or question in plain language.
  - `extract_via_api` boolean: generate only. Controls live API extraction from a connected source: true extracts via the connection (alongside any files), false forces file-only, omitted extracts via API only when no files were uploaded and a connection exists.
  - `instructions` string, nullable: generate only. Optional guidance for this migration (at most 200 characters), e.g. "Only import active customers". The agent follows it but it cannot override Vern's rules, a locked template or the Memory setting. Kept for every later leg of the run and returned on the run as `instructions`. Longer than 200 characters returns 400 with code instructions_too_long.

## Response `201`

The run was accepted. A `generate` is `queued`; a resuming `update`/`clarify`/`execute` is `running`. Poll `poll_url`.

- RunAccepted
  - `run_id` string, uuid
  - `status` string
  - `poll_url` string, uri

## Other responses

- `400`: Malformed request.
- `401`: API key missing, malformed, or revoked.
- `404`: The referenced resource isn't in your account.
- `409`: A run is already in progress (the body carries the active run_id), there is no preview to act on / execute, or the approved preview is no longer resumable (generate a fresh one).
- `429`: Either the hourly rate limit on `kind: "generate"` (30/hour per account) or the concurrent-run limit (3 in progress). The concurrency refusal is identifiable by `code: "run_concurrency_limit"` and lists the blocking runs; a plain rate limit carries only `error` plus `Retry-After`.

## Changes

- **2026-10-11** `9293d74a6a03`: 1 info
  - added the new optional request property `instructions`
- **2026-10-01** `88ecf83c848f`: 3 breaking
  - added `#/components/schemas/Error, #/components/schemas/RunConcurrencyError` to the response body `oneOf` list for the response status `429`
  - the response's body type changed from `object` to no type for status `429`
  - removed the required property `error` from the response with the `429` status
- **2026-06-25** `aaaced6a1cac`: 1 info
  - added the new optional request property `extract_via_api`
- **2026-06-18** `c5a09eb23a64`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vern-so/apis/vern-api/changes/migrations/:migration_id/runs/post.md)

---

[API](https://skmtc.dev/vern-so/apis/vern-api.md) - [All operations](https://skmtc.dev/vern-so/apis/vern-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vern-so/apis/vern-api/revisions/6ae61af2db81?raw)