# Read Available Periods

#### Description
Returns a list of available periods for the authorized account.

The returned available periods will start before the given `to` [`Date`](/developers/api/data-types/index.md) and will end on or after the given `from` [`Date`](/developers/api/data-types/index.md).

#### Example Request
The parameters are encoded in the querystring as specified in <a href="https://www.rfc-editor.org/rfc/rfc6749#appendix-B">appendix B of RFC 6749</a>. Additional linebreaks are added to the request's path for clarity.

```http
GET /v1/available_periods?from={FROM_DATE}&to={TO_DATE}&tzid={TZID} HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {ACCESS_TOKEN}
```

#### Example Response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "pages": {
    "current": 1,
    "total": 2,
    "next_page": "https://api.cronofy.com/v1/available_periods/pages/08a07b034306679e"
  },
  "available_periods": [
    {
      "available_period_id": "qTtZdczOccgaPncGJaCiLg",
      "start": "2026-04-28T15:30:00Z",
      "end": "2026-04-28T17:00:00Z"
    }
  ]
}
```

#### Request parameters
##### `data_center_url` *(required)*

The URL for the data center you want to communicate with. Possible choices are:

- `api-au.cronofy.com` - Australia
- `api-ca.cronofy.com` - Canada
- `api-de.cronofy.com` - Germany
- `api-sg.cronofy.com` - Singapore
- `api-uk.cronofy.com` - United Kingdom
- `api.cronofy.com` - United States

Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `from` *(optional)*

The minimum [`Date`](/developers/api/data-types/index.md) from which to return available periods.

##### `to` *(optional)*

The [`Date`](/developers/api/data-types/index.md) to return available periods up until.

Note that the results **will not** include available periods occurring **on** this date.

##### `tzid` *(optional)*

A [`String`](/developers/api/data-types/index.md) representing a known time zone identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).

Common examples are:

- `Etc/UTC`

- `Europe/Paris`

- `America/Chicago`

It is recommended that you use the same `tzid` for all requests made for an individual user in order to ensure all their available periods are returned to you.

Required if specifying either `from` or `to`

##### `localized_times` *(optional)*

A [`Boolean`](/developers/api/data-types/index.md) specifying whether the available periods should have their `start` and `end` times returned with any available localization information.

If not provided the `start` and `end` times will be returned as simple [`Time`](/developers/api/data-types/index.md) values.

#### Response parameters
##### `pages.current`

An [`Integer`](/developers/api/data-types/index.md) specifying which page of the result set the current request is for.

##### `pages.total`

An [`Integer`](/developers/api/data-types/index.md) specifying the total number of pages in the result set.

##### `pages.next_page` *(optional)*

When present, a [`String`](/developers/api/data-types/index.md) specifying the URL for the next page of results.

The next page of results can be retrieved by issuing a `GET` request to this URL and you will receive a response in the same format as a regular [read events request](/developers/api/events/read-events/index.md).

##### `available_periods.available_period_id`

The `available_period_id` you specified when [creating the available period](/developers/api/scheduling/available-periods/upsert/index.md).

##### `available_periods.start`

When `localized_times` is not specified or is `false`, the [`Time`](/developers/api/data-types/index.md) or [`Date`](/developers/api/data-types/index.md) representing when the available period starts.

When `localized_times` is `true`, an object with two attributes, `time` and `tzid`:

```json
{
  "time": "2026-04-27T23:00:00+02:00",
  "tzid": "Europe/Paris"
}
```

The `time` attribute is the [`Time`](/developers/api/data-types/index.md) or [`Date`](/developers/api/data-types/index.md) representing when the available period starts. This will be provided with an offset matching that of the corresponding `tzid`.

The `tzid` attribute specifies a [`String`](/developers/api/data-types/index.md) representing a known time zone identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).

Common examples are:

- `Etc/UTC`

- `Europe/Paris`

- `America/Chicago`

##### `available_periods.end`

When `localized_times` is not specified or is `false`, the [`Time`](/developers/api/data-types/index.md) or [`Date`](/developers/api/data-types/index.md) by which the available period ends.

When `localized_times` is `true`, an object with two attributes, `time` and `tzid`:

```json
{
  "time": "2026-04-27T23:00:00+02:00",
  "tzid": "Europe/Paris"
}
```

The `time` attribute is the [`Time`](/developers/api/data-types/index.md) or [`Date`](/developers/api/data-types/index.md) by which the available period ends. This will be provided with an offset matching that of the corresponding `tzid`.

The `tzid` attribute specifies a [`String`](/developers/api/data-types/index.md) representing a known time zone identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones).

Common examples are:

- `Etc/UTC`

- `Europe/Paris`

- `America/Chicago`



---
[Read in HTML](/developers/api/scheduling/available-periods/read/)