---
title: "List paychecks for pay cycle"
method: GET
path: "/payroll/hub/us/pay-cycles/{payCycleId}/paychecks"
tags: ["Pay cycles"]
---

# List paychecks for pay cycle

`GET /payroll/hub/us/pay-cycles/{payCycleId}/paychecks`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/payroll/hub/us/pay-cycles/{payCycleId}/paychecks`
- Auth: HTTP bearer

**Beta.** Returns the employee paychecks for a paid pay cycle. Paychecks are
filtered to the employees the authenticated caller is authorized to see.
Supports cursor pagination (`limit` 1–25, default 25).

**Rate limit:** 5 requests per minute per authenticated caller.

## Path parameters

- `payCycleId` string, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Success

- ListPaychecksOutput
  - `items` Paycheck[], required: Paychecks for the requested pay cycle, filtered to the caller's authorized employees.
    - `employeeId` string, required: Unique Bob employee identifier this paycheck belongs to.
    - `employmentStatus` string, nullable: Current employment status of the employee at the time of payment (e.g. `"Active"`, `"Terminated"`).
    - `federalFilingStatus` string, nullable: Federal tax filing status of the employee when available (e.g. `"Single"`, `"Married"`).
    - `hours` number, nullable: Total hours worked in the pay period.
    - `ssn` string, nullable: Social Security Number, formatted `NNN-NN-NNNN`. Present only when the caller is authorized to view sensitive employee data.
    - `ytdHours` number, nullable: Year-to-date total hours.
    - `ytdCompensation` number, nullable: Year-to-date total gross compensation.
    - `grossCompensation` number, nullable: Gross compensation for this pay cycle.
    - `deductions` PaycheckDeduction[], nullable: Deduction lines applied to this paycheck.
      - `name` string, required: Deduction display name (e.g. `"Dependent Care FSA"`, `"401k Plan"`).
      - `currency` string, required: Three-letter ISO 4217 currency code.
      - `amount` string, required: Decimal amount withheld as a string.
      - `type` string, nullable: Deduction category (e.g. `"benefit"`, `"garnishment"`, `"401k"`).
    - `taxes` PaycheckTax[], nullable: Tax lines withheld from this paycheck.
      - `name` string, required: Tax line name (e.g. `"Social Security"`, `"Federal Income Tax"`).
      - `amount` string, required: Decimal amount withheld as a string.
      - `currency` string, required: Three-letter ISO 4217 currency code.
    - `compensations` PaycheckCompensation[], nullable: Compensation lines that make up the gross pay.
      - `name` string, required: Compensation line name (e.g. `"Regular Hours"`, `"Bonus"`).
      - `amount` string, required: Decimal amount as a string.
      - `currency` string, required: Three-letter ISO 4217 currency code.
      - `type` string, nullable: Compensation type (e.g. `"hourly"`, `"salary"`, `"bonus"`).
  - `responseMetadata` ResponseMetadata, required: Pagination metadata returned with every list response. Use `nextCursor` to fetch the next page; `null` indicates there are no more results.
    - `nextCursor` string, nullable: Opaque cursor identifying the start of the next page of results. Pass this value back as the `cursor` query parameter on the next request to continue paging. `null` (or absent) when the current page is the last one.

## Other responses

- `400`: Bad request — invalid request body, validation error, or deduction rejected by US Payroll.
- `401`: Unauthorized — the OAuth 2.0 access token is missing, invalid, or expired.
- `403`: Forbidden — the authenticated caller does not have permission to perform this operation on the requested company, employer, or employee.
- `404`: Not found — the requested employer, employee, pay cycle, or deduction could not be found, or the authenticated caller is not authorized to see it.
- `429`: Too many requests — rate limit exceeded. Read the limit per operation (most reads are 5/minute, mutations 200/minute) and retry after the indicated delay.
- `500`: Internal server error — an unexpected error occurred. Retry with exponential backoff; if the error persists, contact HiBob support with the `requestId` from the response body.

---

[API](https://skmtc.dev/hibob/apis/retirement-partners-api.md) - [All operations](https://skmtc.dev/hibob/apis/retirement-partners-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/retirement-partners-api/revisions/5ebd2ae67958?raw)