Poll a run

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

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.

For live progress, use the thread stream — 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 without telling you anything sooner — runs take minutes, not seconds.

Authentication

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

Response by status

Every response carries run_id, status, created_at, and instructions (the guidance you gave when you started the run, 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.
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.

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.

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	30 requests per minute per account (the Reads class). Check Retry-After. See Rate limits.
500	Server error.

Example

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

Next

• 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.