> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vern.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Poll a run

> Track a run to completion, read the import report, recover a run you lost, and cancel one in flight.

```http theme={null}
GET   https://app.vern.so/api/v1/migrations/{migration_id}/runs/{run_id}
PATCH https://app.vern.so/api/v1/migrations/{migration_id}/runs/{run_id}
```

Reads the state of a [run](https://docs.vern.so/migration-api/concepts.md#runs).

For live progress, use the [thread stream](https://docs.vern.so/migration-api/stream-the-thread.md) —
it pushes events as they happen and doesn't consume your read budget per update.
Polling is for checking whether a run has settled: poll on an interval of **≈10
seconds**, backing off, until `status` is terminal for its phase.

Polling faster than that will exhaust your [read limit](https://docs.vern.so/migration-api/errors.md#rate-limits)
without telling you anything sooner — runs take minutes, not seconds.

## Authentication

Requires an `x-api-key` header. See [Authentication](https://docs.vern.so/migration-api/authentication.md).

## Response by status

Every response carries `run_id`, `status`, `created_at`, and `instructions` (the
guidance you gave when you [started the run](https://docs.vern.so/migration-api/start-a-run.md#request-body),
or `null`). Once you've answered
the agent, the response also echoes `answers` (your reply, read back). The rest
depends on `status`:

**status** `string`

One of `queued`, `running`, `blocked`, `awaiting_approval`, `completed`,
`failed`, or `canceled`.

| `status` | Extra fields |
| - | - |
| `queued` / `running` | `message` — a human-readable update (e.g. `"Cleaning your data"`, `"Retrying (attempt 2 of 5)"`), or `null`. |
| `blocked` | `blocked_reason` — `"question"` (the agent needs a decision; carries `questions[]`) or `"credentials"` (a live source needs secrets; carries `credential_request`). See [below](#a-blocked-run). |
| `awaiting_approval` | *(none)* — a `generate`/`update` run produced a preview. Fetch it from [`GET /preview`](https://docs.vern.so/migration-api/get-the-preview). |
| `completed` | `report` for an `execute` run (see below); nothing extra for a `clarify` run. |
| `failed` | `error` — the agent couldn't produce a working result even after self-healing. For an execute, no rows were inserted. |
| `canceled` | *(none)* — the run was stopped before it finished. |

**answers** `object | null`

Present once you've answered a block — a normalized read-back of your last
reply, so a UI can show what was submitted. Absent before the first answer.

A **completed `execute`** carries a report:

```json theme={null}
{
  "run_id": "d4c3b2a1-...",
  "status": "completed",
  "created_at": "2026-06-19T15:40:02.000Z",
  "report": {
    "inserted": 1450,
    "perSheet": [
      { "templateName": "Contacts", "sheetId": "7a1c2b3d-...", "rowCount": 1450 }
    ],
    "invalidCellCount": 12,
    "coverage": null
  }
}
```

**report.inserted** `number`

Total rows imported across all sheets.

**report.perSheet** `object[]`

Per-template counts — `{ templateName, sheetId, rowCount }`.

**report.invalidCellCount** `number`

The number of **rows** that still have at least one cell that failed validation
— not a count of individual cells. The import succeeded; those rows are simply
flagged. CSV exports include every row, flagged or not, so check this count
before you load the data. See [Export CSV](https://docs.vern.so/migration-api/export-csv.md).

**report.coverage** `object | null`

An optional value-completeness profile — per-column fill/distinct stats for the
source inputs and the imported outputs — so a hollow import (right row count,
dropped fields) is detectable programmatically. `null` when profiling wasn't
available for the run.

Coverage reports **statistics only** — fill rates and distinct counts, never
sample cell values. It tells you *how much* landed in a column, not *what* is
in it. To see actual values, [export the sheet](https://docs.vern.so/migration-api/export-csv.md).

## A blocked run

A `blocked` run is waiting on you. **`blocked_reason` tells you which kind of
block it is** and which sub-resource resumes it:

| `blocked_reason` | Carries | Resume with |
| - | - | - |
| `question` | `questions[]` | [`POST .../messages`](https://docs.vern.so/migration-api/answer-questions) |
| `credentials` | `credential_request` | [`POST .../credentials`](https://docs.vern.so/migration-api/submit-credentials) |

### A question block

`blocked_reason: "question"` carries the `questions` you **render in your own
UI**. Each is self-describing — `{ id, question, context?, options[], allowCustom }`:

```json theme={null}
{
  "run_id": "d4c3b2a1-...",
  "status": "blocked",
  "created_at": "2026-06-19T15:32:11.000Z",
  "blocked_reason": "question",
  "questions": [
    {
      "id": "q1",
      "question": "Some Status values aren't one of the allowed options (Open, Closed, Pending). How should I handle them?",
      "options": [
        { "id": "a", "label": "Map them all to 'Open'" },
        { "id": "b", "label": "Drop those rows" }
      ],
      "allowCustom": true
    }
  ]
}
```

Answer through the run's [messages](https://docs.vern.so/migration-api/answer-questions.md) sub-resource —
not the poll. The agent resumes and may block again with a fresh question.

### A credential block

`blocked_reason: "credentials"` means a [connected live
source](https://docs.vern.so/migration-api/source-connection.md) needs secrets. The response carries a
`credential_request` — the connection it's for, plus a `schema` and `guidance`
you render into a form — and **no question**:

```json theme={null}
{
  "run_id": "d4c3b2a1-...",
  "status": "blocked",
  "created_at": "2026-06-19T15:32:11.000Z",
  "blocked_reason": "credentials",
  "credential_request": {
    "connection_id": "9b1f2c3d-...",
    "source_key": "salesforce",
    "source_name": "Salesforce",
    "reason": "I need API access to read your contacts.",
    "guidance": { "summary": "Create a connected app and copy its OAuth credentials." },
    "schema": { "client_id": { "type": "string" }, "client_secret": { "type": "string", "secret": true } }
  }
}
```

Submit the secrets through the dedicated
[credentials](https://docs.vern.so/migration-api/submit-credentials.md) sub-resource — **never** as a
message answer, which would leak them into the agent thread.

## Recovering a run

If you lose a `run_id` (a crash, a dropped response, a page reload), re-issue the
same [run](https://docs.vern.so/migration-api/start-a-run.md) you were running. Because **only one run
runs at a time per migration**, the call returns `409` with the active run's ID:

```json theme={null}
{ "error": "A run is already in progress for this migration.", "run_id": "d4c3b2a1-..." }
```

Poll that `run_id` as usual.

> [!NOTE]
>
> A run whose engine dies without writing a terminal status is swept to `failed`
> ("Import timed out") once it goes stale — so a lookup never reports a zombie run
> as forever-running.

## Cancel a run

```http theme={null}
PATCH https://app.vern.so/api/v1/migrations/{migration_id}/runs/{run_id}
```

Cancels an in-flight run — it stops the durable workflow and any active import
task. The only accepted body is:

```json theme={null}
{ "status": "cancel_requested" }
```

The response is the run in its updated (`canceled`) shape.

```bash theme={null}
curl -X PATCH https://app.vern.so/api/v1/migrations/c0a8012e-.../runs/d4c3b2a1-... \
  -H "x-api-key: $VERN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "cancel_requested" }'
```

## Errors

| Status | Meaning |
| - | - |
| `400` | (PATCH) body isn't `{ "status": "cancel_requested" }`. |
| `401` | API key missing or invalid. |
| `404` | No such run, or the migration isn't in your account. |
| `409` | (PATCH) The migration is archived (`code: "migration_archived"`). |
| `429` | **30 requests per minute** per account — polling is in the **Reads** class, cancelling in the **Writes** class. Check `Retry-After`. See [Rate limits](https://docs.vern.so/migration-api/errors.md#rate-limits). |
| `500` | Server error. |

## Example

```bash theme={null}
curl https://app.vern.so/api/v1/migrations/c0a8012e-.../runs/d4c3b2a1-... \
  -H "x-api-key: $VERN_API_KEY"
```

## Next

* [Answer the agent](https://docs.vern.so/migration-api/answer-questions.md) — resume a question block.
* [Submit credentials](https://docs.vern.so/migration-api/submit-credentials.md) — resume a credential block.
* [Get the preview](https://docs.vern.so/migration-api/get-the-preview.md) — read what a generate/update produced.
* [Export CSV](https://docs.vern.so/migration-api/export-csv.md) — get the validated rows out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.