Update a Batch | Prolific API

{
  "id": "string",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by": "6278cb09062dbb35bc4abebc",
  "datasets": [
    {
      "id": "string",
      "total_datapoint_count": 1,
      "filename": "string"
    }
  ],
  "name": "Data Collection Batch",
  "status": "UNINITIALISED",
  "total_task_count": 1,
  "total_instruction_count": 1,
  "workspace_id": "6278acb09062db3b35bcbeb0",
  "schema_version": 1,
  "task_details": {
    "task_name": "string",
    "task_introduction": "string",
    "task_steps": "string"
  },
  "total_task_groups": 1,
  "batch_items": [
    {
      "rows": [
        {
          "columns": [
            {
              "items": [
                {
                  "type": "dataset_field",
                  "field": "string"
                }
              ],
              "id": "string"
            }
          ],
          "id": "string"
        }
      ],
      "id": "string",
      "display_position": "intro"
    }
  ],
  "auto_sync_enabled": true
}

Update an existing AI Task Builder batch. You can update the name, task details, associated dataset, and/or batch_items. The dataset does not need to be in READY status for updates.

When updating batch_items, include the id of any existing pages, rows, columns, or items you want to preserve — items without an id are treated as new and assigned one server-side. Omitting an existing id removes that entry. The same validation rules as on create apply, and validation failures return 422 Unprocessable Entity with the BatchItemsValidationError payload.

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

batch_idstringRequired

The unique identifier of the batch

Request

This endpoint expects an object.

namestringOptional

task_detailsobjectOptional

dataset_idstringOptionalformat: "uuid"

batch_itemslist of objects or nullOptional

Replacement layout for the batch’s instructions and content. Include the id of any existing pages, rows, columns, or items you want to preserve; omit id to add new entries. Items absent from the payload are removed.

auto_sync_enabledbooleanOptional

When true, datapoints subsequently appended to the batch’s attached dataset (via POST /datasets/{dataset_id}/datapoints) automatically trigger a sync that materialises tasks for them — no explicit POST /batches/{batch_id}/sync call is needed. When false, appended datapoints are only picked up by an explicit sync. If this field is omitted from the PATCH payload, the existing auto-sync setting is left unchanged.

A sync (auto or manual) only creates tasks on the batch — it doesn’t grow the places on any study built from the batch unless that study opted in via data_collection_metadata.increase_places_on_sync.

Response

idstringformat: "uuid"

created_atdatetime

An ISO-8601 formatted string representing the batch creation time, in UTC.

created_bystring

User ID of the Prolific user that created the resource.

datasetslist of objects

namestring

statusenum

Allowed values:

total_task_countinteger>=0

total_instruction_countinteger>=0

workspace_idstring

schema_versioninteger

task_detailsobject

total_task_groupsinteger>=0

batch_itemslist of objects or nullOptional

The persisted batch_items layout, populated when the batch was created with batch_items. null for legacy batches authored via the standalone instructions endpoint. Every page, row, column, and item carries a server-assigned id.

auto_sync_enabledbooleanOptional

When true, datapoints appended to the batch’s attached dataset automatically trigger a sync that materialises tasks for them. Optional — absent on batches that have never enabled auto-sync. Absent or false mean auto-sync is off.

Errors

400

Bad Request Error

4XX

Client Request Error

422

Unprocessable Entity Error