# Sequenced Availability Query > **BETA** ### Description Inspects calendars to determine the common availability for a number of pre-defined events. For example scheduling a series of events for an interview process. A typical workflow of Sequenced Availability would be: - User defines sequence of events to schedule with desired attendees. - Application checks Availability for sequence for desired events each with a unique `sequence_id`. - Application renders options to user to select from. - User makes selection of sequence. - Application upserts events in attendees calendars using selected option and `sequence_id` as a lookup for each event. ### URL format ``` {data_center_url}/v1/sequenced_availability ``` ### Example Request ```http POST /v1/sequenced_availability HTTP/1.1 Host: {data_center_url} Authorization: Bearer {API_KEY} Content-Type: application/json; charset=utf-8 { "query_periods": [ { "start": "2026-04-19T09:00:00Z", "end": "2026-04-19T18:00:00Z" }, { "start": "2026-04-20T09:00:00Z", "end": "2026-04-20T18:00:00Z" } ], "sequence":[ { "sequence_id":"123", "ordinal":1, "participants":[ { "members":[ { "sub": "acc_5ba21743f408617d1269ea1e", "calendar_ids":[ "cal_n23kjnwrw2_jsdfjksn234" ] } ], "required":"all" } ], "required_duration":{ "minutes": 60 }, "start_interval":{ "minutes": 60 }, "buffer":{ "before":{ "minimum": { "minutes" : 30 }, "maximum": { "minutes" : 60 } }, "after":{ "minimum": { "minutes" : 15 }, "maximum": { "minutes" : 30 } } } }, { "sequence_id":"456", "ordinal":2, "participants":[ { "members":[ { "sub": "acc_64b17d868090ea21640c914c", "available_periods": [ { "start": "2026-04-19T09:00:00Z", "end": "2026-04-19T12:00:00Z" }, { "start": "2026-04-20T10:00:00Z", "end": "2026-04-20T20:00:00Z" } ] } ], "required":"all" } ], "required_duration":{ "minutes": 60 }, "start_interval":{ "minutes": 60 }, "buffer":{ "before":{ "minimum": { "minutes" : 30 }, "maximum": { "minutes" : 60 } }, "after":{ "minimum": { "minutes" : 15 }, "maximum": { "minutes" : 30 } } } } ] } ``` ### Example Response ```http HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "sequences":[ { "sequence":[ { "sequence_id":"123", "start": "2026-04-19T09:00:00Z", "end": "2026-04-19T10:00:00Z", "participants":[ { "sub": "acc_5ba21743f408617d1269ea1e" } ] }, { "sequence_id":"456", "start": "2026-04-19T10:00:00Z", "end": "2026-04-19T11:00:00Z", "participants":[ { "sub": "acc_64b17d868090ea21640c914c" } ] } ] }, { "sequence":[ { "sequence_id":"123", "start": "2026-04-19T11:00:00Z", "end": "2026-04-19T12:00:00Z", "participants":[ { "sub": "acc_5ba21743f408617d1269ea1e" } ] }, { "sequence_id":"456", "start": "2026-04-19T12:00:00Z", "end": "2026-04-19T13:00:00Z", "participants":[ { "sub": "acc_64b17d868090ea21640c914c" } ] } ] } ] } ``` ### 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). ##### `API_KEY` *(required)* The `client_secret` of the client. ##### `query_periods` *(required)* An array of 1 to 50 query periods, across up to 35 days of the period of synchronized events, within which suitable matches may be found. ##### `query_periods.start` *(required)* The `start` of an query period as a [`Time`](/developers/api/data-types/index.md). It must represent a future point in time. ##### `query_periods.end` *(required)* The `end` of an query period as a [`Time`](/developers/api/data-types/index.md). Must be at least **1 minute** after the corresponding `start` and within **35 days** of the earliest `start`. ##### `sequence` *(required)* An array containing the parts of the sequence to find availability for. A maximum of 5 parts can be specified for a sequence ##### `sequence.sequence_id` *(required)* A [`String`](/developers/api/data-types/index.md) value to identify this part of the sequence, must be unique for this request. ##### `sequence.ordinal` A [`Integer`](/developers/api/data-types/index.md) value to define the order of this part of the sequence, this is used to determine desired order of the sequence. ##### `sequence.participants` *(required)* An array of the groups of participants whose availability should be taken into account. At least one group must be specified, a maximum of 10 accounts may be specified over a combination of groups. ##### `sequence.participants.members` *(required)* An array of participants that should have their availability taken into account as part of this group. At least one participant must be specified and you must have been granted the `read_free_busy` scope for each participant involved in the availability 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 have both. ##### `sequence.participants.members.sub` *(required)* The internal Cronofy ID for the account, as an ASCII-only [`String`](/developers/api/data-types/index.md). This can be retrieved by calling the [UserInfo endpoint](/developers/api/identity/userinfo/index.md) with a valid `access_token` ##### `sequence.participants.members.available_periods` An array of 1 to 50 available periods within which the member is available. If omitted it is assumed the member is available whenever they do not have a "busy" event in their calendar. ##### `sequence.participants.members.available_periods.start` *(required)* The`start` of an available period as a [`Time`](/developers/api/data-types/index.md). It must represent a future point in time. ##### `sequence.participants.members.available_periods.end` *(required)* The`end` of an available period as a [`Time`](/developers/api/data-types/index.md). Must be at least **1 minute** after the corresponding `start` and within **35 days** of the earliest `start`. ##### `sequence.participants.members.calendar_ids` Restricts the events contributing towards the members availability to those within the set of specified `calendar_id`s. ##### `sequence.participants.members.ignore_tentative` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether events where the user is marked as tentatively attending will be considered as free periods or not. By default these events are considered as busy periods. ##### `sequence.participants.members.availability_constraints` *(optional)* An `Array` of constraints that must be satisfied for each slot or period. > **WARNING:** Note that availability constraints do not consider other events in the sequence. For example if a subject already has two "Interview" tagged events in their calendar and you are limiting that tag to 3 per week then they will still get picked for 2 more if you are sequence scheduling 2 interviews. ##### `sequence.participants.members.availability_constraints.period` *(required)* A `String` value specifying the time period over which the constraint is to be applied. You can specify one of the following values: - `day` will apply the constraint each day. You must also pass the `tzid` parameter to indicate which timezone you want to use to determine when a day starts and ends. - `week` will apply the constraint over the period of a week. A week is considered to be Monday to Sunday in the UTC time zone, following the ISO standard. ##### `sequence.participants.members.availability_constraints.tzid` *(optional)* A `String` value specifying the time zone to use when the `period` is set to `day`. Must be a known time zone identifier from the [IANA Time Zone Database](https://www.iana.org/time-zones). See the [time zones](/developers/calendars-events/time-zones/index.md) page for more information. Currently specifying a time zone is only supported with the `day` constraint period. ##### `sequence.participants.members.availability_constraints.limit` *(required)* An `Integer` value specifying the maximum number of events allowable per period. If `tags` are provided then limit will only consider events with all of the given tags. ##### `sequence.participants.members.availability_constraints.tags` *(optional)* An `Object` describing zero or more contextual [`Tag`](/developers/api/data-types/index.md) values to search for against each event when searching for availability. If more than one tag is provided the events must have all of the specified tags to be considered. Tags may be treated as an empty set by omitting the `tags` field, setting it to `null`, the empty object `{}`, or leaving the context as an empty array `{ "private": [] }`. The context of "private", as seen in the example below, is the only context currently supported. ```http POST /v1/sequenced_availability HTTP/1.1 Host: {data_center_url} Authorization: Bearer {API_KEY} Content-Type: application/json; charset=utf-8 { "query_periods": [ { "start": "2026-04-19T09:00:00Z", "end": "2026-05-03T18:00:00Z" } ], "sequence":[ { "sequence_id":"123", "ordinal":1, "participants":[ { "members":[ { "sub": "acc_5ba21743f408617d1269ea1e", "calendar_ids":[ "cal_n23kjnwrw2_jsdfjksn234" ], "availability_constraints":[{ "tags": { "private": [ { "value": "Interview" } ] }, "limit": 3, "period": "week" }] } ], "required":"all" } ], "required_duration":{ "minutes": 60 }, "start_interval":{ "minutes": 60 } }, { "sequence_id":"456", "ordinal":2, "participants":[ { "members":[ { "sub": "acc_64b17d868090ea21640c914c", "availability_constraints":[{ "tags": { "private": [ { "value": "Interview" } ] }, "limit": 5, "period": "week" }] } ], "required":"all" } ], "required_duration":{ "minutes": 60 }, "start_interval":{ "minutes": 60 } } ] } ``` Tags on events are managed via the [create or update](/developers/api/events/upsert-event/index.md) event endpoint. ##### `sequence.participants.required` *(required)* Either a [`String`](/developers/api/data-types/index.md) of `all` to specify that all `members` of the group need to be available for a period to be viable, or an [`Integer`](/developers/api/data-types/index.md) to specify the minimum number of the group that must be available. ##### `sequence.required_duration` *(required)* A [`Duration`](/developers/api/data-types/index.md) describing the minimum period that the participant groups must be satisfied for a period to be deemed as available. Must be greater than zero minutes in length. ##### `sequence.buffer.before.minimum` A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free before the event starts. ##### `sequence.buffer.before.maximum` A [`Duration`](/developers/api/data-types/index.md) specifying the maximum number of minutes that must be free before the event starts. ##### `sequence.buffer.after.minimum.` A [`Duration`](/developers/api/data-types/index.md) specifying the minimum number of minutes that must be free after the event ends. ##### `sequence.buffer.before.maximum` A [`Duration`](/developers/api/data-types/index.md) specifying the maximum number of minutes that must be free after the event ends. ##### `sequence.start_interval` A [`Duration`](/developers/api/data-types/index.md) describing the frequency that a sequence can start on. For example, "every hour" or "every 15 minutes". Must be one of `5`, `10`, `15`, `20`, `30`, or `60` minutes. ##### `excluded_events` *(optional)* An array of objects describing events that should not be considered during the Availability calculation. ```json { ... "excluded_events": [ { "event_id": "interview_123" }, { "event_uid": "evt_external_64f758b2707e9e455c32e9e" }, ] }``` Each item must specify either `event_id` for a Managed Event or the `event_uid` of an External Event (you can learn more about the [difference between these here](/developers/faqs/event-id-event-uid/index.md)). If the specified events appear in any of the calendars queried, they will not block time from being considered as Available. This is useful for operations such as querying to reschedule a meeting, where omitting the current event representing the meeting may make some additional slots available. It can also be used to customize your query based on context, such as allowing a query for an important customer meeting to ignore several reschedulable internal meetings. ### Response parameters ##### `sequences` An array of possible sequences that match the criteria specified in the request. ##### `sequences.sequence` An array of available periods which meet the criteria specified in the request. ##### `sequences.sequence.sequence_id` A value to identify this part of the sequence. ##### `sequences.sequence.start` The`start` of an available period as a [`Time`](/developers/api/data-types/index.md). ##### `sequences.sequence.end` The`end` of an available period as a [`Time`](/developers/api/data-types/index.md). ##### `sequences.sequence.participants` An array of participants that are available for the given period. ##### `sequences.sequence.participants.sub` The internal Cronofy ID for the account, as an ASCII-only [`String`](/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. Note that whilst many accounts can be part of the availability request that authentication is performed via the`access_token` for only one of them. 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. ##### 402 Payment Required The request was refused as your plan does not include the required feature. ##### 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 `required_duration` parameter, you would receive a response like: ```json { "errors": { "required_duration": [ { "key": "errors.required", "description": "required" } ] } } ``` The `key` field is intended for programmatic use and the `description` field is a human-readable equivalent. --- [Read in HTML](/developers/api/scheduling/sequenced-availability/)