Configurable Layout (batch_items)

The batch_items field lets you control exactly how content is arranged on the participant task screen. Instead of a fixed, sequential layout, you describe your task as a set of pages, rows, and columns, and place dataset stimuli, display content, and input questions wherever you want them.

This unlocks layouts such as side-by-side evaluations, mixed display and input blocks, and multi-column comparisons — all defined declaratively when you create or update a Batch.

When to use batch_items

When batch_items is set, instructions are defined inline within the layout rather than through the standalone instructions endpoint — giving you full control over where they appear relative to dataset stimuli and display content. See Relationship to the standalone instructions endpoint.

Structure

batch_items is a four-level nested structure:

batch_items = Page[]
Page        = { rows: Row[] }
Row         = { columns: Column[] }   // 1–2 columns
Column      = { items: ColumnItem[] }

• A page is repeated once per dataset row. For the current single-task Batch use case, batch_items typically contains a single page.
• A row stacks vertically down the screen.
• A column sits horizontally within a row (maximum 2 per row).
• An item is a single component rendered top-to-bottom within its column.

Column item types

Each item in a column is a tagged object discriminated by its type field. There are three categories.

Dataset fields

Pull a value from your dataset schema into the layout.

Only fields typed text or image_url can be referenced. Fields typed metadata or task_group_id are not participant-visible and are rejected.

1
{ "type": "dataset_field", "field": "response_a" }

Content blocks (display-only)

Static content defined inline. These use the same schemas as content blocks elsewhere in AI Task Builder.

rich_text

1
{
2
  "type": "rich_text",
3
  "content": "<p>Rate each response for factual accuracy.</p>",
4
  "content_format": "html"
5
}

image

1
{
2
  "type": "image",
3
  "url": "https://example.com/reference.png",
4
  "alt_text": "Reference diagram",
5
  "caption": "Figure 1"
6
}

Instructions (inputs)

Input questions defined inline. These use the standard AI Task Builder instruction input schemas — the same ones documented in Instructions. Supported types:

• free_text
• free_text_with_unit
• multiple_choice
• multiple_choice_with_free_text
• file_upload

1
{
2
  "type": "multiple_choice",
3
  "description": "Which response is more accurate?",
4
  "answer_limit": 1,
5
  "options": [
6
    { "label": "Response A", "value": "a" },
7
    { "label": "Response B", "value": "b" }
8
  ]
9
}

Example: side-by-side evaluation

A comparison layout with per-column ratings and a shared free-text follow-up. The first row shows shared guidance; the second row places each image and its rating in its own column; the third row collects reasoning across the full width. Here each image is displayed with an image content block.

1
{
2
  "batch_items": [
3
    {
4
      "rows": [
5
        {
6
          "columns": [
7
            {
8
              "items": [
9
                {
10
                  "type": "rich_text",
11
                  "content": "<p>Compare the two images and rate how well each one matches the prompt.</p>",
12
                  "content_format": "html"
13
                }
14
              ]
15
            }
16
          ]
17
        },
18
        {
19
          "columns": [
20
            {
21
              "items": [
22
                {
23
                  "type": "image",
24
                  "url": "https://example.com/image_a.png",
25
                  "alt_text": "Response A"
26
                },
27
                {
28
                  "type": "multiple_choice",
29
                  "answer_limit": 1,
30
                  "options": [
31
                    { "label": "Matches the prompt", "value": "match" },
32
                    { "label": "Does not match", "value": "no_match" }
33
                  ]
34
                }
35
              ]
36
            },
37
            {
38
              "items": [
39
                {
40
                  "type": "image",
41
                  "url": "https://example.com/image_b.png",
42
                  "alt_text": "Response B"
43
                },
44
                {
45
                  "type": "multiple_choice",
46
                  "answer_limit": 1,
47
                  "options": [
48
                    { "label": "Matches the prompt", "value": "match" },
49
                    { "label": "Does not match", "value": "no_match" }
50
                  ]
51
                }
52
              ]
53
            }
54
          ]
55
        },
56
        {
57
          "columns": [
58
            {
59
              "items": [
60
                {
61
                  "type": "free_text",
62
                  "helper_text": "Explain your reasoning"
63
                }
64
              ]
65
            }
66
          ]
67
        }
68
      ]
69
    }
70
  ]
71
}

Setting batch_items

Provide batch_items when creating (or updating) a Batch, alongside your dataset and task details.

$
POST /api/v1/data-collection/batches

1
{
2
  "name": "Response evaluation batch",
3
  "workspace_id": "6278acb09062db3b35bcbeb0",
4
  "dataset_id": "0192a3b5-e8f9-7a0b-1c2d-3e4f5a6b7c8d",
5
  "task_details": {
6
    "task_name": "Evaluate AI Responses"
7
  },
8
  "batch_items": [
9
    {
10
      "rows": [
11
        {
12
          "columns": [
13
            {
14
              "items": [
15
                { "type": "dataset_field", "field": "prompt" }
16
              ]
17
            }
18
          ]
19
        }
20
      ]
21
    }
22
  ]
23
}

Validation runs at Batch creation and update time, before any participant-facing tasks are generated. An invalid batch_items value is rejected with a 422 response listing every offending item and its position:

1
{
2
  "type": "INVALID_BATCH_ITEMS",
3
  "message": "batch_items validation failed",
4
  "issues": [
5
    {
6
      "page": 0,
7
      "row": 1,
8
      "column": 0,
9
      "item": 0,
10
      "type": "dataset_field",
11
      "field": "responze_a",
12
      "message": "Field not found in dataset schema"
13
    }
14
  ]
15
}

Each issue pinpoints the item by its zero-based page, row, column, and item index, along with the item type and (for dataset_field items) the offending field.

Constraints and validation

Structural

• Maximum 2 columns per row.
• No limit on the number of rows.
• No limit on the number of items within a column.
• Each page must contain at least one row; each row at least one column; each column at least one item.

Dataset fields

• field must match a field in the dataset schema with type text or image_url.
• metadata and task_group_id fields are rejected — they are not participant-visible.
• The same field may not appear more than once across a page.

Instructions and content blocks

• Instruction items are validated against the existing instruction input schemas (the same validation applied to standalone instructions).
• Content block items are validated against the existing content block schemas.

Relationship to the standalone instructions endpoint

There are two ways to define instructions on a Batch, and they are mutually exclusive:

• Standalone endpoint (legacy): POST /api/v1/data-collection/batches/{batch_id}/instructions — see Working with Batches. Used when batch_items is not set.
• Inline in batch_items: instruction items defined directly in the layout.

When batch_items is set, the inline instructions are the source of truth. The standalone instructions endpoints are deprecated for such Batches and reject create and update calls with a 422.

Extensibility

The layout model is designed to grow without breaking existing batch_items values:

• New component types (for example audio and video stimuli, or additional input types) are additive — existing layouts remain valid.
• Multi-page tasks are supported by the array structure from the start.
• The wider participant task model (Sections → Pages → Components) maps cleanly onto this structure: each page is a Body page, and each column item is a component.

By using AI Task Builder, you agree to our AI Task Builder Terms.