# Free/Busy #### Description Returns a list of free/busy information across all of a users calendars. By default, the events you are managing on behalf of the account are excluded from the query results. The returned free/busy 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). Note that the events you manage are not subject to the default `from` and `to` date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time. #### Example Request The parameters are encoded in the querystring as specified in appendix B of RFC 6749. Additional linebreaks are added to the request's path for clarity. ```http GET /v1/free_busy?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/free_busy/pages/caa2dca822d5d74d98104489" }, "free_busy": [ { "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw", "start": "2026-04-24T08:00:00Z", "end": "2026-04-24T08:30:00Z", "free_busy_status": "busy", } ] } ``` #### 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 free/busy information. If not provided, defaults to the minimum value of **42 days** in the past. ##### `to` *(optional)* The [`Date`](/developers/api/data-types/index.md) to return free/busy information up until. If not provided, defaults to the maximum value of **201 days** in the future. Note that the results **will not** include events occurring **on** this date. ##### `tzid` *(required)* 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 events are returned to you. ##### `include_managed` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether events that you are managing for the account should be included or excluded from the results. If not provided, only non-managed events are returned. Note that the events you manage are not subject to the default `from` and `to` date restrictions and so if you specify neither, you will retrieve all the events you are managing for the account across all of time. ##### `calendar_ids[]` *(optional)* Restricts the returned free/busy information to that within the set of specified `calendar_id`s. The `calendar_ids[]` parameter can be specified multiple times within the query string to include free/busy information from multiple calendars: ``` calendar_ids[]=cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw&calendar_ids[]=cal_U@y23bStTFV7AAAB_iWTeH8WOCDOIW@us5gRzww ``` The possible `calendar_id`s can be discovered through the [list calendars endpoint](/developers/api/calendars/list-calendars/index.md). If no calendars are specified, the default behaviour is to return events from all of the user's calendars. ##### `localized_times` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether the free/busy 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. ##### `include_userinfo` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether the response should include an embedded [userinfo response](/developers/api/identity/userinfo/index.md). ##### `include_ids` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether the response should include IDs to identify the specific event, namely the `event_uid` and `event_id` response parameters. ##### `include_free` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether events that have a `free_busy_status` of `free` should always be included in the results. If not provided, events that have a `free_busy_status` of `free` are omitted as they do not impact availability. Please note that due to the way Google's calendar API works, `google_free_busy` calendars will only return busy events, even when this option is set to `true`. > **WARNING:** Please note that all-day events will **always** be included even if they are marked as free. This is because some calendar client & provider combinations do not allow setting an all-day event as "busy" upon creation. We've seen Apple Calendars with the macOS Calendar app behave like this, for example. Since the real-world intent of the user can be ambiguous as a result, we include the events so that your application can decide how to handle them. ##### `include_deleted` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether events that have been deleted should included or excluded from the results. If not provided, only non-deleted events are returned. ##### `last_modified` *(optional)* The [`Time`](/developers/api/data-types/index.md) that events must be modified on or after in order to be returned. If not provided, all events are returned regardless of when they were last modified. #### 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 [free/busy request](/developers/api/events/free-busy/index.md). ##### `userinfo` *(optional)* An embedded [userinfo response](/developers/api/identity/userinfo/index.md) if `include_userinfo` was specified. ##### `free_busy.calendar_id` This specifies the ID of the calendar as an ASCII-only [`String`](/developers/api/data-types/index.md). ##### `free_busy.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 free/busy period starts. When `localized_times` is `true`, an object with two attributes, `time` and `tzid`: ```json { "time": "2026-04-24T23: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 free/busy 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` ##### `free_busy.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 free/busy period ends. When `localized_times` is `true`, an object with two attributes, `time` and `tzid`: ```json { "time": "2026-04-24T23: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 free/busy 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` ##### `free_busy.free_busy_status` A `String` defining the free/busy status of the block. One of: - `tentative`
the user is probably busy for this period of time - `busy`
the user is busy for this period of time - `free`
the user is free for this period of time - `unknown`
the status of the period is unknown `unknown` is not expected to be used but is included and documented so there is a documented response for periods we may not know how to categorize. ##### `free_busy.event_uid` This uniquely identifies the event as an ASCII-only [`String`](/developers/api/data-types/index.md). ##### `free_busy.event_id` When the event is one you are managing for the account, the `event_id` you specified when [creating the event](/developers/api/events/upsert-event/index.md) will be returned to allow you to reconcile it against your system. ##### `free_busy.deleted` This specifies whether the event has been deleted as a [`Boolean`](/developers/api/data-types/index.md). #### Error responses ##### 401 Unauthorized The request was refused as the provided [authentication credentials](/developers/api/authentication/index.md) were not recognized. When an OAuth `refresh_token` is available then it should be used to [request a replacement `auth_token`](/developers/api/authorization/refresh-token/index.md) before the request is retried. ##### 403 Forbidden The request was refused as the provided [authorization credentials](/developers/api/authorization/index.md) were recognized but does not grant the `read_free_busy` scope which was required for the request. You will need to make an additional [authorization request](/developers/api/authorization/request-authorization/index.md) including the `read_free_busy` scope before retrying the request. Note that the `read_events` scope implicitly includes this scope as it allows access to a higher level of information than free/busy so you do not have to request both. ##### 422 Unprocessable The request was unable to be processed due to it containing invalid parameters. The response will contain a JSON object containing one or more errors relating to the invalid parameters. For example, if you omitted the required `tzid` parameter, you would receive a response like: ```json { "errors": { "tzid": [ { "key": "errors.required", "description": "required" } ] } } ``` The `key` field is intended for programmatic use and the `description` field is a human-readable equivalent. ### Incremental Synchronization When performing incremental synchronization, usually in reaction to a `change` [push notification](/developers/api/push-notifications/index.md), there is a recommended combination to fetch incremental changes in order to update your cache of free/busy information. - `tzid` is required - it is generally recommended this is a consistent value such as `Etc/UTC` - both `from` and `to` should be omitted from the request to ensure all changes are received - `include_ids` should be `true` in order to receive an `event_uid` which is a consistent identifier for an event - `include_deleted` should be `true` to receive details of events that have been deleted, not just those updated or changed - `include_managed` should be `true` to ensure events you are managing are included if you have such access - `include_free` should be `true` to ensure events whose `free_busy_status` changes to `free` are never omitted - `last_modified` should be provided to only return the events changed on or after the specified time - this can be tracked by your application seperately, or the `changes_since` parameter of the push notification used if you are processing every notification #### Example Request ```http GET /v1/free_busy?tzid=Etc%2FUTC&last_modified={changes_since}&include_ids=true&include_deleted=true&include_managed=true&include_free=true 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": 1 }, "free_busy": [ { "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw", "event_uid": "evt_external_54008b1a4a41730f8d5c6037", "start": "2026-04-24T08:00:00Z", "end": "2026-04-24T08:30:00Z", "free_busy_status": "busy", "deleted": false, }, { "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw", "event_uid": "evt_external_64b1801a8090ea21640c9153", "start": "2026-04-26", "end": "2026-04-27", "free_busy_status": "free", "deleted": true, } ] } ``` --- [Read in HTML](/developers/api/events/free-busy/)