# Read Events #### Description Returns a list of events 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 events 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/events?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/events/pages/08a07b034306679e" }, "events": [ { "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw", "event_uid": "evt_external_54008b1a4a41730f8d5c6037", "summary": "Company Retreat", "description": "", "start": "2014-09-06", "end": "2014-09-08", "deleted": false, "created": "2026-04-26T08:00:01Z", "updated": "2026-04-26T09:24:16Z", "location": { "description": "Beach" }, "participation_status": "needs_action", "attendees": [ { "email": "example@cronofy.com", "display_name": "Example Person", "status": "needs_action" } ], "organizer": { "email": "example@cronofy.com", "display_name": "Example Person" }, "transparency": "opaque", "status": "confirmed", "categories": [], "recurring": false, "event_private": false, "options": { "delete": true, "update": true, "change_participation_status": true } } ] } ``` #### 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 oldest [`Date`](/developers/api/data-types/index.md) from which to return events. When provided, this **must** be within the last **42 days**. If not provided, defaults to the maximum value of 42 days in the past. This value will not accept a time as part of the string, it will ignore the time provided and read from the start of the day. To surpass this 42 day limit, the emerging plan is needed along with a message to support requesting an extension to the sync period. Plans and pricing can be found [here](https://www.cronofy.com/api-pricing). ##### `to` *(optional)* The [`Date`](/developers/api/data-types/index.md) to return events up until, when provided **must** be less than or equal to **201 days** in the future. If not provided, defaults to the maximum value of 201 days in the future. Note that the query times are **inclusive** of the `from` date and **exclusive** of the `to` date - the results **will not** include events occurring on the `to` date. For example, if you request `from` 2026-04-26 `to` 2026-05-03, the results will contain events on the days of the 2026-04-26, **up to and including** the 2026-05-02 but **not** 2026-05-03. To include the 2026-05-03 you will need to set the `to` date as 2026-05-04. This value will also not accept timing as part of the string, it will ignore the time provided and read from the start of the day. > **INFO:** The maximum value of 42 days in the past and 201 days in the future applies from the date you are carrying out the read events query rather than the date specified in the `from` and `to` parameters in the query. The reason for this is that the sync window for Cronofy starts 42 days in the past and ends 201 days in the future, so Cronofy only store event information for calendars in this range and can’t return event information when these values are exceeded. ##### `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_deleted` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether managed and external events that have been deleted should included or excluded from the results. If not provided, only non-deleted events are returned. ##### `include_moved` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether managed and external events that have ever existed within the given window should be included or excluded from the results. If not provided, only events that are currently within the search period 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. > **INFO:** The `last_modified` value relates to changes made to the event in the external calendar. This is typically used on the back of a [push notification](/developers/api/push-notifications/index.md) notifying of a change to an event in the user's external calendar. ##### `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. > **INFO:** Note that the events you manage are not subject to the default from and to date restrictions. So if you don't specify a `from` value, you will see managed events that occur in the past beyond the 42 day limit, and if you don't specify a `to` value you will see managed events that occur in the future beyond the 201 day limit. If you specify neither, you will retrieve all the events you are managing for the account across all of time. ##### `only_managed` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether only events that you are managing for the account should be included in the results. > **INFO:** Note that the events you manage are not subject to the default from and to date restrictions. So if you don't specify a `from` value, you will see managed events that occur in the past beyond the 42 day limit, and if you don't specify a `to` value you will see managed events that occur in the future beyond the 201 day limit. 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 events to those within the set of specified `calendar_id`s. The `calendar_ids[]` parameter can be specified multiple times within the query string to include events 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 events 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. > **WARNING:** The localized times are extracted on a best-effort basis from the underlying providers. We do not receive time zone information from all providers and so their events will always be returned with a time zone identifier of `Etc/UTC`. As providers expose this data, or we implement deeper integrations with their platforms, the time zone data available to you will be improved without changes being required to your code. ##### `include_geo` *(optional)* A [`Boolean`](/developers/api/data-types/index.md) specifying whether the events should have their `location.lat` and `location.long` returned where available. Verified applications must have geo-location included in their plan or the API call will result in a [402 error](/developers/api/error-codes/index.md). ##### `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). #### 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). ##### `userinfo` *(optional)* An embedded [userinfo response](/developers/api/identity/userinfo/index.md) if `include_userinfo` was specified. ##### `events.calendar_id` This specifies the ID of the calendar as an ASCII-only [`String`](/developers/api/data-types/index.md). ##### `events.event_uid` This uniquely identifies the event as an ASCII-only [`String`](/developers/api/data-types/index.md). ##### `events.summary` The [`String`](/developers/api/data-types/index.md) value of the summary, sometimes referred to as the name, of the event. ##### `events.description` The plain text [`String`](/developers/api/data-types/index.md) value of the description, sometimes referred to as the notes, of the event. ##### `events.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 event starts. When `localized_times` is `true`, an object with two attributes, `time` and `tzid`: ```json { "time": "2014-09-13T23: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 event 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` ##### `events.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 event ends. When `localized_times` is `true`, an object with two attributes, `time` and `tzid`: ```json { "time": "2014-09-13T23: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 event 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` Also note that `end` is **exclusive**, for [`Time`](/developers/api/data-types/index.md)-based events this makes no noticeable difference, but for [`Date`](/developers/api/data-types/index.md)-based events this can be confusing. It may help to think of the `end` as the point in time by which the event will have ended. When based on time the event an event with an end of `11:30` is actually expected to end at `11:29.99999` so it would not overlap a following event starting at `11:30`. When working with dates the same logic applies so an all day event you wish to cover March 17th would start on March 17th but end **before** March 18th. ##### `events.url` A [`String`](/developers/api/data-types/index.md) that represents the url value associated with the event. Support for event URLs is currently limited to Apple and Google. ##### `events.deleted` This specifies whether the event has been deleted as a [`Boolean`](/developers/api/data-types/index.md). ##### `events.created` The [`Time`](/developers/api/data-types/index.md) the event was created. ##### `events.updated` The [`Time`](/developers/api/data-types/index.md) the event was last updated. ##### `events.location.description` *(optional)* The plain text [`String`](/developers/api/data-types/index.md) describing the event's location. ##### `events.location.lat` *(optional)* The [`String`](/developers/api/data-types/index.md) representing the event's latitude. ##### `events.location.long` *(optional)* The [`String`](/developers/api/data-types/index.md) representing the event's longitude. ##### `events.event_id` *(optional)* 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. ##### `events.participation_status` A `String` representing the participation status of the account with regard to the event. One of: - `needs_action`
the event needs action by the account, usually they have been sent an invite but are yet to respond - `accepted`
they have accepted an invitation to the event - `declined`
they have declined an invitation to the event - `tentative`
they have tentatively accepted an invitation to the event - `unknown`
their participation status for the event is unknown This is intended to help discern the status of the event for the account without having to understand which of the `attendees` entries relates to them. It will also be populated when there are no `attendees` as this is inferred to be a personal entry. `unknown` is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize. ##### `events.attendees.email` The email address associated with the attendee as a `String`. ##### `events.attendees.display_name` A human-friendly name associated with the attendee as a `String`, may be `null`. ##### `events.attendees.status` A `String` representing the participation status of the attendee with regard to the event. One of: - `needs_action`
the event needs action by the attendee, usually they have been sent an invite but are yet to respond - `accepted`
they have accepted an invitation to the event - `declined`
they have declined an invitiation to the event - `tentative`
they have tentatively accepted an invitation to the event - `unknown`
their participation status for the event is unknown `unknown` is not expected to be used but is included and documented so there is a documented response for attendees we may not know how to categorize. ##### `events.organizer.email` The email address of the organizer as a `String`. For [Managed Events](/developers/faqs/event-id-event-uid/index.md) the value of the `organizer` parameter is always `null`. ##### `events.organizer.display_name` A human-friendly name of the organizer as a `String`, may be `null`. ##### `events.transparency` A `String` defining whether an event is transparent or not to free/busy searches. One of: - `opaque`
the account should appear as busy for the duration of the event - `transparent`
the account should **not** appear as busy for the duration of the event - `unknown`
the transparency of the event is unknown `unknown` is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize. ##### `events.extended_transparency` **ALPHA** A `String` providing an enhanced view on a standard `transparency` value and exposes more about the nature of the event when available from the calendar provider. This value will always be populated and will match the value of `transparency` if none of the enhanced values are relevant or available. Currently only events within Microsoft 365 and Exchange calendars can return the extended values. This may be one of the standard `transparency` values as above: - `opaque`
the account should appear as busy for the duration of the event - `transparent`
the account should **not** appear as busy for the duration of the event - `unknown`
the transparency of the event is unknown Or an an extended value: - `working_elsewhere`
indicates the user is working away from their normal site - `tentative`
indicates an invitation not yet responded to, or which has been responded to tentatively - `out_of_office`
indicates the user is unavailable due to being out of the office, such as being on vacation These values map to Microsoft Outlook's "Show as" UI and to standard `transparency` as follows:
Outlook Show as transparency extended_transparency
Free transparent transparent
Busy opaque opaque
Working elsewhere opaque working_elsewhere
Tentative opaque tentative
Away opaque out_of_office
`unknown` is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize. ##### `events.status` A `String` defining the overall status of the event. This is provided from the calendar providers but does **not** represent a summary of the attendee statuses. One of: - `tentative`
the event is probably going to occur - `confirmed`
the event is going to occur - `cancelled`
the event is no longer going to occur - `unknown`
the status of the event is unknown `unknown` is not expected to be used but is included and documented so there is a documented response for events we may not know how to categorize. ##### `events.conferencing.provider_name` *(optional)* The [`String`](/developers/api/data-types/index.md) value for the conferencing provider used for the meeeting. ##### `events.conferencing.join_url` *(optional)* The [`String`](/developers/api/data-types/index.md) value for the conferencing URL that can be used to join the meeting. ##### `meeting_url` *(optional)* The [`String`](/developers/api/data-types/index.md) value for the conferencing URL that can be used to join the meeting, if the event is an external event (not created by Cronofy). ##### `events.categories` An array of `String`s exposing the categories assigned to the event. Each category is a free-text `String`. For the underlying providers that do not support the concept of categories, this will always be an empty array. ##### `events.tags` *(optional)* An `Object` describing zero or more contextual [`Tag`](/developers/api/data-types/index.md) values currently attached to the event. ##### `events.attachments` *(optional)* **ALPHA** An `Array` of the ids of [attachments](/developers/api/attachments/index.md) currently attached to the event. ##### `events.recurring` A [`Boolean`](/developers/api/data-types/index.md) specifying whether this is a recurring event. ##### `events.series_identifier` *(optional)* A [`String`](/developers/api/data-types/index.md) indicating the recurring series the event is a part of, when relevant. Recurring events are created as external events and so this parameter will only be present on the following recurring events and not the original managed event from which the recurrence is created. ##### `events.series_master` *(optional)* For recurring events that are instances of a recurring managed event, this will be populated. > **INFO:** This may be populated in the future for recurring series which are not managed, and you should therefore check for the presence of `events.series_master.event_id` to positively identify your managed event, if any, that this occurrence belongs to. ##### `events.series_master.event_id` *(optional)* When the event is an occurrence of an event you are managing for the account, the `event_id` you specified when [creating the master event](/developers/api/events/upsert-event/index.md) will be returned to allow you to reconcile it against your system. ##### `events.series_master.event_uid` *(optional)* For recurring events that are instances of a recurring managed event, this will be populated. > **INFO:** This may be populated in the future for recurring series which are not managed, and you should therefore check for the presence of `events.series_master.event_id` to positively identify your managed event, if any, that this occurrence belongs to. This uniquely identifies the occurrence's master event as an ASCII-only [`String`](/developers/api/data-types/index.md). ##### `events.event_private` A [`Boolean`](/developers/api/data-types/index.md) specifying whether this is a private event. ##### `events.options.delete` A [`Boolean`](/developers/api/data-types/index.md) specifying whether permission exists to delete this event. ##### `events.options.update` A [`Boolean`](/developers/api/data-types/index.md) specifying whether permission exists to update this event. ##### `events.options.change_participation_status` A [`Boolean`](/developers/api/data-types/index.md) specifying whether permission exists to [change the user's participation status](/developers/api/events/participation-status/index.md) with regard to this event. #### 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 event 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_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 - `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/events?tzid=Etc%2FUTC&last_modified={changes_since}&include_ids=true&include_deleted=true&include_managed=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 }, "events": [ { "calendar_id": "cal_U9uuErStTG@EAAAB_IsAsykA2DBTWqQTf-f0kJw", "event_uid": "evt_external_54008b1a4a41730f8d5c6037", "summary": "Company Retreat", "description": "", "start": "2014-09-06", "end": "2014-09-08", "deleted": false, "created": "2026-04-26T08:00:01Z", "updated": "2026-04-26T09:24:16Z", "location": { "description": "Beach" }, "participation_status": "needs_action", "attendees": [ { "email": "example@cronofy.com", "display_name": "Example Person", "status": "needs_action" } ], "organizer": { "email": "example@cronofy.com", "display_name": "Example Person" }, "transparency": "opaque", "status": "confirmed", "categories": [], "recurring": false, "event_private": false, "options": { "delete": true, "update": true, "change_participation_status": true } } ] } ``` --- [Read in HTML](/developers/api/events/read-events/)