---
title: "Get pay periods for a company"
method: GET
path: "/v1/companies/{company_id}/pay_periods"
tags: ["Payrolls"]
---

# Get pay periods for a company

`GET /v1/companies/{company_id}/pay_periods`

Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened.

To begin submitting information for a given payroll, we need to agree on the time period.

By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the `start_date` and `end_date` parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates.

Starting in version 2023-04-01, the `eligible_employees` attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the [PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare](https://docs.gusto.com/embedded-payroll/reference/put-v1-companies-company_id-payrolls-payroll_id-prepare) endpoint.

scope: `payrolls:read`

## Path parameters

- `company_id` string, required

## Query parameters

- `start_date` string, date
- `end_date` string, date
- `payroll_types` 'regular' | 'transition' | 'regular,transition' — Comma-separated list of payroll types to include (regular, transition). Defaults to regular only.

## Headers

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

## Response `200`

Successful

- PayPeriod[]
  - `start_date` string — The start date, inclusive, of the pay period.
  - `end_date` string — The end date, inclusive, of the pay period.
  - `pay_schedule_uuid` string — A unique identifier of the pay schedule to which the pay period belongs.
  - `payroll` object — Information about the payroll for the pay period.
    - `payroll_uuid` string — The UUID of the payroll for this pay period.
    - `check_date` string — The date on which employees will be paid for the payroll if the payroll is submitted on time.
    - `processed` boolean — Whether or not the payroll has been successfully processed. Note that processed payrolls cannot be updated. Additionally, a payroll is not guaranteed to be processed just because the payroll deadline has passed. Late payrolls are not uncommon. Conversely, users may choose to run payroll before the payroll deadline.
    - `payroll_deadline` string, date-time — The date by which payroll should be run for employees to be paid on time. Payroll data, such as time and attendance data, should be submitted on or before this date.
    - `payroll_type` 'regular' | 'transition' — Whether it is regular pay period or transition pay period.

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)