Get incremental changes for groups

The delta query in Microsoft Graph lets you query for additions, deletions, or updates to supported resources, through a series of delta requests. For groups, the delta query enables you to discover changes without fetching the entire set of groups to compare changes.

Clients that synchronize groups with a local profile store can use the delta query for both their initial full synchronization along with subsequent incremental synchronizations. Typically, a client does an initial full synchronization of all the groups in a tenant, and then gets incremental changes to groups periodically.

Track changes to groups

Track user changes through one or more GET requests with the delta function. The GET request has the following characteristics:

• The delta function prepended to the URL path.
• A state token (deltatoken or skiptoken) from the previous GET delta function call.
• [Optional] Any supported query parameters

Example

This article shows a series of example requests to track changes to groups:

1. An initial request and response
2. A nextLink request and response
3. A final nextLink request and response
4. A deltaLink request and deltaLink response

Initial request

To track changes in the group resource, make a request and include the delta function as a URL segment.

Tip

/delta is a shortcut for the fully qualified name /microsoft.graph.delta. Requests generated by Microsoft Graph SDKs use the fully qualified name.

Take note of the following items:

• The optional $select query parameter is included in the request to demonstrate how query parameters are automatically included in future requests. If required, query parameters must be specified in the initial request.
  • Only properties included in $select are tracked for changes. If $select isn't specified, all properties of the object are tracked for changes.
• The optional $select query parameter is also used to show how group members can be retrieved together with group objects. This capability allows tracking of membership changes, such as when users are added or removed from groups.
• The initial request doesn't include a state token. State tokens are used in subsequent requests.

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","members" };
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get --select "displayName,description,members"

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","members"},
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "members"};
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.select('displayName,description,members')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","description","members"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->delta()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,members" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","members"],
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.groups.delta.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Initial response

If successful, this method returns 200 OK response code and group collection object in the response body. If the entire set of groups is too large to fit in one response, a @odata.nextLink containing a state token is included.

In this example, a @odata.nextLink URL is returned indicating there are more pages of data to be retrieved in the session. Notice the $skiptoken in the URL. The $select query parameter from the initial request is encoded into the @odata.nextLink URL.

The members@delta property is included in the All Company group and contains the two current members of the group. sg-HR doesn't contain that property because the group doesn't have any members.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups(displayName,description)",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
  "value": [
    {
      "displayName":"All Company",
      "description":"This is the default group for everyone in the network",
      "id":"c2f798fd-f95d-4623-8824-63aec21fffff",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "693acd06-2877-4339-8ade-b704261fe7a0"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    },
    {
      "displayName":"sg-HR",
      "description":"All HR personnel",
      "id":"ec22655c-8eb2-432a-b4ea-8b8a254bffff"
    }
  ]
}

nextLink request

The second request uses the @odata.nextLink from the previous response, which contains the skiptoken. Notice the $select parameter isn't visibly present as it's encoded and included in the token.

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ").GetAsDeltaGetResponseAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkiptoken := "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ"

requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.skiptoken('pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->delta()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Skiptoken "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		skiptoken = "pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjvB7XnF_yllFsCrZJ",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.groups.delta.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

nextLink response

The response contains another @odata.nextLink with a new skiptoken value, which indicates that more changes that were tracked for groups are available. Use the @odata.nextLink URL in subsequent requests until a @odata.deltaLink URL (in an @odata.deltaLink parameter) is returned in the final response, even if the value is an empty array.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=pqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
  "value": [
    {
      "displayName":"Mark 8 Project Team",
      "description":"Mark 8 Project Team",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "632f6bb2-3ec8-4c1f-9073-0027a8c68593"
               }
      ]
    },
    {
      "displayName":"Sales and Marketing",
      "description":"Sales and Marketing",
      "id":"421e797f-9406-4934-b778-4908421e3505",
      "members@delta": [
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "3c8ac7c4-d365-4df9-abfa-356a9dd7763c"
               },
               {
                   "@odata.type": "#microsoft.graph.user",
                   "id": "49320844-be99-4164-8167-87ff5d047ace"
               }
      ]
    }
  ]
}

