---
title: "Create a bulk report batch"
method: POST
path: "/v1/bulk_reports"
tags: ["Reports"]
---

# Create a bulk report batch

`POST /v1/bulk_reports`

Triggers asynchronous generation of up to 25 reports across companies the partner is mapped to. Each `batch` item is a `custom_report` (same parameters as [create a custom report](https://docs.gusto.com/embedded-payroll/reference/post-companies-company_uuid-reports)) or a `general_ledger` report (same parameters as [create a general ledger report](https://docs.gusto.com/embedded-payroll/reference/post-payrolls-payroll_uuid-reports-general_ledger)), keyed by `company_uuid` and `report_type`. Items are validated synchronously; if any is invalid, the entire batch is rejected.

Poll the [bulk report GET endpoint](https://docs.gusto.com/embedded-payroll/reference/get-v1-bulk_reports-request_uuid) with the returned `uuid` for status and the report URL, which is valid for 10 minutes.

📘 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:write`

## Headers

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

## Request body

- BulkReportBody — Each `batch` item is a `custom_report` or a `general_ledger` report.
  - `batch` BulkReportItem[], required — One report per item. Up to 25 items per batch, across any combination of companies the partner is mapped to.
    - union — A single report inside a bulk batch. Required fields depend on `report_type`: `custom_report` requires `columns` and `file_type`; `general_ledger` requires `payroll_uuid` and `aggregation`.
      - object — A custom report entry in a bulk batch.
        - `company_uuid` string, uuid, required — UUID of the company to generate the report for. The partner must be mapped to this company.
        - `report_type` 'custom_report', required — Identifies this batch item as a custom report.
        - `columns` string[], required — Columns to include in the report.
        - `groupings` string[] — How to group the report. If omitted, defaults are derived from the requested `columns`.
        - `file_type` 'csv' | 'json' | 'pdf', required — The type of file to generate.
        - `custom_name` string — Display name for the report.
        - `with_totals` boolean — Whether to include subtotals and grand totals.
        - `date_filter_type` 'period_end_date' | 'period_start_date' | 'check_date' — Which payroll date `start_date` and `end_date` filter against.
        - `start_date` string, date — Start date of data to filter by.
        - `end_date` string, date — End date of data to filter by.
        - `payment_method` 'check' | 'direct_deposit' — Payment method to filter by.
        - `employment_type` 'exempt' | 'salaried_nonexempt' | 'nonexempt' | 'commission_only_exempt' | 'commission_only_nonexempt' — Employee employment type to filter by.
        - `employment_status` 'active_full_time' | 'active_part_time' | 'active_part_time_eligible' | 'active_variable' | 'active_seasonal' | 'active' | 'dismissed' — Employee employment status to filter by.
        - `employee_uuids` string[], nullable — Employees to filter by.
        - `department_uuids` string[] — Departments to filter by.
        - `work_address_uuids` string[] — Work addresses to filter by.
      - object — A general ledger report entry in a bulk batch.
        - `company_uuid` string, uuid, required — UUID of the company to generate the report for. The partner must be mapped to this company.
        - `report_type` 'general_ledger', required — Identifies this batch item as a general ledger report.
        - `payroll_uuid` string, uuid, required — The UUID of the payroll to generate the general ledger for.
        - `aggregation` 'default' | 'job' | 'department' | 'integration', required — The breakdown of the report. Use `default` for no split.
        - `integration_type` string, nullable — The kind of integration set up for the company. Required when `aggregation` is `integration`; must be null otherwise.

## Response `201`

Created

- CreateBulkReport
  - `uuid` string, uuid, required — Unique identifier of the bulk report batch.
  - `status` 'pending' | 'processing' | 'completed' | 'failed', required — The batch's processing state. - `pending`: accepted, not yet started - `processing`: reports are being generated - `completed`: all reports finished - `failed`: the batch failed before completing

## Other responses

- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

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