---
title: "List Shifts"
method: GET
path: "/api/v1/scheduling/shifts"
tags: ["Scheduling", "Public API"]
---

# List Shifts

`GET /api/v1/scheduling/shifts`

Lists shifts matching the given filters. Either provide `ids` (ignores all other filters) or provide `start`, `end`, and at least one of `employeeIds` or `scheduleIds`. The time window must be no longer than 1 month. Defaults to returning planned and published shifts.

OAuth Scopes: scheduling:shifts, time_tracking

## Query parameters

- `ids` string[]
- `start` string, date-time
- `end` string, date-time
- `employeeIds` string[]
- `scheduleIds` string[]
- `statuses` string[]
- `page` integer
- `pageSize` integer

## Response `200`

Shifts retrieved successfully

- object
  - `data` SchedulingSchedulingShiftV1[] — Array of shifts
    - `id` string, required — The ID of the shift. This can be the UUIDv7 of the shift instance, or a composite ID (<recurringShiftDefinitionId>_<recurrenceId>) for uninstantiated recurring shifts.
    - `scheduleId` string, uuid, required — The ID of the schedule the shift belongs to.
    - `name` string, nullable — The name of the shift.
    - `status` 'planned' | 'published' | 'cancelled' | 'deleted', required — The status of the shift.
    - `color` string, required — 6 character color hex code.
    - `capacity` integer, nullable — The expected headcount for the shift. Defaults to 1 if unset.
    - `start` string, date-time, nullable, required — UTC timestamp of the start of the shift.
    - `end` string, date-time, nullable, required — UTC timestamp of the end of the shift.
    - `timezone` string, required — The timezone for the shift.
    - `recurrenceRule` string, nullable — The recurrence rule. Follows the iCalendar RFC 5545 RRULE syntax.
    - `recurrenceId` string, nullable — The stable identifier for a recurrence, which is the original start of shift according to recurrence rules. Null for non-recurring shifts.
    - `recurrenceDtstart` string, nullable — The UTC start time for a recurring shift and the anchor point for the recurrence rule. Null for non-recurring shifts.
    - `recurrenceDtend` string, nullable — The UTC end time for a recurring shift. Null for non-recurring shifts.
    - `recurrenceUntil` string, nullable — The UTC datetime when the recurrence series stops generating new occurrences (UNTIL in RRULE). Null for non-recurring shifts.
    - `employeeIds` integer[] — The list of employee IDs currently assigned.
    - `unpublishedChanges` object, nullable — The pending changes that have not been published.
    - `createdAt` string, date-time — UTC timestamp when the shift was created
    - `updatedAt` string, date-time, nullable — UTC timestamp when the shift was last updated
    - `deletedAt` string, date-time, nullable — UTC timestamp when the shift was deleted
  - `meta` object
    - `totalItems` integer — Total number of shifts matching the filter.
    - `page` integer — Current page number.
    - `pageSize` integer — Number of items per page.
  - `_links` object
    - `prev` object — Link to the previous page.
      - `href` string, nullable — URL for the previous page, or null if on the first page.
    - `next` object — Link to the next page.
      - `href` string, nullable — URL for the next page, or null if on the last page.

## Other responses

- `403` — Forbidden - insufficient permissions
- `422` — Invalid input

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/versions/19ebf391a399/schema)