Final nextLink request

The third request uses the latest @odata.nextLink returned from the last sync request.

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7").GetAsDeltaGetResponseAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestSkiptoken := "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7"

requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Skiptoken: &requestSkiptoken,
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.skiptoken('ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->skiptoken = "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->delta()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Skiptoken "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		skiptoken = "ppqwSUjGYvb3jQpbwVAwEL7yuI3dU1LecfkkfLPtnIjtQ5LOhVoS7qQG_wdVCHHlbQpga7",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.groups.delta.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Final nextLink response

When a @odata.deltaLink URL is returned, there's no more data about the existing state of group objects. For future requests, the application uses the @odata.deltaLink URL to learn about other changes to groups. Save the deltatoken and use it in the subsequent request URL to discover more changes to groups.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
    {
      "displayName":"All Employees",
      "id":"bed7f0d4-750e-4e7e-ffff-169002d06fc9"
    },
    {
      "displayName":"Remote living",
      "description":"Remote living",
      "id":"421e797f-9406-ffff-b778-4908421e3505"
    }
  ]
}

deltaLink request

Using the @odata.deltaLink from the last response, you get changes (additions, deletions, or updates) to groups since the last request. Changes include:

• Newly created group objects.
• Deleted group objects.
• Group objects for which a tracked property changed (for example, an updated displayName).
• Group objects for which member objects were added or removed.

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
// Note: The URI string parameter used with WithUrl() can be retrieved using the OdataNextLink or OdataDeltaLink property from a response object
var result = await graphClient.Groups.Delta.WithUrl("https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw").GetAsDeltaGetResponseAsync();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestDeltatoken := "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw"

requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Deltatoken: &requestDeltatoken,
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.groups.delta.DeltaRequestBuilder deltaRequestBuilder = new com.microsoft.graph.groups.delta.DeltaRequestBuilder("https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw", graphClient.getRequestAdapter());
com.microsoft.graph.groups.delta.DeltaGetResponse result = deltaRequestBuilder.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->deltatoken = "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->delta()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Deltatoken "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		deltatoken = "sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.groups.delta.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

deltaLink response

deltaLink response with an empty array

If there are no changes, a @odata.deltaLink is returned with no results - the value property is an empty array. Make sure to replace the previous link in the application with the new one for use in future calls.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": []
}

deltaLink response with changes

If there are changes, a collection of changed groups is included. The response also contains either a @odata.nextLink - in case there are multiple pages of changes to retrieve - or a @odata.deltaLink. Implement the same pattern of following the @odata.nextLink and persist the final @odata.deltaLink for future calls.

Note

This request might have replication delays for groups that were recently created, updated, or deleted. Retry the @odata.nextLink or @odata.deltaLink after some time to retrieve the latest changes.

Some things to note about the example response:

• The objects are returned with the same set of properties originally specified via the $select query parameter.
• Both changed and unchanged properties are included - the description property has a new value, while the displayName property hasn't changed.
• members@delta contains the following changes to the group membership.
  • The user with ID 632f6bb2-3ec8-4c1f-9073-0027a8c6859 was removed from the group by removing their membership, as described by the @removed property. Objects that are removed from a group through deletion of the object aren't detected by delta queries.
  • The second user with ID 37de1ae3-408f-4702-8636-20824abda004 was added to the group.

A group object can contain the @removed annotation in the following scenarios:

• When a group is deleted (Microsoft 365 groups), the item contains an annotation: @removed with value of "reason": "changed".
• When the group is permanently deleted (a security group or permanently deleting a Microsoft 365 group), the item contains an annotation: @removed with value of "reason": "deleted".
• When the group is created, or restored, there's no annotation.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.deltaLink":"https://graph.microsoft.com/v1.0/groups/delta?$deltatoken=sZwAFZibx-LQOdZIo1hHhmmDhHzCY0Hs6snoIHJCSIfCHdqKdWNZ2VX3kErpyna9GygROwBk-rqWWMFxJC3pw",
  "value": [
          {
              "displayName": "TestGroup3",
              "description": "A test group for change tracking",
              "id": "2e5807ce-58f3-4a94-9b37-ffff2e085957",
              "members@delta": [
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
                      "@removed": {
                          "reason": "deleted"
                      }
                  },
                  {
                      "@odata.type": "#microsoft.graph.user",
                      "id": "37de1ae3-408f-4702-8636-20824abda004"
                  }
              ]
          }
      ]
}

