---
title: "List upcoming shifts for a schedule"
method: GET
path: "/api/v1/schedules/{id}/occurrences"
tags: ["Schedules"]
---

# List upcoming shifts for a schedule

`GET /api/v1/schedules/{id}/occurrences`

## Request

- Base URL: `https://volunteerreminder.com`
- URL: `https://volunteerreminder.com/api/v1/schedules/{id}/occurrences`
- Auth: HTTP bearer

Occurrences in [from, to] plus the schedule's roster and each date's attendance/exception status. Requires the `read` scope.

## Path parameters

- `id` string, required: The schedule's numeric id.

## Query parameters

- `from` string: Start of the range: "yyyy-MM-dd" (interpreted in the account timezone) or a full ISO 8601 datetime. Defaults to now.
- `to` string: End of the range, same formats as `from`. Defaults to 90 days from now.
- `limit` integer: Maximum rows to return (default 20, max 100).

## Response `200`

Upcoming occurrences.

- ScheduleOccurrencesResponse
  - `schedule_id` number, required: The schedule these occurrences belong to.
  - `time_zone` string, required: IANA timezone used to render dates.
  - `occurrences` ScheduleOccurrence[], required
    - `id` number, required: Occurrence id.
    - `date` string, required: "yyyy-MM-dd" civil date in the account timezone.
    - `time` string, nullable, required: Wall-clock "HH:mm", or null when the schedule has no time-of-day.
    - `occurrence_at` number, required: Epoch ms (UTC) instant of this occurrence.
    - `label` string, required: Human-readable label.
    - `attending` boolean, required: False when this specific date has been marked as an exception (the roster is not attending this occurrence).
    - `assigned_contacts` AssignedContact[], required: The schedule's roster. Assignment is schedule-level, not per-occurrence.
      - `id` number, required: Contact id.
      - `full_name` string, required: Contact's full name.

## Other responses

- `400`: The request failed schema validation (`validation_error`). On the import endpoints, also when the text is UTF-16 (Excel "Unicode Text"; `unsupported_encoding`): resend it as CSV UTF-8.
- `401`: Missing or invalid API key.
- `403`: The API key lacks a scope required by this endpoint.
- `404`: The requested resource does not exist.

---

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