---
title: "Get a Batch"
method: GET
path: "/api/v1/data-collection/batches/{batch_id}"
tags: ["aiTaskBuilder"]
---

# Get a Batch

`GET /api/v1/data-collection/batches/{batch_id}`

Get a specific AI Task Builder batch by its unique identifier.

## Path parameters

- `batch_id` string, required

## Headers

- `Authorization` string, required

## Response `200`

Ok

- AITaskBuilderBatch
  - `id` string, uuid, required
  - `created_at` string, date-time, required — An ISO-8601 formatted string representing the batch creation time, in UTC.
  - `created_by` string, required — User ID of the Prolific user that created the resource.
  - `datasets` AiTaskBuilderBatchDatasetsItems[], required
    - `id` string, uuid, required
    - `total_datapoint_count` integer, required
    - `filename` string, required — The filename of the dataset
  - `name` string, required
  - `status` 'UNINITIALISED' | 'PROCESSING' | 'READY' | 'ERROR', required
  - `total_task_count` integer, required
  - `total_instruction_count` integer, required
  - `workspace_id` string, required
  - `schema_version` integer, required
  - `task_details` AiTaskBuilderBatchTaskDetails, required
    - `task_name` string, required
    - `task_introduction` string, required — HTML formatted task introduction
    - `task_steps` string, required — HTML formatted task steps
  - `total_task_groups` integer, required
  - `batch_items` BatchItemsPage[], nullable — 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`.
    - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing page when updating.
    - `rows` BatchItemsRow[], required
      - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing row when updating.
      - `columns` BatchItemsColumn[], required
        - `id` string — Server-assigned identifier; present on responses. Include to preserve an existing column when updating.
        - `items` BatchItemsItem[], required
          - union — A single item within a column. One of: a dataset field reference (`dataset_field`), a content block (`image`, `rich_text`), or an instruction (`free_text`, `free_text_with_unit`, `multiple_choice`, `multiple_choice_with_free_text`, `file_upload`). Discriminated on `type`.
            - object — References a field in the batch's attached dataset. At task time, the dataset value for the current datapoint is rendered at this position. Only dataset schema fields of type `text`, `image_url`, `audio_url`, or `video_url` are permitted, and the same field may not be referenced more than once on the same page.
              - …
            - object — An image content block rendered inline within the batch layout.
              - …
            - object — A rich-text content block rendered inline within the batch layout.
              - …
            - object — Free-text input instruction.
              - …
            - object — Free-text input instruction paired with a unit selector.
              - …
            - object — Multiple-choice instruction.
              - …
            - object — Multiple-choice instruction with an additional free-text input per selected option.
              - …
            - object — File upload instruction.
              - …
  - `auto_sync_enabled` boolean — 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.

## Other responses

- `400` — Error

---

[API](https://skmtc.net/prolific/apis/api-reference.md) · [All operations](https://skmtc.net/prolific/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/prolific/api-reference/versions/5c53371c41a0/schema)