---
title: "Read a batch that a send made, with its print requests"
method: GET
path: "/v1/print-jobs/batches/{batchId}/requests"
tags: ["Print Jobs"]
---

# Read a batch that a send made, with its print requests

`GET /v1/print-jobs/batches/{batchId}/requests`

## Request

- Base URL: `https://api.printhiv3d.com`
- URL: `https://api.printhiv3d.com/v1/print-jobs/batches/{batchId}/requests`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/printhiv3d/apis/hive-api-documentation/docs/v1/print-jobs/batches/:batchId/requests/get.ts> (a function with typed inputs; its response is checked against the schema)

The batch status comes from its requests and their jobs. Requests are oldest first. A batch that no send made is 404.

## Path parameters

- `batchId` string, required

## Response `200`

Default Response

- object
  - `batchId` string, uuid, required
  - `name` string, required
  - `status` 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'PARTIAL' | 'CANCELLED', required
  - `schedulingHeld` boolean, required
  - `closed` boolean, required
  - `createdAt` string, required
  - `source` object, nullable, required
    - `sourceVersionId` string, uuid, nullable, required
    - `filename` string, nullable, required
    - `modelFileId` string, nullable, required
    - `sentAt` string, required
  - `requests` object[], required
    - `requestId` string, uuid, required
    - `status` 'preparing' | 'held' | 'created' | 'failed' | 'cancelled', required
    - `externalId` string, nullable, required
    - `createdAt` string, required
    - `plate` integer, nullable
    - `printerId` string, uuid, nullable
    - `name` string, nullable
    - `sourceVersionId` string, uuid, nullable
    - `job` object, nullable, required
      - `id` number, required
      - `status` string, required
      - `model_file_id` string, uuid, nullable, required
      - `printer_id` string, uuid, nullable, required
      - `load_actions` object[], nullable: What is still to load for the assigned printer, recomputed on each read from its current filament state and the same planner as POST /v1/print-jobs/plan: load and swap actions only, in source slot order. An empty array means nothing to load, including an unassigned or finished job. Null means the actions could not be computed or the job changed during the read, so read again.
        - `actionId` string, required
        - `sourceSlot` integer, required
        - `kind` 'load' | 'swap' | 'already_loaded', required
        - `filament` object, required
          - `filamentId` string, uuid
          - `brand` string, nullable
          - `name` string
          - `colorName` string, nullable
          - `material` string, required
          - `colorHex` string, nullable, required
        - `bay` object, required
          - `id` string, required
          - `unitLabel` string, required
          - `label` string, required
          - `ams_id` integer
          - `slot_id` integer
        - `current` object
          - `material` string, nullable, required
          - `colorHex` string, nullable, required
        - `text` string, required
      - `print_options` object, nullable, required
        - `filament_route_state` 'waiting' | 'resolved'
        - `filament_warnings` string[]
        - `filament_waiting_reasons` object[]
          - `filamentId` string, uuid
          - `brand` string, nullable
          - `name` string
          - `colorName` string, nullable
          - `material` string
          - `colorHex` string
          - `code` 'filament_not_loaded' | 'material_route_changed', required
          - `sourceSlot` integer
          - `color` string, nullable
          - `message` string
          - `messageKind` 'requirement' | 'instruction'
          - `match` union
            - object
              - …
            - object
              - …
            - object
              - …
          - `cause` 'slot_empty' | 'missing_material' | 'color_distance' | 'slot_conflict' | 'reported_material_mismatch' | 'material_type_mismatch' | 'material_unassigned'
          - `suggestedTargetSlot` object
            - `ams_id` integer, required
            - `slot_id` integer, required
    - `requiredActions` union[], required
      - union
        - object
          - `item` integer, required
          - `plateNumber` integer, required
          - `hold` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - object
          - `code` string, required
    - `warnings` object[]
      - `code` string, required
    - `error` object, nullable, required
    - `batchId` string, uuid, nullable
    - `attempt` integer
    - `retryOf` string, uuid, nullable
    - `retriedBy` string, uuid, nullable
    - `superseded` boolean
    - `variants` object[]
      - `targetModelId` string, required
      - `targetNozzleMm` number, required
      - `fit` string, required
      - `status` 'preparing' | 'ready' | 'held' | 'failed' | 'cancelled' | 'discarded', required
      - `representativePrinterId` string, uuid, nullable, required
      - `bound` boolean, required
      - `warnings` object[]
        - `code` string, required
      - `holds` object[]
      - `failure` object, nullable
        - `code` string
        - `sliceCode` string
        - `message` string
    - `filaments` object[]
      - `filamentId` string, uuid
      - `brand` string, nullable
      - `name` string
      - `colorName` string, nullable
      - `material` string
      - `colorHex` string
      - `sourceSlot` integer, required
    - `estimatedSeconds` integer, nullable
    - `createdJobId` integer, nullable
    - `modelFileId` string, uuid, nullable

## Other responses

- `404`: Default Response

## Changes

- **2026-11-11** `f440fad63ce0`: 4 info
  - added the optional property `requests/items/createdJobId` to the response with the `200` status
  - added the optional property `requests/items/estimatedSeconds` to the response with the `200` status
  - added the optional property `requests/items/filaments` to the response with the `200` status
  - added the optional property `requests/items/modelFileId` to the response with the `200` status
- **2026-11-10** `09f2403145b5`: 1 info
  - api operation id `getPrintJobBatch` was added
- **2026-11-10** `86492c6abdea`: 1 breaking, 3 warning, 4 info
  - the response property `requests/items/job/print_options/filament_waiting_reasons/items/color` became nullable for the status `200`
  - added the new `material_type_mismatch` enum value to the `requests/items/job/print_options/filament_waiting_reasons/items/cause` response property for the response status `200`
  - added the new `material_unassigned` enum value to the `requests/items/job/print_options/filament_waiting_reasons/items/cause` response property for the response status `200`
  - added the new `reported_material_mismatch` enum value to the `requests/items/job/print_options/filament_waiting_reasons/items/cause` response property for the response status `200`
  - …4 more
- **2026-11-10** `12865bb46cca`: 1 info
  - added the optional property `requests/items/variants` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/changes/v1/print-jobs/batches/:batchId/requests/get.md)

---

[API](https://skmtc.dev/printhiv3d/apis/hive-api-documentation.md) - [All operations](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/printhiv3d/apis/hive-api-documentation/revisions/35a7515c29d5?raw)