---
title: "Poll a run"
method: GET
path: "/migrations/{migration_id}/runs/{run_id}"
tags: ["Runs"]
---

# Poll a run

`GET /migrations/{migration_id}/runs/{run_id}`

## Request

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

Read a run's state. Every response carries `run_id`, `status`, and `created_at` (plus `answers`, a read-back of your last reply, once you've answered a block); the rest depends on status (`message` while running, `blocked_reason` + `questions`/`credential_request` when blocked, `report` on a completed execute, `error` on failure).

## Response `200`

The run's current state.

- Run: A run's polled state. Fields beyond run_id/status/created_at depend on status.
  - `run_id` string, uuid
  - `status` 'queued' | 'running' | 'blocked' | 'awaiting_approval' | 'completed' | 'failed' | 'canceled'
  - `created_at` string, date-time
  - `instructions` string, nullable: The guidance given when the migration was generated (at most 200 characters), carried onto every later leg. Null when none was given.
  - `answers` object, nullable: A read-back of your last reply, present once you've answered a block.
  - `message` string, nullable: Present while queued/running.
  - `blocked_reason` 'question' | 'credentials': Present when blocked — which kind of block it is.
  - `questions` Question[]: Present when blocked for a question.
    - `id` string
    - `question` string
    - `context` string
    - `options` object[]
      - `id` string
      - `label` string
    - `allowCustom` boolean
  - `credential_request` CredentialRequest: Present when a run is blocked for credentials. Describes the live source needing secrets — render a form from `schema` and POST to .../credentials. Carries no secret values.
    - `connection_id` string, uuid: The source connection the secrets belong to.
    - `source_key` string
    - `source_name` string
    - `reason` string: Why the agent needs access. May be absent.
    - `guidance` object: Optional help — { summary?, steps?, links? } — for where to find the credentials.
    - `schema` object: The fields to collect, keyed by name.
  - `report` Report
    - `inserted` integer: Total rows imported across all sheets.
    - `perSheet` object[]
      - `templateName` string
      - `sheetId` string
      - `rowCount` integer
    - `invalidCellCount` integer: Rows that still carry at least one invalid cell.
    - `coverage` object, nullable: Optional per-column fill/distinct profile of sources vs. outputs.
  - `error` string: Present when failed.

## Other responses

- `401`: API key missing, malformed, or revoked.
- `404`: The referenced resource isn't in your account.
- `429`: Rate limit hit. Counted per account, not per API key. Creating a migration and starting a `generate` run are limited to 30/hour each; answering a run is limited to 30/hour; reads allow 30/minute and writes 30/minute. `Retry-After` gives the seconds until the window resets, alongside `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`.

## Changes

- **2026-10-11** `9293d74a6a03`: 1 info
  - added the optional property `instructions` to the response with the `200` status
- **2026-06-25** `aaaced6a1cac`: 3 info
  - added the optional property `answers` to the response with the `200` status
  - added the optional property `blocked_reason` to the response with the `200` status
  - added the optional property `credential_request` to the response with the `200` status
- **2026-06-18** `c5a09eb23a64`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/vern-so/apis/vern-api/changes/migrations/:migration_id/runs/:run_id/get.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)