---
title: "Get Schema Migration Status"
method: GET
path: "/api/v1/data-collection/datasets/{dataset_id}/schema-migrations/{job_id}"
tags: ["aiTaskBuilder"]
---

# Get Schema Migration Status

`GET /api/v1/data-collection/datasets/{dataset_id}/schema-migrations/{job_id}`

Returns the current status of a schema migration job, which reprocesses a V4 dataset's
datapoints against a newer schema version.

A migration job has these statuses:
- `processing` — the migration is underway.

**Terminal statuses:**
- `complete` — all datapoints were reprocessed. `reprocessed_count` is populated.
- `partial` — some datapoints were reprocessed and some fields could not be re-normalised (and
  were nulled). `reprocessed_count`, `failed_count`, and `errors` are populated.
- `failed` — the migration failed entirely. `reason` is populated.

Continue polling while the status is `processing`.

## Path parameters

- `dataset_id` string, uuid, required
- `job_id` string, uuid, required

## Headers

- `Authorization` string, required

## Response `200`

Schema migration job status

- SchemaMigrationJob — Tracks the asynchronous re-normalisation of a V4 dataset's datapoints against a newer schema version. Poll `GET /datasets/{dataset_id}/schema-migrations/{job_id}` until a terminal status (`complete`, `partial`, or `failed`). The shape depends on `status`: the fields below marked as terminal-only are present only for the corresponding status.
  - `dataset_id` string, uuid, required — The dataset being migrated.
  - `job_id` string, uuid, required — The unique identifier of the schema migration job.
  - `schema_version` integer, required — The schema version this job reprocesses datapoints up to.
  - `created_at` string, date-time, required — When the migration job was created (ISO 8601, UTC).
  - `updated_at` string, date-time, required — When the migration job was last updated (ISO 8601, UTC).
  - `status` 'processing' | 'complete' | 'partial' | 'failed', required — Current status of the migration job.
  - `reprocessed_count` integer — Number of datapoints reprocessed. Present when status is `complete` or `partial`.
  - `failed_count` integer — Number of datapoints with at least one field that could not be re-normalised. Present when status is `partial`.
  - `errors` SchemaMigrationError[] — Record-level failures — fields nulled because they were invalid under the new schema. Present when status is `partial`.
    - `datapoint_id` string, uuid, required — The datapoint whose field could not be re-normalised.
    - `field` string, required — The schema field key that was nulled.
    - `reason` string, required — Human-readable description of why the field was nulled.
  - `reason` string — Human-readable reason for failure. Present when status is `failed`.

## Other responses

- `400` — Error
- `404` — Schema migration job not found

## Changes

- **2026-07-26** `421c6aa415ef` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/prolific/apis/api-reference/changes/api/v1/data-collection/datasets/:dataset_id/schema-migrations/:job_id/get.md)

---

[API](https://skmtc.dev/prolific/apis/api-reference.md) · [All operations](https://skmtc.dev/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/prolific/api-reference/revisions/ae92a54c3ced/schema)