event: delta
Namespace: microsoft.graph
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Get a set of event resources that have been added, deleted, or updated in one or more calendars.
You can get specific types of these incremental changes in the events in all the calendars of a mailbox or in a specific calendar, or in an event collection of a calendarView (range of events defined by start and end dates) of a calendar. The calendar can be the default calendar or some other specified calendar of the user's. In the case of getting incremental changes on calendarView, the calendar can be a group calendar as well.
Typically, synchronizing events in a calendar or calendarView in a local store entails a round of multiple delta function calls. The initial call is a full synchronization, and every subsequent delta call in the same round gets the incremental changes (additions, deletions, or updates). This allows you to maintain and synchronize a local store of events in the specified calendar, without having to fetch all the events of that calendar from the server every time.
The following table lists the differences between the delta function on events and the delta function on a calendarView in a calendar.
| Delta function on events | Delta function on calendarView |
|---|---|
| Gets incremental changes of all the events in a calendar not bounded by a start and end date range. Alternatively, you can get incremental changes of the events in a calendar bounded by a start time, starting on or after that date/time. | Gets incremental changes of events within the start and end date/time of the calendarView. |
Returns only a limited set of event properties for performance reasons. Client to subsequently use GET /events/{id} to expand any events. |
Server-side expansion returns a fuller set of event properties. |
| Response includes single instances and recurring series master. | Response includes single instances, and occurrences and exceptions of recurring series. |
| Applies to events in user calendars but not group calendars. | Applies to events in user and group calendars. |
| Currently available only in the beta version. | Available in the v1.0 and beta versions. |
This API is available in the following national cloud deployments.
| Global service | US Government L4 | US Government L5 (DOD) | China operated by 21Vianet |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
Permissions
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
| Permission type | Least privileged permissions | Higher privileged permissions |
|---|---|---|
| Delegated (work or school account) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Delegated (personal Microsoft account) | Calendars.ReadBasic | Calendars.Read, Calendars.ReadWrite |
| Application | Calendars.Read | Calendars.ReadBasic, Calendars.ReadWrite |
HTTP request
This section shows the HTTP request syntax for the initial delta function call to start a full synchronization that retrieves all the events in the specified calendar or calendar view. This syntax does not contain any state tokens.
The query URL returned in a @odata.nextLink or @odata.deltaLink of a successful response includes a state token. For any subsequent delta function call, use the query URL in a @odata.nextLink or @odata.deltaLink preceding it.
Delta function on events in a user calendar (preview)
Apply the delta function on all the events or events starting on or after a specific date/time, in the specified user calendar(s):
To get incremental changes of all the events, or of events starting on or after the specified date/time in the user's mailbox:
GET /me/events/delta GET /users/{id | userPrincipalName}/events/delta GET /me/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/events/delta?startDateTime={start_datetime}To get incremental changes of all the events, or of events starting on or after the specified date/time in the user's default calendar:
GET /me/calendar/events/delta GET /users/{id | userPrincipalName}/calendar/events/delta GET /me/calendar/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendar/events/delta?startDateTime={start_datetime}To get incremental changes of all the events, or of events starting on or after the specified date/time in the specified user calendar:
GET /me/calendars/{id}/events/delta GET /users/{id | userPrincipalName}/calendars/{id}/events/delta GET /me/calendars/{id}/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendars/{id}/events/delta?startDateTime={start_datetime}To get incremental changes all the events, or of events starting on or after the specified date/time in the specified calendar group and calendar:
GET /me/calendarGroups/{id}/calendars/{id}/events/delta GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta GET /me/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime} GET /users/{id | userPrincipalName}/calendarGroups/{id}/calendars/{id}/events/delta?startDateTime={start_datetime}
Delta function on calendarView in a user calendar
Apply the delta function on a range of events delimited by start and end date/times, in the specified user calendar:
To get incremental changes in a calendar view of the user's default calendar:
GET /me/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}To get incremental changes in a calendar view of the specified user calendar:
GET /me/calendars/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime} GET /users/{id}/calendars/{id}/calendarView/delta?startDateTime={start_datetime}&endDateTime={end_datetime}
Delta function on calendarView in a group calendar
- To get incremental changes in a calendar view of a group's calendar:
GET /groups/{id}/calendarView?startDateTime={start_datetime}&endDateTime={end_datetime}
Query parameters
Tracking changes incurs a round of one or more delta function calls. If you use any query parameter
(other than $deltatoken and $skiptoken), you must specify
it in the initial delta request. Microsoft Graph automatically encodes any specified parameters
into the token portion of the @odata.nextLink or @odata.deltaLink URL provided in the response. You only need to specify any desired query parameters once upfront.
In subsequent requests, simply copy and apply the @odata.nextLink or @odata.deltaLink URL from the previous response, as that URL already
includes the encoded, desired parameters.
| Query parameter | Type | Description |
|---|---|---|
| startDateTime | String | The start date and time of the time range, represented in ISO 8601 format. For example, "2019-11-08T19:00:00-08:00". The timezone is specified in the timezone offset portion of the parameter value, and is not impacted by the Prefer: outlook.timezone header if present. If no timezone offset is included in the value, it is interpreted as UTC.Optional for delta on events in a calendar. Required for delta on calendarView. |
| endDateTime | String | The end date and time of the time range, represented in ISO 8601 format. For example, "2019-11-08T20:00:00-08:00". The timezone is specified in the timezone offset portion of the parameter value, and is not impacted by the Prefer: outlook.timezone header if present. If no timezone offset is included in the value, it is interpreted as UTC.Not supported by delta on events in a calendar. Required for delta on calendarView. |
| $deltatoken | string | A state token returned in the @odata.deltaLink URL of the previous delta function call for the same calendar view, indicating the completion of that round of change tracking. Save and apply the entire @odata.deltaLink URL including this token in the first request of the next round of change tracking for that calendar view. |
| $skiptoken | string | A state token returned in the @odata.nextLink URL of the previous delta function call, indicating there are further changes to be tracked in the same calendar view. |
OData query parameters
Expect a delta function call on a calendarView to return the same properties you'd normally get from a
GET /calendarViewrequest. You cannot use$selectto get only a subset of those properties.The delta function doesn't support the following query parameters for events in a user calendar, or events in a calendarView:
$expand,$filter,$orderby,$search, and$select.
Request headers
| Name | Type | Description |
|---|---|---|
| Authorization | string | Bearer {token}. Required. |
| Content-Type | string | application/json. Required. |
| Prefer | string | odata.maxpagesize={x}. Optional. |
| Prefer | string | outlook.timezone={Time zone string}. Optional, UTC assumed if absent. |
Response
Delta function on events (preview)
If successful, this method returns a 200 OK response code and an event collection in the response body. Each event in the response contains only
the id, type, start and end properties for performance reasons. Use GET /events/{id} subsequently to expand any events from the response.
Delta function on calendarView
If successful, this method returns a 200 OK response code and an event collection in the response body.
Expect to get all the properties you'd normally get from a GET /calendarView request.
Within a round of delta function calls bound by the date range of a calendarView, you may find a delta call returning two types of events under @removed with the reason deleted:
- Events that are within the date range and that have been deleted since the previous delta call.
- Events that are outside the date range and that have been added, deleted, or updated since the the previous delta call.
Filter the events under @removed for the date range that your scenario requires.
Examples
Example 1: Delta function on events in a calendar (preview)
Request
The following example shows the initial sync request to get events in the signed-in user's default calendar, that occur on or after the specified startDateTime parameter. The initial request does not include any state token.
The request uses the Prefer: odata.maxpagesize header to limit the maximum number of events in each response to 1.
Continue calling the delta function by using the query returned in @odata.nextLink until you get a @odata.deltaLink in the response.
GET https://graph.microsoft.com/beta/me/calendar/events/delta?startDateTime=2020-06-12T00:00:00Z
Prefer: odata.maxpagesize=1
Response
If the request is successful, the response includes a state token, which is either a skipToken (in an @odata.nextLink response header) or a deltaToken (in an @odata.deltaLink response header). Respectively, they indicate whether you should continue with the round or you have completed getting all the changes for that round.
The response below shows a skipToken in an @odata.nextLink response header.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.nextLink":"https://graph.microsoft.com/beta/me/calendar/events/delta?$skiptoken=R0usmcdvmMu7jxWP8",
"value": [
{
"id": " AAMkADllMWMwNDkzLWJlY2EtNDIyOS1iZjAA=",
"type": "singleInstance",
"start": {
"DateTime": "2020-02-19T10:00:00.0000000",
"TimeZone": "UTC"
},
"end": {
"DateTime": "2020-02-19T11:00:00.0000000",
"TimeZone": "UTC"
}
}
]
}
Example 2: Delta function on calendarView
Request
The following example shows the initial sync request to get events in the specified calendar of the signed-in user, within the range of dates indicated by the calendarView. The initial request does not include any state token.
The request uses the Prefer: odata.maxpagesize header to limit the maximum number of events in each response to 2. Continue calling the delta function by using the query returned in @odata.nextLink until you get all the events in that calendar view, and a @odata.deltaLink
in the response.
GET https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?startDateTime=2020-06-01T00:00:00Z&endDateTime=2020-06-10T00:00:00Z
Prefer: odata.maxpagesize=2
Response
If the request is successful, the response includes a state token, which is either a skipToken (in an @odata.nextLink response header) or a deltaToken (in an @odata.deltaLink response header). Respectively, they indicate whether you should continue with the round or you have completed getting all the changes for that round.
The response below shows a skipToken in an @odata.nextLink response header.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(event)",
"@odata.nextLink": "https://graph.microsoft.com/beta/me/calendars/AAMkADI5M1BbeAAA=/calendarView/delta?$skiptoken=R0usmcdvmMu7jxWP8",
"value": [
{
"@odata.type": "#microsoft.graph.event",
"@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTgw==\"",
"createdDateTime": "2020-06-16T04:05:43.8668791Z",
"lastModifiedDateTime": "2020-06-16T04:08:27.354268Z",
"changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTgw==",
"categories": [],
"transactionId": null,
"originalStartTimeZone": "Pacific Standard Time",
"originalEndTimeZone": "Pacific Standard Time",
"uid": "040000008200E00074C5B7101A82E00800000000F088B8B95843D601000000000000000010000000165CD5547CFC9545B6492B261750B48C",
"reminderMinutesBeforeStart": 15,
"isReminderOn": false,
"hasAttachments": false,
"subject": "Summer party",
"bodyPreview": "",
"importance": "normal",
"sensitivity": "normal",
"isAllDay": false,
"isCancelled": false,
"isOrganizer": true,
"IsRoomRequested": false,
"AutoRoomBookingStatus": "None",
"responseRequested": true,
"seriesMasterId": null,
"showAs": "busy",
"type": "singleInstance",
"webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1QAAA%3D&exvsurl=1&path=/calendar/item",
"onlineMeetingUrl": null,
"isOnlineMeeting": false,
"onlineMeetingProvider": "unknown",
"allowNewTimeProposals": true,
"OccurrenceId": null,
"isDraft": false,
"recurrence": null,
"AutoRoomBookingOptions": null,
"onlineMeeting": null,
"id": "AAMkADI5MAAKkeE1QAAA=",
"responseStatus": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"body": {
"contentType": "html",
"content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\"> </p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"start": {
"dateTime": "2020-06-02T20:00:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-06-02T22:30:00.0000000",
"timeZone": "UTC"
},
"location": {
"displayName": "",
"locationType": "default",
"uniqueIdType": "unknown",
"address": {
"type": "unknown"
},
"coordinates": {}
},
"locations": [],
"attendees": [
{
"type": "required",
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"organizer": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
},
{
"@odata.type": "#microsoft.graph.event",
"@odata.etag": "W/\"Jdsb3FEkPk2qoUHCdliYowACwixTfw==\"",
"createdDateTime": "2020-06-16T04:06:18.386713Z",
"lastModifiedDateTime": "2020-06-16T04:08:19.5694048Z",
"changeKey": "Jdsb3FEkPk2qoUHCdliYowACwixTfw==",
"categories": [],
"transactionId": null,
"originalStartTimeZone": "Pacific Standard Time",
"originalEndTimeZone": "Pacific Standard Time",
"uid": "040000008200E00074C5B7101A82E0080000000060074BC55843D6010000000000000000100000002D33A89F36B10D43A12FD990B62858B2",
"reminderMinutesBeforeStart": 15,
"isReminderOn": true,
"hasAttachments": false,
"subject": "Summer party part 2",
"bodyPreview": "",
"importance": "normal",
"sensitivity": "normal",
"isAllDay": false,
"isCancelled": false,
"isOrganizer": true,
"IsRoomRequested": false,
"AutoRoomBookingStatus": "None",
"responseRequested": true,
"seriesMasterId": null,
"showAs": "busy",
"type": "singleInstance",
"webLink": "https://outlook.office365.com/owa/?itemid=AAMkADI5MAAKkeE1RAAA%3D&exvsurl=1&path=/calendar/item",
"onlineMeetingUrl": null,
"isOnlineMeeting": false,
"onlineMeetingProvider": "unknown",
"allowNewTimeProposals": true,
"OccurrenceId": null,
"isDraft": false,
"recurrence": null,
"AutoRoomBookingOptions": null,
"onlineMeeting": null,
"id": "AAMkADI5MAAKkeE1RAAA=",
"responseStatus": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"body": {
"contentType": "html",
"content": "<html>\r\n<head></head>\r\n<body lang=\"EN-US\" link=\"#0563C1\" vlink=\"#954F72\" style=\"\">\r\n<div class=\"WordSection1\">\r\n<p class=\"MsoNormal\"> </p>\r\n</div>\r\n</body>\r\n</html>\r\n"
},
"start": {
"dateTime": "2020-06-04T19:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"dateTime": "2020-06-04T22:30:00.0000000",
"timeZone": "UTC"
},
"location": {
"displayName": "",
"locationType": "default",
"uniqueIdType": "unknown",
"address": {
"type": "unknown"
},
"coordinates": {}
},
"locations": [],
"attendees": [
{
"type": "required",
"status": {
"response": "none",
"time": "0001-01-01T00:00:00Z"
},
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"organizer": {
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
}
]
}
Related content
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for