---
title: "Get a people batch"
method: GET
path: "/v1/people_batches/{people_batch_uuid}"
tags: ["People Batches"]
---

# Get a people batch

`GET /v1/people_batches/{people_batch_uuid}`

Returns the status and results of a people batch.

Poll this endpoint to check the batch processing status and retrieve results.

scope: `people_batches:read`

## Path parameters

- `people_batch_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Response `200`

successful

- PeopleBatchResults — A people batch with processing results.
  - `uuid` string, uuid, required — The unique identifier of the people batch.
  - `idempotency_key` string, uuid, required — The idempotency key provided when creating the batch.
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'partial_success', required — The current status of the batch processing.
  - `submitted_at` string, date-time — The timestamp when the batch was submitted.
  - `completed_at` string, date-time, nullable — The timestamp when the batch processing completed.
  - `submitted_items` integer, nullable — The number of items submitted in the batch.
  - `processed_items` integer — The number of items successfully processed.
  - `excluded_items` integer — The number of items excluded from processing.
  - `results` object[] — The results for each batch item.
    - `external_id` string — The external ID provided in the batch request.
    - `role` 'employee' — The type of person created.
    - `status` 'success' | 'partial_success' | 'failed' — The status of this batch item.
    - `idx` integer — The index of this item in the original batch request.
    - `uuid` string, uuid — The UUID of the created person.
    - `employee_uuid` string, uuid — The UUID of the created employee (if role is employee).
    - `errors` object[], nullable — Errors encountered while processing this batch item.
      - `error_key` string — The key identifying the error source.
      - `category` string — The error category.
      - `message` string, nullable — Human-readable error message.
      - `errors` object[], nullable — Nested errors for sub-operations.
  - `exclusions` object[], nullable — Items excluded from processing due to validation errors.
    - `external_id` string — The external ID of the excluded item(s).
    - `category` string — The exclusion category.
    - `message` string — Human-readable explanation for exclusion.
    - `item_count` integer — Number of items affected by this exclusion.

## Other responses

- `404` — Not Found

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)