---
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}`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/people_batches/{people_batch_uuid}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/people_batches/:people_batch_uuid/get.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)