---
title: "Get a payroll cancellation batch"
method: GET
path: "/v1/payroll_batches/{payroll_batch_uuid}"
tags: ["Payroll Cancellations"]
---

# Get a payroll cancellation batch

`GET /v1/payroll_batches/{payroll_batch_uuid}`

Returns the status and per-payroll results of a payroll cancellation batch.

Poll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the response includes the `results` array (one entry per authorized payroll, each with its own per-payroll `status` — `success` or `failed`) and the `exclusions` array (one entry per payroll that could not be processed). A cancel is atomic, so a per-payroll result is only ever `success` or `failed` — never `partial_success`.

Note that the top-level batch `status` (`pending` / `processing` / `completed` / `failed`) is the request lifecycle, distinct from the per-payroll `status` inside `results[]`. A `completed` batch does not imply every payroll was cancelled — inspect the array for per-payroll outcomes.

Results are stored in Redis with a limited TTL after completion. If the partner polls after results have expired, this endpoint returns 410 Gone — partners should re-submit a new batch.

📘 System Access Authentication

This endpoint uses the [Bearer Auth scheme with the system-level access token in the HTTP Authorization header](https://docs.gusto.com/embedded-payroll/docs/system-access)

scope: `payroll_batches:read`

## Path parameters

- `payroll_batch_uuid` string, required

## Headers

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

## Response `200`

successful

- PayrollBatchResults — A payroll cancellation batch with per-payroll results.
  - `uuid` string, uuid, required — The unique identifier of the payroll cancellation batch.
  - `idempotency_key` string, uuid, required — The idempotency key provided when creating the batch.
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — The lifecycle status of the batch request itself. Terminal values are `completed` (processing finished — inspect `results` and `exclusions` for per-payroll outcomes) and `failed` (the batch crashed at the system level; can be retried). This is distinct from the per-payroll `status` returned inside `results[]`. A `completed` batch does not imply every payroll was cancelled.
  - `submitted_at` string, date-time, required — 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 payrolls submitted in the batch.
  - `processed_items` integer — The number of payrolls processed (cancelled or attempted). Only present once the batch reaches a terminal status.
  - `excluded_items` integer — The number of payrolls excluded from processing. Only present once the batch reaches a terminal status.
  - `results` object[] — Per-payroll cancellation results. Only present once the batch reaches a terminal status. One entry per authorized payroll.
    - `idx` integer — The index of this payroll in the original POST batch array.
    - `uuid` string, uuid — The UUID of the payroll.
    - `status` 'success' | 'failed' — The outcome of cancelling this payroll. A cancel is atomic — there is no per-payroll `partial_success`. - `success`: the payroll was cancelled, or required no action (already cancelled / never run) - `failed`: the payroll could not be cancelled; see `errors`
    - `errors` object[] — Present only when `status` is `failed`. A cancel is a single atomic operation, so this is a flat array with exactly one error.
      - `error_key` string — The key identifying the error source.
      - `category` 'not_cancellable' | 'internal_error' — Machine-readable reason the cancellation failed. - `not_cancellable`: the payroll is past the point where it can be cancelled - `internal_error`: an unexpected error occurred; the request can be retried
      - `message` string — Human-readable explanation of the failure.
  - `exclusions` object[] — Payrolls that could not be processed, determined at submission time. Only present once the batch reaches a terminal status. Every UUID submitted in the POST batch appears in exactly one of `results` or `exclusions`.
    - `idx` integer — The index of this payroll in the original POST batch array.
    - `entity_type` 'payroll' — The type of entity this exclusion represents.
    - `uuid` string, uuid — The UUID of the excluded payroll.
    - `company_uuid` string, uuid — The UUID of the company asserted to own the payroll.
    - `status` 'failed' — Always `failed` for an excluded payroll.
    - `category` 'not_found' | 'duplicate_operation' — Machine-readable category for why the payroll was excluded. - `not_found`: the payroll does not exist, or is not associated with a company the partner is mapped to - `duplicate_operation`: the same payroll UUID appeared more than once in the request; only the first occurrence is processed
    - `message` string — Human-readable explanation for the exclusion.

## Other responses

- `404` — Not Found
- `410` — Gone - results have expired from Redis

---

[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)