# Get Started: Running AI Task Builder Batches via Prolific's API

# What you'll accomplish

* Upload raw datapoints (e.g., text, image URLs) into an **AI Task Builder Dataset**
* Create an **AI Task Builder Batch** and attach **Instructions**
* Convert your dataset into **tasks** and wait until the batch is **READY**
* Create and **publish a Prolific study** that references the batch
* Pull **annotated responses** from the batch

For detailed reference documentation, see:

* [Working with Batches](/api-reference/ai-task-builder/batches)
* [Working with Datasets](/api-reference/ai-task-builder/datasets)
* [Instructions](/api-reference/ai-task-builder/instructions)

# Prerequisites

* Your **workspace\_id**
* Your **API token** (`Authorization: Token ...`)
* Decide how many **tasks per participant** you want to show (via `tasks_per_group`)
* Decide your **study** settings (reward, sample size, timing, targeting)

# Step-by-step guide

<Steps>
  <Step>
    ## Create a Dataset

    Create a container that will hold the datapoints participants will annotate.

    <RunnableEndpoint endpoint="POST /api/v1/data-collection/datasets" example="task_builder_starter_dataset_create" readonly={["examples"]} />

    Response will include `id` (your `dataset_id`) and `status` (one of `UNINITIALISED|PROCESSING|READY|ERROR`).
  </Step>

  <Step>
    ## Request An Upload URL For Your Data

    Upload one or more files (CSV format) that contain the datapoints.

    <RunnableEndpoint endpoint="GET /api/v1/data-collection/datasets/{dataset_id}/upload-url/{filename}" readonly={["examples"]} />

    **The response body will be structured as follows**

    ```json
    {
        "upload_url": "string",
        "expires_at": "string",  // ISO-8601 DateTime string
        "http_method": "string", // PUT in all instances
        "dataset_id": "string"
    }
    ```
  </Step>

  <Step>
    ## Upload Your Data (files → dataset)

    Upload the file containing your datapoints.

    ```bash
    curl -X PUT "UPLOAD_URL_FROM_PREVIOUS_STEP" --data-binary "@{path_to_file}"
    ```

    **Poll status** until the dataset is processed:

    <RunnableEndpoint endpoint="GET /api/v1/data-collection/datasets/{dataset_id}" readonly={["examples"]} />

    ```bash
    {"status": "READY"} # (wait for READY)
    ```

    For advanced dataset options including metadata columns and custom task grouping, see [Working with Datasets](/api-reference/ai-task-builder/datasets).
  </Step>

  <Step>
    ## Create a Batch

    Batches bind datasets + instructions into something you can attach to a Prolific study.

    You can also include task details here with introductions and steps.
    `task_introduction` and `task_steps` fields support basic HTML.

    <RunnableEndpoint endpoint="POST /api/v1/data-collection/batches" example="task_builder_starter_batch_create" readonly={["examples"]} />

    (**Note:** `dataset_id` is optional at creation time and can be added later via update, but must be provided before setup.)

    Save the returned `id` as `BATCH_ID`.
  </Step>

  <Steps>
    <Step>
      ### Update a Batch (optional)

      You can update a batch's name, task details, or associated dataset after creation.

      <RunnableEndpoint endpoint="PATCH /api/v1/data-collection/batches/{batch_id}" example="task_builder_starter_batch_update" readonly={["examples"]} />

      All fields are optional - include only what you want to update.
    </Step>

    <Step>
      ### Duplicate a Batch (optional)

      You can create a copy of an existing batch, either with or without its dataset.

      #### Duplicate with the same dataset (dataset is shared, not copied)

      ```bash
      curl -X POST https://api.prolific.com/api/v1/data-collection/batches/BATCH_ID/duplicate \
        -H "Authorization: Token YOUR_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Copy of My Batch"
        }'
      ```

      #### Duplicate without a dataset (requires new upload)

      ```bash
      curl -X POST https://api.prolific.com/api/v1/data-collection/batches/BATCH_ID/duplicate \
        -H "Authorization: Token YOUR_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "Copy of My Batch",
          "upload_new_dataset": true
        }'
      ```

      If `name` is omitted, the duplicate will be named `[Original Batch Name] (Copy)`.

      **Note:** When duplicating with a dataset, both batches will reference the same dataset - it is not duplicated.
    </Step>
  </Steps>

  <Step>
    ## Add Instructions to the Batch

    You can create **multiple** instructions. Types supported:

    * `multiple_choice` — selection from options (use `answer_limit` for single or multi-select)
    * `free_text` — open-ended text input
    * `multiple_choice_with_free_text` — selection with associated free text fields
    * `file_upload` — file submission

    For full schema details, see [Instructions](/api-reference/ai-task-builder/instructions).

    <RunnableEndpoint endpoint="POST /api/v1/data-collection/batches/{batch_id}/instructions" example="task_builder_starter_batch_instructions" readonly={["examples"]} />

    (You can later **PUT** the same endpoint to update instructions -
    please include the complete payload as it will replace all instructions on the batch, or **GET** it to read them back.)
  </Step>

  <Step>
    ## Set Up the Batch (build tasks, set tasks per participant)

    Configure how datapoints become tasks and how many tasks each participant gets.

    <RunnableEndpoint endpoint="POST /api/v1/data-collection/batches/{batch_id}/setup" example="task_builder_starter_batch_setup" readonly={["examples"]} />

    **Note:** The dataset must be in `READY` status before running the setup endpoint.

    Now **poll batch status** until it's **READY**:

    <RunnableEndpoint endpoint="GET /api/v1/data-collection/batches/{batch_id}" readonly={["examples"]} />

    ```bash
    {"status":"READY"} # (possible values: UNINITIALISED|PROCESSING|READY|ERROR)
    ```
  </Step>

  <Step>
    ## Create a Prolific Study that References the Batch

    When the batch is **READY**, create a standard study but include these two fields:

    * `"data_collection_method": "AI_TASK_BUILDER_BATCH"`
    * `"data_collection_id": "BATCH_ID"`

    <RunnableEndpoint endpoint="POST /api/v1/studies/" example="task_builder_starter_study" readonly={["examples"]} />
  </Step>

  <Step>
    ## Publish the Study

    <RunnableEndpoint endpoint="POST /api/v1/studies/{id}/transition/" example="publish_study" readonly={["examples"]} />

    (Other actions available include `PAUSE`, `START` (resume), and `STOP`.)
  </Step>

  <Step>
    ## Retrieve Annotated Responses

    There are two ways to retrieve responses once participants have completed their tasks.

    ### Option 1: JSON responses

    Get individual responses as JSON, useful for processing programmatically or streaming results as they come in.

    <RunnableEndpoint endpoint="GET /api/v1/data-collection/batches/{batch_id}/responses" readonly={["examples"]} />

    ```json
    {
      "results": [
        {
          "id": "01997d0c-34ab-748a-b6e3-104288f7a1bf",
          "batch_id": "01997d05-8689-72a8-b980-3f930729f28a",
          "participant_id": "6862a1a367ad476b8601fa2a",
          "submission_id": "68d43c57a56e9439d5d1e93e",
          "task_id": "84cc7c99-9097-5c0f-8052-65382273ace5",
          "response": {
            "instruction_id": "01997d05-8f20-734f-ad19-c82e279b5118",
            "type": "free_text",
            "answer": [
              { "value": "abc" }
            ]
          },
          "created_at": "2025-09-24T18:46:15.979Z"
        }
      ],
      "meta": {
        "count": 1
      }
    }
    ```

    ### Option 2: CSV report

    Download a CSV report containing your original data with response columns appended.

    <RunnableEndpoint endpoint="GET /api/v1/data-collection/batches/{batch_id}/report/" readonly={["examples"]} />

    This returns a presigned URL to download the CSV:

    ```json
    {
      "url": "https://...",
      "expires_at": "2025-01-20T10:17:34.949Z",
      "http_method": "GET"
    }
    ```

    Use the `url` to download your annotated dataset.
  </Step>
</Steps>

# Operational Notes & Tips

* **Statuses**: Datasets and Batches both progress through `UNINITIALISED → PROCESSING → READY` (or `ERROR`).
  Don't attach a batch to a study until it's `READY`.
* **Instructions**: You can mix multiple instruction types within the same batch
  (e.g., two `multiple_choice` plus one `free_text`).
* **`tasks_per_group`**: Controls how many tasks a single participant receives in one "sitting"
  (this is what will be classed as a single Submission on Prolific).
  Increase to reduce study overhead and per-task price dispersion; decrease if tasks are long.
* **Targeting & Reward**: As with any Prolific study, all participants share the same targeting and reward.
* Once a batch has been set up (step 6) you can no longer edit its instructions.
* **Dataset Requirements**: Datasets do not need to be in READY status when creating, updating, or duplicating batches.
  However, the dataset **must** be in READY status before running the setup endpoint.
* **Batch Duplication**: When duplicating a batch with a dataset, the dataset is shared between both batches, not duplicated.
  If you need separate datasets, use `upload_new_dataset: true`.