# List a schedule's shifts over a range

`GET https://evohub.io/api/v1/schedules/{id}/shifts`

Part of the [On-Call API](https://docs.evohub.io/oncall.md) reference · operationId `listScheduleShifts`.

Every layer's turns between `from` and `to`, cut to each layer's shift
window (its weekdays and hours), as the calendar shows them. These are
the turns the layers give; overrides are not applied here — list them
with `GET /api/v1/schedules/{id}/overrides`. Turns are cut at `from` and
`to`, and a layer with nobody on it gives none. The range may be at most
62 days.

A schedule that belongs to a team is visible only to callers in that team (and
to administrators acting in person); others get 404, as if it did not exist.

**Permission (API-key scope):** `oncall:schedule:read`.

## Authorization

Any one of:

- `bearerAuth` (oncall:schedule:read)
- `apiKeyHeader` (oncall:schedule:read)

Where:

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Path parameters

- `id` (string, required, example `5b1c7d2e-8f3a-4b9c-a0d1-e2f3a4b5c6d7`): The schedule's id.

## Query parameters

- `from` (string (date-time), required, example `2026-10-19T00:00:00Z`): Start of the range, an RFC 3339 instant.
- `to` (string (date-time), required, example `2026-11-16T00:00:00Z`): End of the range, an RFC 3339 instant after `from` and at most 62 days later.

## Responses

### 200 — The turns, every layer's together; an empty array when there are none.

Content type: `application/json`

Type: `object`

- `data` (array of ScheduleTurn, required)
  - `layer_id` (string): The layer giving the turn (`preview` for a layer that is not stored yet).
  - `user_id` (string): Who holds the turn; empty in a preview with no members.
  - `start` (string (date-time))
  - `end` (string (date-time))
- `success` (boolean, required, value `true`)

### 400 — `from` or `to` is missing or not RFC 3339, or `to` is not after `from` or is more than 62 days later (`VALIDATION_FAILED`).

Content type: `application/json`

Type: `ValidationError`

- `error` (object, required)
  - `code` (string, required, value `VALIDATION_FAILED`)
  - `message` (string, required)
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.
  - `details` (array of object, required)
    - `field` (string)
    - `message` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 404 — No schedule with this id in your organization (`NOT_FOUND`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 429 — Too many requests (`RATE_LIMITED`). Wait `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required): Machine-readable code. Branch on this.
  - `message` (string, required): Human-readable explanation.
  - `request_id` (string): The request's `X-Request-ID`. Quote it to support.

## Example request

```bash
curl -X GET 'https://evohub.io/api/v1/schedules/5b1c7d2e-8f3a-4b9c-a0d1-e2f3a4b5c6d7/shifts?from=2026-10-19T00%3A00%3A00Z&to=2026-11-16T00%3A00%3A00Z' \
  -H 'Authorization: Bearer <TOKEN>'
```