Use delta query to track changes in Microsoft Graph data

Article
08/19/2023

Delta query enables applications to discover newly created, updated, or deleted entities without performing a full read of the target resource with every request. Microsoft Graph applications can use delta query to efficiently synchronize changes with a local data store.

Use delta query to track changes in a resource collection

The typical call pattern is as follows:

The application begins by calling a GET request with the delta function on the desired resource.
Microsoft Graph sends a response containing the requested resource and a state token.

a. If an @odata.nextLink URL is returned, there are additional pages of data to be retrieved in the session. This is true even if the current response may contain an empty result. The application continues making requests using the @odata.nextLink URL to retrieve all pages of data until a @odata.deltaLink URL is returned in the response.

b. If a @odata.deltaLink URL is returned, there is no more data about the existing state of the resource to be returned. For future requests, the application uses the @odata.deltaLink URL to learn about changes to the resource.
When the application needs to learn about changes to the resource, it makes a new request using the @odata.deltaLink URL received in step 2. This request may be made immediately after completing step 2 or when the application checks for changes.
Microsoft Graph returns a response describing changes to the resource since the previous request, and either a @odata.nextLink URL or a @odata.deltaLink URL.

Note

Resources stored in Microsoft Entra ID (such as users and groups) support "sync from now" scenarios. This allows you to skip steps 1 and 2 (if you're not interested in retrieving the full state of the resource) and ask for the latest @odata.deltaLink instead. Append $deltaToken=latest to the delta function and the response will contain a @odata.deltaLink and no resource data. Resources in OneDrive and SharePoint also support this feature. For resources in OneDrive and SharePoint, append token=latest instead.
The delta query function is generally referred to by appending /delta to the resource name. However, /delta is a shortcut for the fully qualified name /microsoft.graph.delta that you see in requests generated by the Microsoft Graph SDKs.
The initial request to the delta query function (no $deltaToken or $skipToken) will return the resources that currently exist in the collection. Resources that have been created and deleted prior to the initial delta query won't be returned. Updates made before the initial request are summarized on the resource returned as its latest state.
Note that $select and $deltaLink query parameters are supported for some Microsoft Entra resources so that customers can change the properties they want to track for an existing @odata.deltaLink. Delta queries with both $select and $skipToken will not be supported.

State tokens

A delta query GET response always includes a URL specified in a @odata.nextLink or @odata.deltaLink response header. The @odata.nextLink URL includes a $skipToken, and a @odata.deltaLink URL includes a $deltaToken.

These tokens are opaque to the client. The following details are what you need to know about them:

Each token reflects the state and represents a snapshot of the resource in that round of change tracking.
The state tokens also encode and include other query parameters (such as $select) specified in the initial delta query request. Therefore, it's not required to repeat them in subsequent delta query requests.
When carrying out delta query, you can copy and apply the @odata.nextLink or @odata.deltaLink URL to the next delta function call without having to inspect the contents of the URL, including its state token.

Optional query parameters

If a client uses a query parameter, it must be specified in the initial request. Microsoft Graph automatically encodes the specified parameter into the @odata.nextLink or @odata.deltaLink provided in the response. The calling application only needs to specify the query parameters once upfront. Microsoft Graph adds the specified parameters automatically for all subsequent requests.

Note the general limited support of the following optional query parameters:

$orderby

Do not assume a specific sequence of the responses returned from a delta query. Assume that the same item can show up anywhere in the @odata.nextLink sequence and handle that in your merge logic.
$top

The number of objects in each page can vary depending on the resource type and the type of changes made to the resource.

For the message resource, see details for query parameters support in a delta query.

For the user and group resources, there are restrictions on using some query parameters:

$expand is not supported.
$top is not supported.
$orderby is not supported.
If a $select query parameter is used, the parameter indicates that the client prefers to only track changes on the properties or relationships specified in the $select statement. If a change occurs to a property that is not selected, the resource for which that property changed does not appear in the delta response after a subsequent request.
$select also supports manager and members navigation properties for users and groups respectively. Selecting those properties allows tracking of changes to user's manager and group memberships.
Scoping filters allow you to track changes to one or more specific users or groups, filtering only by object ID. For example, the following request returns changes for the groups matching the IDs specified in the query filter.

https://graph.microsoft.com/beta/groups/delta/?$filter=id eq '477e9fc6-5de7-4406-bb2a-7e5c83c9ae5f' or id eq '004d6a07-fe70-4b92-add5-e6e37b8acd8e'

Resource representation in the delta query response

Newly created instances of a supported resource are represented in the delta query response using their standard representation.
Updated instances are represented by their id with at least the properties that have been updated, but additional properties may be included.
Relationships on users and groups are represented as annotations on the standard resource representation. These annotations use the format propertyName@delta. The annotations are included in the response of the initial delta query request.

Removed instances are represented by their id and an @removed object. The @removed object may include additional information about why the instance was removed. For example, "@removed": {"reason": "changed"}.

Possible @removed reasons can be changed or deleted.

changed indicates the item was deleted and can be restored from deletedItems.
deleted indicates the item is deleted and cannot be restored.

The @removed object can be returned in the initial delta query response and in tracked (deltaLink) responses. Clients using delta query requests should be designed to handle these objects in the responses.

Note

It's possible that a single entity will be contained multiple times in the response, if that entity was changed multiple times and under certain conditions. Delta queries enable your application to list all the changes, but can't ensure that entities are unified in a single response.

Supported resources

Delta query is currently supported for the following resources. Note that some resources which are available in v1.0 have their corresponding delta functions still in preview status, as indicated.

Resource collection	API
Applications	delta function of the application resource
Administrative units	delta function of the administrativeUnit resource
Call recordings (preview)	delta function (preview) of the callRecording resource, through the getAllRecordings function
Call transcripts (preview)	delta function (preview) of the callTranscript resource, through the getAllTranscripts function
Chat messages in a channel	delta function (preview) of the chatMessage resource
Device objects	delta function of the device resource
Directory roles	delta function of the directoryRole resource
Directory objects	delta function of the directoryObject resource
Drive items*	delta function of the driveItem resource
Education assignments	delta function of the educationAssignment resource
Education categories	delta function of the educationCategory resource
Education classes	delta function of the educationClass resource
Education schools	delta function of the educationSchool resource
Education users	delta function of the educationUser resource
Events in a calendar view (date range) of the primary calendar	delta function of the event resource
Groups	delta function of the group resource
List items*	delta function of the listItem resource
Mail folders	delta function of the mailFolder resource
Messages in a folder	delta function of the message resource
Organizational contacts	delta function of the orgContact resource
OAuth2PermissionGrants	delta function of the oauth2permissiongrant resource
Personal contact folders	delta function of the contactFolder resource
Personal contacts in a folder	delta function of the contact resource
Planner buckets (preview)	delta function (preview) of the plannerBucket resource
Planner items** (preview)	delta function (preview) of the all segment of plannerUser resource
Service principals	delta function of the servicePrincipal resource
To-do tasks in a task list	delta function of the todoTask resource
To-do task lists	delta function of the todoTaskList resource
Users	delta function of the user resource

* The usage pattern for OneDrive and SharePoint resources is similar to the other supported resources with some minor syntax differences. Delta query for drives and lists will be updated in the future to be consistent with other resource types. For more detail about the current syntax, see driveItem: delta and listItem: delta.

** The usage pattern for Planner resources is similar to other supported resources with a few differences. For details, see planner: delta.

Limitations

Properties stored outside of the main data store

Some resources contain properties that are stored outside of the main data store for the resource (for example, the user resource is mostly stored in the Microsoft Entra ID system, while some properties, like skills, are stored in SharePoint Online). Currently, those properties are not supported as part of change tracking; a change to one of those properties will not result in an object showing up in the delta query response. Currently, only the properties stored in the main data store trigger changes in the delta query.

To verify that a property can be used in delta query, try to perform a regular GET operation on the resource collection, and select the property you're interested in. For example, you can try the skills property on the users collection.

GET https://graph.microsoft.com/v1.0/users/?$select=skills

Because the skills property is stored outside of Microsoft Entra ID, the following is the response.

HTTP/1.1 501 Not Implemented
Content-type: application/json

{
    "error": {
        "code": "NotImplemented",
        "message": "This operation target is not yet supported.",
        "innerError": {
            "request-id": "...",
            "date": "2019-09-20T21:47:50"
        }
    }
}

This tells you that the skills property is not supported for delta query on the user resource.

Navigation properties are not supported. For example, you cannot track changes to the users collection that would include changes to their photo property; photo is a navigation property stored outside of the user entity, and changes to it do not cause the user object to be included in the delta response.

Processing delays

Expect varying delays between the time a change is made to a resource instance, which can be through an app interface or API, and the time the tracked change is reflected in a delta query response.

Sometimes the changes that have occurred to the object might not be indicated when you select the @odata.nextLink or the @odata.deltaLink. This is because some requests might have replication delays for objects that were recently created, updated, or deleted. Retry the @odata.nextLink or @odata.deltaLink after some time to retrieve the latest changes.

National clouds

Delta queries are only available for customers hosted on the public cloud, Microsoft Cloud for US Government, and Microsoft Graph China operated by 21Vianet.

Replays

Your application must be prepared for replays, which occur when the same change appears in subsequent responses. While delta query makes a best effort to reduce replays, they are still possible.

Synchronization reset

Delta query can return a response code of 410 (gone) and a Location header containing a request URL with an empty $deltaToken (same as the initial query). This is an indication that the application must restart with a full synchronization of the target tenant. This usually happens to prevent data inconsistency due to internal maintenance or migration of the target tenant.

Token duration

Delta tokens are only valid for a specific period before the client application needs to run a full synchronization again.

For directory objects, the limit is seven days.
For education objects (educationSchool, educationUser, and educationClass), the limit is seven days.
For Outlook entities (message, mailFolder, event, contact, contactFolder, todoTask, and todoTaskList), the upper limit is not fixed; it's dependent on the size of the internal delta token cache. While new delta tokens are continuously added in the cache, after the cache capacity is exceeded, the older delta tokens are deleted.

In case of an expired token, the service should respond with a 40X-series error with error codes such as syncStateNotFound. For more information, see Error codes in Microsoft Graph.

Prerequisites

The same permissions that are required to read a specific resource are also required to perform delta query on that resource.