Poll a run

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. Poll it on an interval (≈2s, backing off) until status is terminal for its phase. For live progress, prefer the thread stream.

Authentication

Requires an x-api-key header. See Authentication.

Response by status

Every response carries run_id, status, and created_at. 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.
`awaiting_approval`	(none) — a `generate`/`update` run produced a preview. Fetch it from `GET /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:

{
  "run_id": "e5d4c3b2-...",
  "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. The default CSV download (?filter=valid) excludes any flagged row entirely, so a single bad cell drops its whole row. See Export CSV.

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.

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`
`credentials`	`credential_request`	`POST .../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 }:

{
  "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 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 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:

{
  "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 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 you were running. Because only one run runs at a time per migration, the call returns 409 with the active run’s ID:

{ "error": "A run is already in progress for this migration.", "run_id": "d4c3b2a1-..." }

Poll that run_id as usual.

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

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:

{ "status": "cancel_requested" }

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

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.
`429`	Rate limit hit — back off and retry.
`500`	Server error.

Example

curl https://app.vern.so/api/v1/migrations/c0a8012e-.../runs/d4c3b2a1-... \
  -H "x-api-key: $VERN_API_KEY"

Answer the agent — resume a question block.
Submit credentials — resume a credential block.
Get the preview — read what a generate/update produced.
Export CSV — get the validated rows out.

Overview

Get started

API reference

Reference

Authentication

Response by status

A blocked run

A question block

A credential block

Recovering a run

Cancel a run

Errors

Example

Next

​Authentication

​Response by status

​A blocked run

​A question block

​A credential block

​Recovering a run

​Cancel a run

​Errors

​Example

​Next

Authentication

Response by status

A blocked run

A question block

A credential block

Recovering a run

Cancel a run

Errors

Example

Next