---
title: "List report runs"
method: GET
path: "/report_runs"
---

# List report runs

`GET /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/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns a list of report runs for the authenticated partner, newest first. Expired report runs are omitted.

## Query parameters

- `company` string
- `report_type` 'payroll_journal' | 'payroll_summary'
- `status` 'generating' | 'completed' | 'failed'
- `limit` integer

## Response `200`

200

- object
  - `next` string, nullable
  - `previous` string, nullable
  - `results` 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/get.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)