PRprolific
aiTaskBuilder

Update a Batch

Changed on

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.

patch/api/v1/data-collection/batches/{batch_id}

Request

  • Base URL
    https://api.prolific.com
  • URL
    https://api.prolific.com/api/v1/data-collection/batches/{batch_id}
  • Auth
    API key in header Authorization

Path parameters

batch_idstring required

The unique identifier of the batch

Request body

namestring
dataset_idstring uuid
auto_sync_enabledboolean

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

Ok

idstring uuid required
created_atstring date-time required

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

created_bystring required

User ID of the Prolific user that created the resource.

namestring required
status'UNINITIALISED' | 'PROCESSING' | 'READY' | 'ERROR' required
total_task_countinteger required
total_instruction_countinteger required
workspace_idstring required
schema_versioninteger required
total_task_groupsinteger required
auto_sync_enabledboolean

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.

Changes

  • 9449de4ad274Revision changes
    • breaking

      added subschema #9 to the /////// response property oneOf list for the response status

    • info

      added subschema #9 to the /////// request property oneOf list

  • 6c9aa73fa51fRevision changes
    • warning

      deleted the header request parameter Authorization

    • info

      the endpoint scheme security token was added to the API