---
title: "Get a payroll digest batch"
method: GET
path: "/v1/payroll_digests/{payroll_digest_uuid}"
tags: ["Payroll Digests"]
---

# Get a payroll digest batch

`GET /v1/payroll_digests/{payroll_digest_uuid}`

Returns the status and results of a payroll digest batch.

Poll this endpoint until the batch `status` reaches a terminal value (`completed` or `failed`). Once terminal, the response includes the full `results` array (one entry per attempted company, each with its own per-company `status` — `success`, `partial_success`, or `failed`) and the `exclusions` array (one entry per company that could not be looked up or processed).

Note that the top-level batch `status` (`pending` / `processing` / `completed` / `failed`) is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`. A `completed` batch does not imply every company succeeded — inspect the arrays for per-company outcomes.

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

📘 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_digests:read`

## Path parameters

- `payroll_digest_uuid` string, required

## Headers

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

## Response `200`

successful

- PayrollDigestResults — A payroll digest batch with processing results.
  - `uuid` string, uuid, required — The unique identifier of the payroll digest 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-company outcomes) and `failed` (request failed; can be retried). This is distinct from the per-company `status` returned inside `results[]` and `exclusions[]`.
  - `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 companies submitted in the batch.
  - `processed_items` integer — The number of companies successfully processed. Only present once the batch reaches a terminal status.
  - `excluded_items` integer — The number of companies excluded from processing. Only present once the batch reaches a terminal status.
  - `results` object[] — Per-company results. Only present once the batch reaches a terminal status. Includes successfully processed companies (with their `payrolls` array, which may be empty when the company has no payrolls in the date window).
    - `idx` integer — The index of this company in the original POST batch array.
    - `entity_type` 'company' — The type of entity this result represents.
    - `uuid` string, uuid — The UUID of the company.
    - `name` string — The legal/display name of the company.
    - `status` 'success' | 'partial_success' | 'failed' — The status of this company's digest computation.
    - `blockers` object[] — Reasons the company cannot currently run payroll. Applies to every payroll in this company's `payrolls` array — blockers are evaluated at the company level, not per payroll. Empty when there are no blockers.
      - `type` string — A machine-readable blocker key (e.g. `missing_bank_account`).
      - `description` string — Human-readable description of the blocker.
    - `payrolls` object[] — Payrolls for this company within the digest date window (7 days past, 30–60 days future). May be empty.
      - `payroll_uuid` string, uuid, nullable — UUID of the payroll. `null` for upcoming pay periods that have not been started yet (the `payrolls` API has not yet created a payroll record). Once a payroll is created, subsequent digest requests will include the real `payroll_uuid`.
      - `payroll_type` string — The type of payroll (e.g. `regular`, `new_hire`, `termination`, `transition`, `bonus`, `correction`).
      - `display_title` string — Partner-facing display title for this payroll (e.g. "Run biweekly payroll").
      - `auto_payroll` boolean — Whether the company has auto-payroll enabled for this pay schedule.
      - `status` string — The lifecycle status of the payroll (e.g. `ready_to_start`, `in_progress`, `submitted`, `completed`, `failed`).
      - `pay_period` object
        - `start_date` string, date, nullable — First day of the pay period.
        - `end_date` string, date, nullable — Last day of the pay period.
        - `check_date` string, date, nullable — The date employees get paid.
        - `run_payroll_by` string, date, nullable — The deadline to run payroll for this pay period.
      - `pay_schedule` object, nullable
        - `uuid` string, uuid — UUID of the pay schedule.
        - `frequency` string — Human-friendly pay frequency (e.g. "Every other week").
        - `custom_name` string, nullable — Custom name for the pay schedule, when set.
      - `totals` object, nullable — Pay totals. `null` when the payroll has not been calculated, or when the calculation is stale (the partner edited hours/earnings after the last calculation).
        - `total_debit_amount` string — Total amount debited from the company bank account (string-formatted decimal).
        - `net_pay` string — Total net pay across all employees on this payroll (string-formatted decimal).
        - `total_employer_cost` string — Total employer cost including taxes and benefits (string-formatted decimal).
  - `exclusions` object[] — Companies that could not be processed. 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 company in the original POST batch array.
    - `entity_type` 'company' — The type of entity this exclusion represents.
    - `uuid` string, uuid — The UUID of the excluded company.
    - `status` 'failed' — The status of this company's digest computation.
    - `category` 'not_found' | 'company_inactive' | 'duplicate' | 'internal_error' — Machine-readable category for why the company was excluded.
    - `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)