---
title: "Create a report run"
method: POST
path: "/report_runs"
---

# Create a report run

`POST /report_runs`

## Request

- Base URL: `https://sandbox.checkhq.com`
- URL: `https://sandbox.checkhq.com/report_runs`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/checkhq/apis/check-api/docs/report_runs/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a report run. Poll `GET /report_runs/{id}` or listen for `report_run` webhooks until `status` is `completed` or `failed`. When completed, download the file from `result.url`. Report generation may take up to 20 minutes. Data that report runs rely on may be up to 10 minutes out of date. Create requests are rate limited to 1 per second per partner, with a maximum of 20 report runs generating at once.

## Headers

- `X-Idempotency-Key` string

## Request body

- object
  - `report` 'payroll_journal' | 'payroll_summary', required: Report to generate. One of `payroll_journal` or `payroll_summary`.
  - `company` string: Company ID to scope the report.
  - `parameters` object, required: Parameters for the selected report. Required fields depend on the report type.
    - `payday_from` string, date: Inclusive start of the payday range (YYYY-MM-DD).
    - `payday_to` string, date: Inclusive end of the payday range (YYYY-MM-DD).
    - `additional_columns` string[]: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
    - `payroll` string: Optional payroll ID to scope the report to a single payroll.
    - `group_by` 'workplace': Payroll journal only. When set to `workplace`, groups rows by workplace.
    - `contractors` boolean: Include contractor payments.
    - `taxable_wages` boolean: Include taxable wage columns.
    - `gross_taxable_wages` boolean: Include gross taxable wage columns.
  - `metadata` object: Additional loosely structured information to associate with the report run.

## Response `200`

200

- object
  - `id` string: Report run ID.
  - `report` 'payroll_journal' | 'payroll_summary': Report to generate. One of `payroll_journal` or `payroll_summary`.
  - `status` 'generating' | 'completed' | 'failed': One of `generating`, `completed`, or `failed`. New report runs start as `generating`.
  - `company` string, nullable: Company ID to scope the report. Required for some report types.
  - `created_at` string, date-time: When the report run was created.
  - `completed_at` string, date-time, nullable: When the report run finished successfully or failed.
  - `parameters` object: Parameters for the selected report. Required fields depend on the report type.
    - `payday_from` string, date: Inclusive start of the payday range (YYYY-MM-DD).
    - `payday_to` string, date: Inclusive end of the payday range (YYYY-MM-DD).
    - `additional_columns` string[]: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
    - `payroll` string: Optional payroll ID to scope the report to a single payroll.
    - `group_by` 'workplace': Payroll journal only. When set to `workplace`, groups rows by workplace.
    - `contractors` boolean: Include contractor payments.
    - `taxable_wages` boolean: Include taxable wage columns.
    - `gross_taxable_wages` boolean: Include gross taxable wage columns.
  - `result` object, nullable: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived.
    - `url` string: URL that returns a short-lived download for the generated report file.
  - `metadata` object: Additional loosely structured information associated with the report run.

## Changes

- **2026-11-03** `5a54f5eb888b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/checkhq/apis/check-api/changes/report_runs/post.md)

---

[API](https://skmtc.dev/checkhq/apis/check-api.md) - [All operations](https://skmtc.dev/checkhq/apis/check-api/llms.txt) - [OpenAPI document](https://skmtc.dev/checkhq/apis/check-api/revisions/5a54f5eb888b?raw)