---
title: "Get a schedule"
method: GET
path: "/api/v1/schedules/{id}"
tags: ["Schedules"]
---

# Get a schedule

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

## Request

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

Requires the `read` scope.

## Path parameters

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

## Response `200`

The schedule.

- Schedule
  - `id` number, required: Schedule id.
  - `description` string, required: Short label shown on the schedule list and in reminder messages, e.g. "Sunday morning greeters".
  - `job_id` number, required: Job/role id (use for per-job reminder overrides).
  - `job_name` string, nullable, required: Resolved job/role name.
  - `group_id` integer, nullable, required: Id of an existing volunteer group to attach, or null. An id not owned by this account is silently ignored (treated as null).
  - `group_name` string, nullable, required: Resolved group name, or null.
  - `schedule_type` 'weekly' | 'biweekly' | 'monthly_fixed' | 'monthly_nth' | 'bimonthly_fixed' | 'bimonthly_nth' | 'custom', required: Recurrence shape. 'weekly' recurs on one or more days of the week; 'biweekly' is the same weekday mask every 14 days (start_date picks which week — it is not BiMonthly, which is every other MONTH); 'monthly_fixed' / 'bimonthly_fixed' recur on a fixed day of the month; 'monthly_nth' / 'bimonthly_nth' recur on the Nth weekday of the month; the 'bimonthly_*' variants additionally alternate months starting from start_month; 'custom' uses an explicit list of dates.
  - `days_of_week` string[], required: Days of the week this recurs on. Required (non-empty) when schedule_type is 'weekly' or 'biweekly'; ignored for every other schedule_type.
  - `nth_weekday` 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'null', nullable, required: The weekday that recurs. Used by schedule_type 'monthly_nth' / 'bimonthly_nth'; defaults to Sunday if omitted for those types.
  - `week_of_month` number, nullable, required: Nth-weekday occurrence (1-5), or null when schedule_type doesn't use it.
  - `day_of_month` number, nullable, required: Fixed day of month, or null when schedule_type doesn't use it.
  - `start_month` number, nullable, required: Bimonthly anchor month (1-12), or null when schedule_type doesn't use it.
  - `time` string, nullable, required: Wall-clock time of day "HH:mm" (24h) in the account's timezone, or null for no specific time (midnight).
  - `start_date` string, nullable, required: "yyyy-MM-dd" in the account's timezone before which no occurrences materialize, or null for no lower bound. For 'biweekly' this date also picks which week the 14-day rotation lands on (Sunday-week of this day is an on-week). When omitted for biweekly, the server stores the first selected weekday with a shift still ahead (today if it is selected and its start time hasn't passed, else the next selected weekday; the first shift), and the rotation counts from there. On PATCH of an existing biweekly schedule, null keeps the stored date (the rotation only moves when you send a new date).
  - `end_date` string, nullable, required: "yyyy-MM-dd" in the account's timezone after which occurrence materialization stops, or null for no end date.
  - `custom_dates` string[], required: Explicit list of "yyyy-MM-dd" dates. Required (non-empty) when schedule_type is 'custom'; ignored otherwise.
  - `contact_ids` integer[], required: Volunteer roster for this schedule. Ids not owned by this account are silently dropped.
  - `notes` string, nullable, required: Free-text internal notes.
  - `next_occurrence_at` number, nullable, required: Epoch ms (UTC) of the next upcoming, attendable occurrence, or null.
  - `is_muted` boolean, required: Whether reminders for this schedule are muted.
  - `created_at` number, required: Epoch ms (UTC) this schedule was created.

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