Check Report Runs API
The Report Runs API from Check — 3 operation(s) for report runs.
The Report Runs API from Check — 3 operation(s) for report runs.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/check-hq:check-hq-report-runs-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: check-api Report Runs API
version: '2025-01-01'
servers:
- url: https://sandbox.checkhq.com
security:
- sec0: []
tags:
- name: Report Runs
paths:
/report_runs:
post:
summary: Create a report run
description: 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.
operationId: create-a-report-run
requestBody:
content:
application/json:
schema:
type: object
required:
- report
- parameters
properties:
report:
type: string
description: Report to generate. One of `payroll_journal` or `payroll_summary`.
enum:
- payroll_journal
- payroll_summary
company:
type: string
description: Company ID to scope the report.
parameters:
type: object
description: Parameters for the selected report. Required fields depend on the report type.
properties:
payday_from:
type: string
format: date
description: Inclusive start of the payday range (YYYY-MM-DD).
payday_to:
type: string
format: date
description: Inclusive end of the payday range (YYYY-MM-DD).
additional_columns:
type: array
description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
items:
type: string
payroll:
type: string
description: Optional payroll ID to scope the report to a single payroll.
group_by:
type: string
description: Payroll journal only. When set to `workplace`, groups rows by workplace.
enum:
- workplace
contractors:
type: boolean
description: Include contractor payments.
default: false
taxable_wages:
type: boolean
description: Include taxable wage columns.
default: false
gross_taxable_wages:
type: boolean
description: Include gross taxable wage columns.
default: false
metadata:
type: object
description: Additional loosely structured information to associate with the report run.
additionalProperties: true
examples:
Payroll journal:
value:
report: payroll_journal
company: com_MkBYRtUviD6kYO0b85H8
parameters:
payday_from: '2025-01-01'
payday_to: '2025-03-31'
additional_columns:
- employee.id
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"generating\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": null,\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": null,\n \"metadata\": {}\n}"
schema:
type: object
properties:
id:
type: string
description: Report run ID.
example: run_w4wDuqfuSqpMrSXbERrL
report:
type: string
description: Report to generate. One of `payroll_journal` or `payroll_summary`.
enum:
- payroll_journal
- payroll_summary
example: payroll_journal
status:
type: string
description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`.
enum:
- generating
- completed
- failed
example: generating
company:
type: string
nullable: true
description: Company ID to scope the report. Required for some report types.
example: com_MkBYRtUviD6kYO0b85H8
created_at:
type: string
format: date-time
description: When the report run was created.
completed_at:
type: string
format: date-time
nullable: true
description: When the report run finished successfully or failed.
parameters:
type: object
description: Parameters for the selected report. Required fields depend on the report type.
properties:
payday_from:
type: string
format: date
description: Inclusive start of the payday range (YYYY-MM-DD).
payday_to:
type: string
format: date
description: Inclusive end of the payday range (YYYY-MM-DD).
additional_columns:
type: array
description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
items:
type: string
payroll:
type: string
description: Optional payroll ID to scope the report to a single payroll.
group_by:
type: string
description: Payroll journal only. When set to `workplace`, groups rows by workplace.
enum:
- workplace
contractors:
type: boolean
description: Include contractor payments.
default: false
taxable_wages:
type: boolean
description: Include taxable wage columns.
default: false
gross_taxable_wages:
type: boolean
description: Include gross taxable wage columns.
default: false
result:
type: object
nullable: true
description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived.
properties:
url:
type: string
description: URL that returns a short-lived download for the generated report file.
metadata:
type: object
description: Additional loosely structured information associated with the report run.
additionalProperties: true
deprecated: false
parameters:
- name: X-Idempotency-Key
in: header
description: Optional idempotency key. Replays the first response when the same key is reused.
schema:
type: string
tags:
- Report Runs
get:
summary: List report runs
description: Returns a list of report runs for the authenticated partner, newest first. Expired report runs are omitted.
operationId: list-report-runs
parameters:
- name: company
in: query
description: Return report runs for this company ID.
schema:
type: string
- name: report_type
in: query
description: Return report runs of this report type. One of `payroll_journal` or `payroll_summary`.
schema:
type: string
enum:
- payroll_journal
- payroll_summary
- name: status
in: query
description: Return report runs in this status. One of `generating`, `completed`, or `failed`.
schema:
type: string
enum:
- generating
- completed
- failed
- name: limit
in: query
description: Number of report runs returned per page. The maximum value is 100.
schema:
type: integer
format: int32
default: 25
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"next\": null,\n \"previous\": null,\n \"results\": [\n {\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"completed\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": \"2024-11-03T19:55:11Z\",\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": {\n \"url\": \"https://sandbox.checkhq.com/report_runs/run_w4wDuqfuSqpMrSXbERrL/download\"\n },\n \"metadata\": {}\n },\n {\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"generating\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": null,\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": null,\n \"metadata\": {}\n }\n ]\n}"
schema:
type: object
properties:
next:
type: string
nullable: true
previous:
type: string
nullable: true
results:
type: array
items:
type: object
properties:
id:
type: string
description: Report run ID.
example: run_w4wDuqfuSqpMrSXbERrL
report:
type: string
description: Report to generate. One of `payroll_journal` or `payroll_summary`.
enum:
- payroll_journal
- payroll_summary
example: payroll_journal
status:
type: string
description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`.
enum:
- generating
- completed
- failed
example: generating
company:
type: string
nullable: true
description: Company ID to scope the report. Required for some report types.
example: com_MkBYRtUviD6kYO0b85H8
created_at:
type: string
format: date-time
description: When the report run was created.
completed_at:
type: string
format: date-time
nullable: true
description: When the report run finished successfully or failed.
parameters:
type: object
description: Parameters for the selected report. Required fields depend on the report type.
properties:
payday_from:
type: string
format: date
description: Inclusive start of the payday range (YYYY-MM-DD).
payday_to:
type: string
format: date
description: Inclusive end of the payday range (YYYY-MM-DD).
additional_columns:
type: array
description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
items:
type: string
payroll:
type: string
description: Optional payroll ID to scope the report to a single payroll.
group_by:
type: string
description: Payroll journal only. When set to `workplace`, groups rows by workplace.
enum:
- workplace
contractors:
type: boolean
description: Include contractor payments.
default: false
taxable_wages:
type: boolean
description: Include taxable wage columns.
default: false
gross_taxable_wages:
type: boolean
description: Include gross taxable wage columns.
default: false
result:
type: object
nullable: true
description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived.
properties:
url:
type: string
description: URL that returns a short-lived download for the generated report file.
metadata:
type: object
description: Additional loosely structured information associated with the report run.
additionalProperties: true
deprecated: false
tags:
- Report Runs
/report_runs/{report_run}:
get:
summary: Get a report run
description: Returns the specified report run.
operationId: get-a-report-run
parameters:
- name: report_run
in: path
description: ID of the report run to return.
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"id\": \"run_w4wDuqfuSqpMrSXbERrL\",\n \"report\": \"payroll_journal\",\n \"status\": \"completed\",\n \"company\": \"com_MkBYRtUviD6kYO0b85H8\",\n \"created_at\": \"2024-11-03T19:52:15Z\",\n \"completed_at\": \"2024-11-03T19:55:11Z\",\n \"parameters\": {\n \"payday_from\": \"2025-01-01\",\n \"payday_to\": \"2025-03-31\",\n \"additional_columns\": [\n \"employee.id\"\n ],\n \"contractors\": false,\n \"taxable_wages\": false,\n \"gross_taxable_wages\": false\n },\n \"result\": {\n \"url\": \"https://sandbox.checkhq.com/report_runs/run_w4wDuqfuSqpMrSXbERrL/download\"\n },\n \"metadata\": {}\n}"
schema:
type: object
properties:
id:
type: string
description: Report run ID.
example: run_w4wDuqfuSqpMrSXbERrL
report:
type: string
description: Report to generate. One of `payroll_journal` or `payroll_summary`.
enum:
- payroll_journal
- payroll_summary
example: payroll_journal
status:
type: string
description: One of `generating`, `completed`, or `failed`. New report runs start as `generating`.
enum:
- generating
- completed
- failed
example: generating
company:
type: string
nullable: true
description: Company ID to scope the report. Required for some report types.
example: com_MkBYRtUviD6kYO0b85H8
created_at:
type: string
format: date-time
description: When the report run was created.
completed_at:
type: string
format: date-time
nullable: true
description: When the report run finished successfully or failed.
parameters:
type: object
description: Parameters for the selected report. Required fields depend on the report type.
properties:
payday_from:
type: string
format: date
description: Inclusive start of the payday range (YYYY-MM-DD).
payday_to:
type: string
format: date
description: Inclusive end of the payday range (YYYY-MM-DD).
additional_columns:
type: array
description: Optional extra columns. Allowed values are `employee.id`, `contractor.id`, `payroll.id` (payroll journal only), or `employee.metadata.<key>`.
items:
type: string
payroll:
type: string
description: Optional payroll ID to scope the report to a single payroll.
group_by:
type: string
description: Payroll journal only. When set to `workplace`, groups rows by workplace.
enum:
- workplace
contractors:
type: boolean
description: Include contractor payments.
default: false
taxable_wages:
type: boolean
description: Include taxable wage columns.
default: false
gross_taxable_wages:
type: boolean
description: Include gross taxable wage columns.
default: false
result:
type: object
nullable: true
description: Present when the report run has completed successfully. Use `url` to download the generated file. Download URLs are short-lived.
properties:
url:
type: string
description: URL that returns a short-lived download for the generated report file.
metadata:
type: object
description: Additional loosely structured information associated with the report run.
additionalProperties: true
deprecated: false
tags:
- Report Runs
/report_runs/{report_run}/download:
get:
summary: Download a report run
description: Returns a short-lived download URL for the generated report artifact. The report run must be in the `completed` status and its artifact must not have expired.
operationId: download-a-report-run
parameters:
- name: report_run
in: path
description: ID of the report run to download
schema:
type: string
required: true
responses:
'200':
description: '200'
content:
application/json:
examples:
Result:
value: "{\n \"download_url\": \"https://check-reportruns.s3.amazonaws.com/ssn_report_output/2026/06/24/run_Bw6EkMDmxCPeVQ2eYzLu.zip?...\",\n \"extension\": \"zip\",\n \"content_type\": \"application/zip\"\n}"
deprecated: false
tags:
- Report Runs
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer
x-default: YOUR_API_KEY
x-readme-fauxas: true
x-provenance:
method: searched
source: https://docs.checkhq.com/reference
harvested: '2026-10-14'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.checkhq.com/reference/add-filing-blockers.md
- https://docs.checkhq.com/reference/approve-a-correction.md
- https://docs.checkhq.com/reference/approve-an-external-payroll.md
- https://docs.checkhq.com/reference/approve-payroll.md
- https://docs.checkhq.com/reference/bulk-get-employee-tax-parameter-settings.md
- https://docs.checkhq.com/reference/bulk-get-employee-tax-params.md
- https://docs.checkhq.com/reference/bulk-update-employee-tax-parameters.md
- https://docs.checkhq.com/reference/cancel-a-payment.md
- https://docs.checkhq.com/reference/company-business-details.md
- https://docs.checkhq.com/reference/company-checklist-component.md
- https://docs.checkhq.com/reference/company-connect-bank-account.md
- https://docs.checkhq.com/reference/company-employee-setup.md
- https://docs.checkhq.com/reference/company-filing-authorization.md
- https://docs.checkhq.com/reference/company-pay-history.md
- https://docs.checkhq.com/reference/company-payment-setup.md
- https://docs.checkhq.com/reference/company-progress-tracker.md
- https://docs.checkhq.com/reference/company-signatory-agreements.md
- https://docs.checkhq.com/reference/company-tax-setup.md
- https://docs.checkhq.com/reference/company-team-setup.md
- https://docs.checkhq.com/reference/company-terms-of-service.md
- https://docs.checkhq.com/reference/company-verification-documents.md
- https://docs.checkhq.com/reference/contractor-roster.md
- https://docs.checkhq.com/reference/create-a-bank-account.md
- https://docs.checkhq.com/reference/create-a-company-provided-document.md
- https://docs.checkhq.com/reference/create-a-contractor-payment.md
- https://docs.checkhq.com/reference/create-a-correction.md
- https://docs.checkhq.com/reference/create-a-pay-schedule.md
- https://docs.checkhq.com/reference/create-a-payroll-item.md
- https://docs.checkhq.com/reference/create-a-post-tax-deduction.md
- https://docs.checkhq.com/reference/create-a-report-run.md
- https://docs.checkhq.com/reference/create-a-workplace.md
- https://docs.checkhq.com/reference/create-an-earning-code.md
- https://docs.checkhq.com/reference/create-an-earning-rate.md
- https://docs.checkhq.com/reference/create-an-external-payroll.md
- https://docs.checkhq.com/reference/create-company-tax-elections.md
- https://docs.checkhq.com/reference/create-net-pay-split.md
- https://docs.checkhq.com/reference/create-payroll.md
- https://docs.checkhq.com/reference/create-the-enrollment-profile.md
- https://docs.checkhq.com/reference/credit-limits.md
- https://docs.checkhq.com/reference/delete-a-bank-account.md
- https://docs.checkhq.com/reference/delete-a-company-benefit.md
- https://docs.checkhq.com/reference/delete-a-contractor-payment.md
- https://docs.checkhq.com/reference/delete-a-correction.md
- https://docs.checkhq.com/reference/delete-a-pay-schedule.md
- https://docs.checkhq.com/reference/delete-a-payroll-copy-1.md
- https://docs.checkhq.com/reference/delete-a-payroll-item-1.md
- https://docs.checkhq.com/reference/delete-a-payroll-item.md
- https://docs.checkhq.com/reference/delete-a-payroll.md
- https://docs.checkhq.com/reference/delete-a-post-tax-deduction.md
- https://docs.checkhq.com/reference/delete-a-webhook-config.md
- https://docs.checkhq.com/reference/delete-an-employee-benefit.md
- https://docs.checkhq.com/reference/download-a-report-run.md
- https://docs.checkhq.com/reference/download-a-setup-document.md
- https://docs.checkhq.com/reference/download-a-tax-package.md
- https://docs.checkhq.com/reference/employee-roster.md
- https://docs.checkhq.com/reference/employee-tax-setup.md
- https://docs.checkhq.com/reference/employee-tax-statements-1.md
- https://docs.checkhq.com/reference/employee-withholdings-setup.md
- https://docs.checkhq.com/reference/filing-preview-component.md
- https://docs.checkhq.com/reference/full-service-setup-submission.md
- https://docs.checkhq.com/reference/generate-contractor-onboard-link.md
- https://docs.checkhq.com/reference/generate-onboard-link.md
- https://docs.checkhq.com/reference/get-a-communication.md
- https://docs.checkhq.com/reference/get-a-company-filing.md
- https://docs.checkhq.com/reference/get-a-contractor-pay-statement.md
- https://docs.checkhq.com/reference/get-a-contractor-payment.md
- https://docs.checkhq.com/reference/get-a-correction-receipt-download.md
- https://docs.checkhq.com/reference/get-a-correction-receipt.md
- https://docs.checkhq.com/reference/get-a-correction.md
- https://docs.checkhq.com/reference/get-a-form.md
- https://docs.checkhq.com/reference/get-a-fulfillment-receipt-2.md
- https://docs.checkhq.com/reference/get-a-fulfillment.md
- https://docs.checkhq.com/reference/get-a-log.md
- https://docs.checkhq.com/reference/get-a-notification.md
- https://docs.checkhq.com/reference/get-a-paper-check-2.md
- https://docs.checkhq.com/reference/get-a-paper-check.md
- https://docs.checkhq.com/reference/get-a-pay-schedule.md
- https://docs.checkhq.com/reference/get-a-report-run.md
- https://docs.checkhq.com/reference/get-a-setup-document.md
- https://docs.checkhq.com/reference/get-a-setup.md
- https://docs.checkhq.com/reference/get-a-tax-package.md
- https://docs.checkhq.com/reference/get-a-tax.md
- https://docs.checkhq.com/reference/get-a-webhook-delivery.md
- https://docs.checkhq.com/reference/get-an-agency.md
- https://docs.checkhq.com/reference/get-an-earning-code.md
- https://docs.checkhq.com/reference/get-an-earning-rate.md
- https://docs.checkhq.com/reference/get-an-employees-paystubs.md
- https://docs.checkhq.com/reference/get-an-external-payroll.md
- https://docs.checkhq.com/reference/get-an-integration-partner-copy.md
- https://docs.checkhq.com/reference/get-child-support-payments-report.md
- https://docs.checkhq.com/reference/get-company-paydays.md
- https://docs.checkhq.com/reference/get-paper-checks-report.md
- https://docs.checkhq.com/reference/get-paper-checks.md
- https://docs.checkhq.com/reference/get-paydays.md
- https://docs.checkhq.com/reference/get-payroll-journal.md
- https://docs.checkhq.com/reference/get-payroll.md
- https://docs.checkhq.com/reference/integration-partners-copy.md
- https://docs.checkhq.com/reference/integration-partners.md
- https://docs.checkhq.com/reference/list-a-webhook-config.md
- https://docs.checkhq.com/reference/list-active-funding-strikes.md
- https://docs.checkhq.com/reference/list-agencies.md
- https://docs.checkhq.com/reference/list-bank-accounts.md
- https://docs.checkhq.com/reference/list-benefits.md
- https://docs.checkhq.com/reference/list-communications.md
- https://docs.checkhq.com/reference/list-companies.md
- https://docs.checkhq.com/reference/list-company-authorization-documents.md
- https://docs.checkhq.com/reference/list-company-benefits.md
- https://docs.checkhq.com/reference/list-company-filings.md
- https://docs.checkhq.com/reference/list-company-tax-documents.md
- https://docs.checkhq.com/reference/list-company-tax-elections.md
- https://docs.checkhq.com/reference/list-company-tax-parameter-settings.md
- https://docs.checkhq.com/reference/list-company-tax-parameters.md
- https://docs.checkhq.com/reference/list-contractor-forms.md
- https://docs.checkhq.com/reference/list-contractor-payments.md
- https://docs.checkhq.com/reference/list-contractor-tax-documents.md
- https://docs.checkhq.com/reference/list-contractors.md
- https://docs.checkhq.com/reference/list-corrections.md
- https://docs.checkhq.com/reference/list-earning-codes.md
- https://docs.checkhq.com/reference/list-earning-rates.md
- https://docs.checkhq.com/reference/list-employee-tax-documents.md
- https://docs.checkhq.com/reference/list-employee-tax-elections.md
- https://docs.checkhq.com/reference/list-employee-tax-parameter-settings.md
- https://docs.checkhq.com/reference/list-employee-tax-statements.md
- https://docs.checkhq.com/reference/list-employees-tax-parameters.md
- https://docs.checkhq.com/reference/list-employees.md
- https://docs.checkhq.com/reference/list-external-payrolls.md
- https://docs.checkhq.com/reference/list-forms.md
- https://docs.checkhq.com/reference/list-fulfillments.md
- https://docs.checkhq.com/reference/list-integration-accesses-1.md
- https://docs.checkhq.com/reference/list-integration-permissions-copy.md
- https://docs.checkhq.com/reference/list-integration-permissions.md
- https://docs.checkhq.com/reference/list-logs.md
- https://docs.checkhq.com/reference/list-net-pay-splits.md
- https://docs.checkhq.com/reference/list-notifications.md
- https://docs.checkhq.com/reference/list-pay-schedules.md
- https://docs.checkhq.com/reference/list-payments.md
- https://docs.checkhq.com/reference/list-payroll-items.md
- https://docs.checkhq.com/reference/list-payrolls.md
- https://docs.checkhq.com/reference/list-post-tax-deductions.md
- https://docs.checkhq.com/reference/list-report-runs.md
- https://docs.checkhq.com/reference/list-setup-documents.md
- https://docs.checkhq.com/reference/list-setups.md
- https://docs.checkhq.com/reference/list-tax-deposits.md
- https://docs.checkhq.com/reference/list-taxes.md
- https://docs.checkhq.com/reference/list-usage-records.md
- https://docs.checkhq.com/reference/list-usage-summaries.md
- https://docs.checkhq.com/reference/list-webhook-deliveries.md
- https://docs.checkhq.com/reference/list-workplaces.md
- https://docs.checkhq.com/reference/preview-a-correction.md
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/check-hq/refs/heads/main/openapi/check-hq-report-runs-api-openapi.yml