> ## 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 > 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). ## OpenAPI ````yaml /api-reference/openapi.json get /migrations/{migration_id}/runs/{run_id} openapi: 3.1.0 info: title: Vern Migration API version: 1.0.0 description: >- Run Vern as a headless migration engine. Create a migration, upload a customer's files, run the managed agent to generate a preview, then execute and export clean data. See the Migration API guides for concepts and walkthroughs. servers: - url: https://app.vern.so/api/v1 security: - apiKey: [] tags: - name: Catalog description: Discover the sources and templates you set up in the Vern UI. - name: Migrations description: Create a migration workspace and upload a customer's files. - name: Runs description: 'Drive the managed agent: generate, refine, execute, answer, and observe.' - name: Export description: Download a migration's validated data as CSV. paths: /migrations/{migration_id}/runs/{run_id}: parameters: - $ref: '#/components/parameters/MigrationId' - $ref: '#/components/parameters/RunId' get: tags: - Runs summary: Poll a run description: >- 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). operationId: getRun responses: '200': description: The run's current state. content: application/json: schema: $ref: '#/components/schemas/Run' examples: running: summary: running value: run_id: d4c3b2a1-... status: running created_at: '2026-06-19T15:32:11.000Z' message: Cleaning your data blocked: summary: blocked (question) value: 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. How should I handle them? options: - id: a label: Map them all to 'Open' - id: b label: Drop those rows allowCustom: true blocked_credentials: summary: blocked (credentials) value: 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. schema: client_id: type: string client_secret: type: string secret: true awaiting_approval: summary: awaiting_approval value: run_id: d4c3b2a1-... status: awaiting_approval created_at: '2026-06-19T15:32:11.000Z' completed: summary: completed (execute) value: 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 failed: summary: failed value: run_id: d4c3b2a1-... status: failed created_at: '2026-06-19T15:32:11.000Z' error: Run failed or timed out '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: MigrationId: name: migration_id in: path required: true description: The migration ID returned by Create a migration. schema: type: string format: uuid example: c0a8012e-4f1b-4d3a-9b2c-7e6f5a4b3c2d RunId: name: run_id in: path required: true description: The run ID returned by Start a run. schema: type: string format: uuid example: d4c3b2a1-9f8e-47d6-b5a4-c3d2e1f0a9b8 schemas: Run: type: object description: >- A run's polled state. Fields beyond run_id/status/created_at depend on status. properties: run_id: type: string format: uuid status: type: string enum: - queued - running - blocked - awaiting_approval - completed - failed - canceled created_at: type: string format: date-time answers: type: - object - 'null' description: >- A read-back of your last reply, present once you've answered a block. message: type: - string - 'null' description: Present while queued/running. blocked_reason: type: string enum: - question - credentials description: Present when blocked — which kind of block it is. questions: type: array items: $ref: '#/components/schemas/Question' description: Present when blocked for a question. credential_request: $ref: '#/components/schemas/CredentialRequest' report: $ref: '#/components/schemas/Report' error: type: string description: Present when failed. Question: type: object properties: id: type: string question: type: string context: type: string options: type: array items: type: object properties: id: type: string label: type: string allowCustom: type: boolean CredentialRequest: type: object description: >- 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. properties: connection_id: type: string format: uuid description: The source connection the secrets belong to. source_key: type: string source_name: type: string reason: type: string description: Why the agent needs access. May be absent. guidance: type: object description: >- Optional help — { summary?, steps?, links? } — for where to find the credentials. schema: type: object description: The fields to collect, keyed by name. additionalProperties: true Report: type: object properties: inserted: type: integer description: Total rows imported across all sheets. perSheet: type: array items: type: object properties: templateName: type: string sheetId: type: string rowCount: type: integer invalidCellCount: type: integer description: Rows that still carry at least one invalid cell. coverage: type: - object - 'null' description: Optional per-column fill/distinct profile of sources vs. outputs. Error: type: object properties: error: type: string description: A human-readable error message. required: - error responses: Unauthorized: description: API key missing, malformed, or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The referenced resource isn't in your account. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: Rate limit hit — back off and retry. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Too many requests securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your Vern API key. Create one at Settings → API keys. ````