Update a Batch | Prolific API

{
  "id": "a3f1c2d4-5678-4e9b-9f12-3456789abcde",
  "created_at": "2024-01-15T09:30:00Z",
  "created_by": "6278cb09062dbb35bc4abebc",
  "datasets": [
    {
      "id": "b7d9f8e1-2345-4cde-8f90-123456789abc",
      "total_datapoint_count": 150,
      "filename": "customer_feedback_2024.csv"
    }
  ],
  "name": "Data Collection Batch",
  "status": "UNINITIALISED",
  "total_task_count": 1,
  "total_instruction_count": 1,
  "workspace_id": "6278acb09062db3b35bcbeb0",
  "schema_version": 1,
  "task_details": {
    "task_name": "Customer Feedback Analysis",
    "task_introduction": "<p>Welcome to the customer feedback analysis task. Please follow the instructions carefully.</p>",
    "task_steps": "<ol><li>Read the feedback carefully.</li><li>Provide your analysis in the fields provided.</li><li>Submit your responses.</li></ol>"
  },
  "total_task_groups": 1,
  "batch_items": [
    {
      "rows": [
        {
          "columns": [
            {
              "items": [
                {
                  "type": "dataset_field",
                  "field": "feedback_text"
                }
              ],
              "id": "col-001"
            }
          ],
          "id": "row-001"
        }
      ],
      "id": "page-001"
    }
  ]
}

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.

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>.

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.

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

total_task_countinteger>=0

total_instruction_countinteger>=0

workspace_idstring

schema_versioninteger

task_detailsobject

total_task_groupsinteger>=0

batch_itemslist of objects or null

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.

Errors

400

Bad Request Error

4XX

Client Request Error

422

Unprocessable Entity Error

$	curl -X PATCH https://api.prolific.com/api/v1/data-collection/batches/batch_id \
>	-H "Authorization: Token <token>" \
>	-H "Content-Type: application/json" \
>	-d '{}'