v1

latestOpenAPI 3.1.02026-07-243113441.2 MB

Reports

Get a bulk report batch

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

scope: company_reports:read

get/v1/bulk_reports/{request_uuid}

Path parameters

request_uuidstring required

The UUID of the bulk report batch.

Headers

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

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Response

uuidstring 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_atstring date-time required

When the batch was accepted.

completed_atstring date-time nullable required

When the batch reached a terminal state. Null while non-terminal.

submitted_itemsinteger required

How many reports the partner asked for in this batch.

partner_uuidstring uuid

UUID of the partner that owns this batch. Returned only once the batch has finished; omitted while in progress.

processed_itemsinteger

How many reports succeeded. Returned only once the batch has finished; omitted while in progress.

report_urlstring 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.