---
title: "Get a bulk report batch"
method: GET
path: "/v1/bulk_reports/{request_uuid}"
tags: ["Reports"]
---

# Get a bulk report batch

`GET /v1/bulk_reports/{request_uuid}`

Get a bulk report batch's status and results given the `request_uuid`. While in progress, only batch metadata is returned; once complete, it also includes a signed `report_url` (a zip of all generated reports, valid for 10 minutes) and a per-company breakdown.

Reports containing PHI are inaccessible with `company_reports:read:tier_2_only` data scope.

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

## Path parameters

- `request_uuid` string, required

## Headers

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

## Response `200`

OK

- BulkReport
  - `uuid` string, uuid, required — Unique identifier of the bulk report batch.
  - `status` 'pending' | 'processing' | 'success' | 'partial_success' | 'failed', required — Overall batch status. `pending`/`processing` while in progress; once finished, `success` (all reports succeeded), `partial_success` (some succeeded, some failed), or `failed` (none succeeded).
  - `submitted_at` string, date-time, required — When the batch was accepted.
  - `completed_at` string, date-time, nullable, required — When the batch reached a terminal state. Null while non-terminal.
  - `submitted_items` integer, required — How many reports the partner asked for in this batch.
  - `partner_uuid` string, uuid — UUID of the partner that owns this batch. Returned only once the batch has finished; omitted while in progress.
  - `processed_items` integer — How many reports succeeded. Returned only once the batch has finished; omitted while in progress.
  - `report_url` string, nullable — Signed S3 URL to a zip containing every successfully-generated report, valid for 10 minutes. Returned only once the batch has finished; omitted while in progress.
  - `companies` BulkReportCompany[] — Per-company breakdown. Returned only once the batch has finished; omitted while in progress.
    - `company_uuid` string, uuid, required — UUID of the company.
    - `status` 'pending' | 'success' | 'partial_success' | 'failed', required — This company's overall status across its `reports`: - `success`: every report succeeded - `partial_success`: some succeeded, some failed - `failed`: every report failed - `pending`: at least one report is still being generated
    - `reports` BulkReportItemResult[], required
      - `report_type` 'custom_report' | 'general_ledger', required — Which report this entry refers to.
      - `file_type` string, required — The report's output file type.
      - `status` 'pending' | 'success' | 'failed', required — The terminal state for this individual report.
      - `error` string, nullable, required — A user-facing error message when status is `failed`. Null on success.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.

---

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