# Get Shifts

> GET /v1/shifts

`GET https://app.untetherlabs.com/api/v1/shifts`

Get shifts within a given time range.

This endpoint is paginated. See /using-the-api/pagination.

## Request

```bash
curl -X GET 'https://app.untetherlabs.com/api/v1/shifts' \
  -H 'Authorization: Bearer $UNTETHER_API_KEY'
```

## Query parameters

- `provider` (uuid)
- `team` (uuid)
- `startDate` (string, example "2024-11-20T07:43:34+0000") — Used to inclusively filter shifts whose startDate is later than the provided start time, in yyyy-MM-dd format. Defaults to current date - 1 month.
- `endDate` (string, example "2024-11-20T07:43:34+0000") — Used to exclusively filter shifts whose endDate is earlier than the provided end time, in yyyy-MM-dd format. Defaults to current date + 1 month.
- `includeOpen` (boolean, default false)
- `includeDisplayNames` (boolean, default false)
- `sort` (string) — Available fields: `startDate` See [Query Parameters](/using-the-api/query-parameters) for more information on sorting.
- `pageSize` (number, default 20, min 1, max 200)
- `cursor` (string)

## Response 200

- `items` (Shift[], required)
  - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
  - `version` (number) — Version number for optimistic locking. Include this when updating to detect conflicts.
  - `provider` (uuid | null, required) — The provider of the shift. If null, the shift is an open shift.
  - `providerName` (string | null) — The display name of the provider. Only populated when the request opts in via includeDisplayNames.
  - `startDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `endDate` (string, required, example "2024-11-20T07:43:34+0000")
  - `segments` (ShiftSegment[], required) — The segments that make up a shift, ordered by startDate.
    - `importedId` (string | null, required) — If a segment was created in an external system, this is the ID of the segment in that system.
    - `createdAt` (string, required, example "2024-11-20T07:43:34+0000")
    - `role` (uuid | null, required) — The role of the shift. Can be null if the shift is pulled from an external system.
    - `roleName` (string | null) — The display name of the segment's role. Only populated when the request opts in via includeDisplayNames.
    - `roleColor` (string | null) — The hex color of the segment's role. Only populated when the request opts in via includeDisplayNames.
    - `roleImportedId` (string) — *DEPRECATED* The ID of the role in the external system. Once all roles are migrated to the system, this field will be removed.
    - `additionalInfo` (any) — *DEPRECATED* Additional information about the segment.
    - `isBreak` (boolean, required, example false) — Used to denote whether or not the provider will be on break during this segment.
    - `isOnCall` (boolean, required, example false)
    - `type` (enum, required, one of `working`, `paid_break`, `unpaid_break`, `on_call`) — The type of the segment.
    - `startDate` (string, required, example "2024-11-20T07:43:34+0000") — The timestamp of when the shift starts.
    - `endDate` (string, required, example "2024-11-20T07:43:34+0000") — The timestamp of when the shift ends.
    - `skillRequirement` (NullableSkillRequirement)
      - Option 1: SkillRequirementCondition
      - Option 2: SkillRequirementGroup
    - `labels` (string[], required) — The label IDs associated with this shift segment.
  - `payCodes` (ShiftPayCode[], max items 1)
    - `payCodeId` (uuid, required) — The pay code ID associated with this shift.
    - `value` (number) — Only present for variable pay codes. The value of the pay code for this shift.
  - `team` (uuid | null, required) — The team that the shift is associated with.
  - `note` (string | null, required) — A note about the shift. Visible to providers.
  - `isCallout` (boolean, required) — Whether the shift is marked as a callout. Callout shifts are hidden from reads unless an endpoint explicitly includes them.
  - `workRuleOverride` (uuid | null, required)
- `cursor` (string)

## Errors

- `validation` (400) — Input validation failed.
- `unauthorized` (403) — You do not have permission to perform this action.