---
title: "Preview pay schedule dates"
method: GET
path: "/v1/companies/{company_id}/pay_schedules/preview"
tags: ["Pay Schedules"]
---

# Preview pay schedule dates

`GET /v1/companies/{company_id}/pay_schedules/preview`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/companies/{company_id}/pay_schedules/preview`
- Auth: HTTP bearer

Provides a preview of a pay schedule with the specified parameters for the next 18 months. Use this before creating or updating a pay schedule to show expected check dates, pay period boundaries, and payroll deadlines.

### Related guides
- [Create a pay schedule](doc:create-a-pay-schedule)
- [Manage Pay Schedules via API](doc:manage-pay-schedules-api)

scope: `pay_schedules:write`

## Path parameters

- `company_id` string, required

## Query parameters

- `frequency` 'Every week' | 'Every other week' | 'Twice per month' | 'Monthly', required
- `anchor_pay_date` string, date, required
- `anchor_end_of_pay_period` string, date, required
- `day_1` integer
- `day_2` integer
- `first_pay_period_pay_day` integer
- `second_pay_period_pay_day` integer
- `first_pay_period_end_day` integer
- `second_pay_period_end_day` integer
- `end_date` string, date
- `pay_schedule_uuid` string, uuid

## Headers

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

## Response `200`

Successful

- PaySchedulePreview: Preview of pay schedule dates for the next 18 months. Use this to show partners expected pay dates, pay period boundaries, and payroll deadlines before they create or change a pay schedule. See [Preview pay schedule dates](https://docs.gusto.com/embedded-payroll/reference/get-v1-companies-company_id-pay_schedules-preview) for usage. - **pay_periods**: One entry per pay period in the range; each includes check_date, start_date, end_date, and run_payroll_by. - **holidays**: Observed bank holidays (ISO date strings) that may affect payroll timing.
  - `pay_periods` PaySchedulePreviewPayPeriod[]: A list of pay periods for the previewed pay schedule (default range is 18 months from today, or up to end_date when provided).
    - `check_date` string, date, required: The payment date, "Check date", for the pay period.
    - `start_date` string, date, required: The first day of the pay period.
    - `run_payroll_by` string, date, required: The deadline to run payroll for direct deposit on the check date.
    - `end_date` string, date, required: The last day of the pay period.
  - `holidays` string[]: A list of dates for bank closures (ISO date strings); may affect payroll processing.

## 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.

## Changes

- **2026-11-03** `f98575fa2a5e`: 6 info
  - added the new optional `query` request parameter `first_pay_period_end_day`
  - added the new optional `query` request parameter `first_pay_period_pay_day`
  - added the new optional `query` request parameter `second_pay_period_end_day`
  - added the new optional `query` request parameter `second_pay_period_pay_day`
  - …2 more

[Operation history](https://skmtc.dev/gusto/apis/gusto-api/changes/v1/companies/:company_id/pay_schedules/preview/get.md)

---

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