# Get timebands

`GET /api/booking-sheets/timebands`

- **Success:** `200 OK`
- **Products:** Operator (`FOH`)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Get timebands](https://support.gladstonesoftware.cloud/reference/bookings/get-timebands)

## Overview

Lists the time bands configured for your sites. A time band is a named period of the day — an
off-peak morning, a peak evening — that a booking sheet is divided into, and it is the unit you
work in when you block time out.

Its main use is to find the `timeBandId` values that
[Create one or more booking sheet exceptions](create-one-or-more-booking-sheet-exceptions.md)
will accept. That endpoint only accepts bands whose `restrictEntry` is `true`, so call this with
`restrictedOnly=true` before building an exception request rather than guessing an id and taking a
`400`.

Time bands are configuration rather than live data, so a band
created moments ago may not appear in this list straight away.

## Endpoint

`GET {base_url}/api/booking-sheets/timebands`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `restrictedOnly` | boolean | No | Filters by whether the band restricts entry. Careful: this is a three-way switch, not a flag. Omit it and you get **every** band; send `true` and you get only entry-restricted bands — the ones booking sheet exceptions can be created against; send `false` and you get only the bands that are *not* entry-restricted. Sending `false` is therefore not the same as leaving it out. |

## Sample request

```bash title="cURL"
curl -X GET '{base_url}/api/booking-sheets/timebands' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true'
```

## Response fields

| Field | Type | Description |
|-------|------|-------------|
| `[].id` | string | The time band's identifier, and the value to send as `times[].timeBandId` when creating booking sheet exceptions. It is a configured code rather than a generated number, so treat it as opaque and read it from this endpoint rather than hard-coding it. |
| `[].description` | string | The band's name as configured by the operator — what a member of staff would call it, such as `Peak` or `Off Peak Morning`. Intended for display; it carries no times of its own and is not usable as an identifier. |
| `[].restrictEntry` | boolean | Whether the band can have entry restricted during it, which is what makes it usable for booking sheet exceptions. Only bands with `true` are accepted as `times[].timeBandId` by [Create one or more booking sheet exceptions](create-one-or-more-booking-sheet-exceptions.md); sending an id where this is `false` fails with `One or more TimeBand IDs do not exist or are not marked as entry restricted`. |

## Sample response

```json title="200 OK"
[
  {
    "id": "PEAK",
    "description": "Peak",
    "restrictEntry": true
  },
  {
    "id": "OFFPEAK",
    "description": "Off Peak",
    "restrictEntry": false
  }
]
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `500` | Internal server error | Any unexpected server-side failure, with an empty body — including the case where no time bands are configured at all, which returns `500` rather than `404`. An empty array is returned only when bands exist and none match `restrictedOnly`. |