Paging through members in a large group

The members@delta property is included in group objects by default, when the $select query parameter isn't specified, or when the $select=members parameter is explicitly specified. For groups with many members, it's possible that all members can't fit into a single response. Implement the following pattern to handle such cases.

Note

This pattern applies to both the initial retrieval of group state as well as to subsequent calls to get delta changes.

Let's assume you're running the following delta query - either to capture the initial full state of groups, or later on to get delta changes:

HTTP

GET https://graph.microsoft.com/v1.0/groups/delta?$select=displayName,description,members

C#

// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups.Delta.GetAsDeltaGetResponseAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","description","members" };
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc groups delta get --select "displayName,description,members"

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphgroups.GroupsDelta()RequestBuilderGetQueryParameters{
	Select: [] string {"displayName","description","members"},
}
configuration := &graphgroups.GroupsDelta()RequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

delta, err := graphClient.Groups().Delta().GetAsDeltaGetResponse(context.Background(), configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

var result = graphClient.groups().delta().get(requestConfiguration -> {
	requestConfiguration.queryParameters.select = new String []{"displayName", "description", "members"};
});

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let delta = await client.api('/groups/delta')
	.select('displayName,description,members')
	.get();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PHP

<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Groups\Delta\DeltaRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new DeltaRequestBuilderGetRequestConfiguration();
$queryParameters = DeltaRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","description","members"];
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->groups()->delta()->get($requestConfiguration)->wait();

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

PowerShell

Import-Module Microsoft.Graph.Groups

Get-MgGroupDelta -Property "displayName,description,members" 

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

Python

from msgraph import GraphServiceClient
from msgraph.generated.groups.delta.delta_request_builder import DeltaRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = DeltaRequestBuilder.DeltaRequestBuilderGetQueryParameters(
		select = ["displayName","description","members"],
)

request_configuration = DeltaRequestBuilder.DeltaRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.groups.delta.get(request_configuration = request_configuration)

Read the SDK documentation for details on how to add the SDK to your project and create an authProvider instance.

1. Microsoft Graph might return a response that contains just one group object, with a large list of members in the members@delta property:

First page

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "632f6bb2-3ec8-4c1f-9073-0027a8c6859",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "37de1ae3-408f-4702-8636-20824abda004"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}

2. When you follow the @odata.nextLink, you might receive a response containing the same group object. The same property values are returned but the members@delta property now contains a different list of users.

Second page

HTTP/1.1 200 OK
Content-type: application/json
{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#groups",
  "@odata.nextLink":"https://graph.microsoft.com/v1.0/groups/delta?$skiptoken=<...>",
  "value": [
    {
      "displayName":"LargeGroup",
      "description":"A group containing thousands of users",
      "id":"2e5807ce-58f3-4a94-9b37-ffff2e085957",
      "members@delta": [
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "c08a463b-7b8a-40a4-aa31-f9bf690b9551",
              "@removed": {
                  "reason": "deleted"
              }
          },
          {
              "@odata.type": "#microsoft.graph.user",
              "id": "23423fa6-821e-44b2-aae4-d039d33884c2"
          },
          <...more users here...>
      ]
    }
    <...no more groups included - this group filled out the entire response...>
  ]
}

3. Eventually, the entire member list is returned in this fashion, and other groups start showing up in the response.

We recommend the following best practices to correctly handle this pattern:

• Always follow @odata.nextLink and locally merge each group's state: as you receive responses related to the same group, use them to build the full membership list in your application.
• Don't assume a specific sequence of the responses. Assume that the same group could show up anywhere in the @odata.nextLink sequence and handle that in your merge logic.

Related content

• Microsoft Graph delta query overview.