Get Schema Migration Status

GET

https://api.prolific.com/api/v1/data-collection/datasets/:dataset_id/schema-migrations/:job_id

GET

/api/v1/data-collection/datasets/:dataset_id/schema-migrations/:job_id

curl https://api.prolific.com/api/v1/data-collection/datasets/dataset_id/schema-migrations/job_id \
     -H "Authorization: Token <token>" \
     -H "Content-Type: application/json"

{
  "dataset_id": "a3f1c2d4-8e57-4b9a-bc12-3d7e5f901234",
  "job_id": "7b2e9f1a-4c63-4d8e-a015-9f3b2c7d5e81",
  "schema_version": 3,
  "created_at": "2024-06-10T08:15:00Z",
  "updated_at": "2024-06-10T08:22:45Z",
  "status": "partial",
  "reprocessed_count": 1842,
  "failed_count": 17,
  "errors": [
    {
      "datapoint_id": "c9d4e2f7-1a3b-4c56-8d90-ef1234567890",
      "field": "response_rating",
      "reason": "Value '6' exceeds the maximum allowed by the new schema (max: 5); field was nulled."
    }
  ],
  "reason": "Schema version incompatibility prevented full reprocessing of all datapoints."
}

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.

Authentication

AuthorizationToken

The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings.

Your API token does not have an expiry date and carries full permission, so be sure to keep them secure.

If your token is leaked, delete it and create a new one directly in the app.

In your requests add Authorization header with the value Token <your token>.

Path parameters

dataset_idstringRequiredformat: "uuid"

The unique identifier of the dataset

job_idstringRequiredformat: "uuid"

The schema migration job ID

Response

Schema migration job status

dataset_idstringformat: "uuid"

The dataset being migrated.

job_idstringformat: "uuid"

The unique identifier of the schema migration job.

schema_versioninteger>=1

The schema version this job reprocesses datapoints up to.

created_atdatetime

When the migration job was created (ISO 8601, UTC).

updated_atdatetime

When the migration job was last updated (ISO 8601, UTC).

statusenum

Current status of the migration job.

Allowed values:

reprocessed_countintegerOptional>=0

Number of datapoints reprocessed. Present when status is complete or partial.

failed_countintegerOptional>=0

Number of datapoints with at least one field that could not be re-normalised. Present when status is partial.

errorslist of objectsOptional

Record-level failures — fields nulled because they were invalid under the new schema. Present when status is partial.

reasonstringOptional

Human-readable reason for failure. Present when status is failed.

Errors

4XX

Client Request Error

404

Not Found Error