Namespace: microsoft.graph
Get a list of thegroup's direct members. A group can have users, organizational contacts, devices, service principals and other groups as members. This operation is not transitive.
Important
This API has a known issue where service principals are not listed as group members in v1.0. As a workaround, use this API on thebeta endpoint or use the/groups/{id}?$expand=members API. For more information, see the relatedknown issue.
This API is available in the followingnational 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 permissionsonly if your app requires it. For details about delegated and application permissions, seePermission types. To learn more about these permissions, see thepermissions reference.
| Permission type | Least privileged permissions | Higher privileged permissions |
|---|
| Delegated (work or school account) | GroupMember.Read.All | Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All |
| Delegated (personal Microsoft account) | Not supported. | Not supported. |
| Application | GroupMember.Read.All | Directory.Read.All, Group.Read.All, Group.ReadWrite.All, GroupMember.ReadWrite.All |
Important
When an application queries a relationship that returns adirectoryObject type collection, if it doesn't have permission to read a certain resource type, members of that type are returned but with limited information. For example, only the@odata.type property for the object type and theid is returned, while other properties are indicated asnull. With this behavior, applications can request the least privileged permissions they need, rather than rely on the set ofDirectory.* permissions. For details, seeLimited information returned for inaccessible member objects.
In delegated scenarios, the signed-in user must also be assigned a supportedMicrosoft Entra role or a custom role with themicrosoft.directory/groups/members/read ormicrosoft.directory/groups/members/limitedRead role permission, ormicrosoft.directory/groups/hiddenMembers/read role permission to read hidden members. The following least privileged roles are supported for this operation:
- Group owners
- "Member" users
- "Guest" users - havelimited read permissions
- Directory Readers
- Directory Writers
- Groups Administrator
- User Administrator - Including hidden members
- Exchange Administrator - Including hidden members
- SharePoint Administrator - Including hidden members
- Intune Administrator - Including hidden members
- Teams Administrator - Including hidden members
- Yammer Administrator - Including hidden members
To list the members of a hidden membership group, theMember.Read.Hidden permission is also required.
HTTP request
GET /groups/{id}/members
Optional query parameters
This method supports the$filter,$count,$select,$search,$top, and$expandOData query parameters to help customize the response.
- OData cast is enabled. For example,
/groups/{id}/members/microsoft.graph.user retrieves group members that are users. $search is supported on thedisplayName anddescription properties only.- The use of query parameters with this API, except for
$expand, is supported only with advanced query parameters.$expand isn't supported with advanced query parameters. For more information, seeAdvanced query capabilities on directory objects.
The default and maximum page size is 100 and 999 group objects respectively.
Request headers
| Header | Value |
|---|
| Authorization | Bearer {token}. Required. Learn more aboutauthentication and authorization. |
| ConsistencyLevel | eventual. This header and$count are required when using the$search,$filter,$orderby, or OData cast query parameters. It uses an index that might not be up-to-date with recent changes to the object. |
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a200 OK response code and a collection ofdirectoryObject objects in the response body.
An attempt to filter by an OData cast that represents an unsupported member type returns a400 Bad Request error with theRequest_UnsupportedQuery code. For example,/groups/{id}}/members/microsoft.graph.group when the group is a Microsoft 365 group will return this error, because Microsoft 365 groups cannot have other groups as members.
Examples
Example 1: Get the direct membership in a group
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members
// 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=csharpvar result = await graphClient.Groups["{group-id}"].Members.GetAsync();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*// Dependenciesimport ( "context" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" //other-imports)// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=gomembers, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), nil)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest version. Current version is 6.xGraphServiceClient graphClient = new GraphServiceClient(requestAdapter);DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
const options = {authProvider,};const client = Client.init(options);let members = await client.api('/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members').get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
<?phpuse Microsoft\Graph\GraphServiceClient;$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get()->wait();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
# Code snippets are only available for the latest version. Current version is 1.xfrom msgraph import GraphServiceClient# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=pythonresult = await graph_client.groups.by_group_id('group-id').members.get()
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OKContent-type: application/json{ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#directoryObjects", "value": [ { "id": "11111111-2222-3333-4444-555555555555", "mail": "user1@contoso.com" } ]}
Example 2: Get only a count of all membership
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/$countConsistencyLevel: eventual
// 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=csharpawait graphClient.Groups["{group-id}"].Members.Count.GetAsync((requestConfiguration) =>{requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*// Dependenciesimport ( "context" abstractions "github.com/microsoft/kiota-abstractions-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups" //other-imports)headers := abstractions.NewRequestHeaders()headers.Add("ConsistencyLevel", "eventual")configuration := &graphgroups.ItemMembers$countRequestBuilderGetRequestConfiguration{Headers: headers,}// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=gographClient.Groups().ByGroupId("group-id").Members().Count().Get(context.Background(), configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest version. Current version is 6.xGraphServiceClient graphClient = new GraphServiceClient(requestAdapter);graphClient.groups().byGroupId("{group-id}").members().count().get(requestConfiguration -> {requestConfiguration.headers.add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
const options = {authProvider,};const client = Client.init(options);let int32 = await client.api('/groups/02bd9fd6-8f93-4758-87c3-1fb73740a315/members/$count').header('ConsistencyLevel','eventual').get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
<?phpuse Microsoft\Graph\GraphServiceClient;use Microsoft\Graph\Generated\Groups\Item\Members\Count\CountRequestBuilderGetRequestConfiguration;$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);$requestConfiguration = new CountRequestBuilderGetRequestConfiguration();$headers = ['ConsistencyLevel' => 'eventual',];$requestConfiguration->headers = $headers;$graphServiceClient->groups()->byGroupId('group-id')->members()->count()->get($requestConfiguration)->wait();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
# Code snippets are only available for the latest version. Current version is 1.xfrom msgraph import GraphServiceClientfrom msgraph.generated.groups.item.members.count.count_request_builder import CountRequestBuilderfrom kiota_abstractions.base_request_configuration import RequestConfiguration# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=pythonrequest_configuration = RequestConfiguration()request_configuration.headers.add("ConsistencyLevel", "eventual")await graph_client.groups.by_group_id('group-id').members.count.get(request_configuration = request_configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Response
The following example shows the response.
HTTP/1.1 200 OKContent-type: text/plain893
Example 3: Use OData cast to get only a count of user membership
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user/$countConsistencyLevel: eventual
// 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=csharpawait graphClient.Groups["{group-id}"].Members.GraphUser.Count.GetAsync((requestConfiguration) =>{requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*// Dependenciesimport ( "context" abstractions "github.com/microsoft/kiota-abstractions-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups" //other-imports)headers := abstractions.NewRequestHeaders()headers.Add("ConsistencyLevel", "eventual")configuration := &graphgroups.ItemMembersGraph.user$countRequestBuilderGetRequestConfiguration{Headers: headers,}// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=gographClient.Groups().ByGroupId("group-id").Members().GraphUser().Count().Get(context.Background(), configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest version. Current version is 6.xGraphServiceClient graphClient = new GraphServiceClient(requestAdapter);graphClient.groups().byGroupId("{group-id}").members().graphUser().count().get(requestConfiguration -> {requestConfiguration.headers.add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
const options = {authProvider,};const client = Client.init(options);let int32 = await client.api('/groups/{id}/members/microsoft.graph.user/$count').header('ConsistencyLevel','eventual').get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
<?phpuse Microsoft\Graph\GraphServiceClient;use Microsoft\Graph\Generated\Groups\Item\Members\Graph\User\Count\CountRequestBuilderGetRequestConfiguration;$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);$requestConfiguration = new CountRequestBuilderGetRequestConfiguration();$headers = ['ConsistencyLevel' => 'eventual',];$requestConfiguration->headers = $headers;$graphServiceClient->groups()->byGroupId('group-id')->members()->graphUser()->count()->get($requestConfiguration)->wait();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
# Code snippets are only available for the latest version. Current version is 1.xfrom msgraph import GraphServiceClientfrom msgraph.generated.groups.item.members.graph.user.count.count_request_builder import CountRequestBuilderfrom kiota_abstractions.base_request_configuration import RequestConfiguration# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=pythonrequest_configuration = RequestConfiguration()request_configuration.headers.add("ConsistencyLevel", "eventual")await graph_client.groups.by_group_id('group-id').members.graph_user.count.get(request_configuration = request_configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Response
The following example shows the response.
HTTP/1.1 200 OKContent-type: text/plain893
Example 4: Use $searchand OData cast to get user membership in groups with display names that contain the letters 'Pr' including a count of returned objects
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/groups/{id}/members/microsoft.graph.user?$count=true&$orderby=displayName&$search="displayName:Pr"&$select=displayName,idConsistencyLevel: eventual
// 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=csharpvar result = await graphClient.Groups["{group-id}"].Members.GraphUser.GetAsync((requestConfiguration) =>{requestConfiguration.QueryParameters.Count = true;requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };requestConfiguration.QueryParameters.Search = "\"displayName:Pr\"";requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*// Dependenciesimport ( "context" abstractions "github.com/microsoft/kiota-abstractions-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups" //other-imports)headers := abstractions.NewRequestHeaders()headers.Add("ConsistencyLevel", "eventual")requestCount := truerequestSearch := "\"displayName:Pr\""requestParameters := &graphgroups.ItemMembersGraph.userRequestBuilderGetQueryParameters{Count: &requestCount,Orderby: [] string {"displayName"},Search: &requestSearch,Select: [] string {"displayName","id"},}configuration := &graphgroups.ItemMembersGraph.userRequestBuilderGetRequestConfiguration{Headers: headers,QueryParameters: requestParameters,}// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=gographUser, err := graphClient.Groups().ByGroupId("group-id").Members().GraphUser().Get(context.Background(), configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest version. Current version is 6.xGraphServiceClient graphClient = new GraphServiceClient(requestAdapter);UserCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().graphUser().get(requestConfiguration -> {requestConfiguration.queryParameters.count = true;requestConfiguration.queryParameters.orderby = new String []{"displayName"};requestConfiguration.queryParameters.search = "\"displayName:Pr\"";requestConfiguration.queryParameters.select = new String []{"displayName", "id"};requestConfiguration.headers.add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
const options = {authProvider,};const client = Client.init(options);let user = await client.api('/groups/{id}/members/microsoft.graph.user').header('ConsistencyLevel','eventual').search('displayName:Pr').select('displayName,id').orderby('displayName').get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
<?phpuse Microsoft\Graph\GraphServiceClient;use Microsoft\Graph\Generated\Groups\Item\Members\Graph\User\UserRequestBuilderGetRequestConfiguration;$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);$requestConfiguration = new GraphUserRequestBuilderGetRequestConfiguration();$headers = ['ConsistencyLevel' => 'eventual',];$requestConfiguration->headers = $headers;$queryParameters = GraphUserRequestBuilderGetRequestConfiguration::createQueryParameters();$queryParameters->count = true;$queryParameters->orderby = ["displayName"];$queryParameters->search = "\"displayName:Pr\"";$queryParameters->select = ["displayName","id"];$requestConfiguration->queryParameters = $queryParameters;$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->graphUser()->get($requestConfiguration)->wait();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Import-Module Microsoft.Graph.GroupsGet-MgGroupMemberAsUser -GroupId $groupId -CountVariable CountVar -Sort "displayName" -Search '"displayName:Pr"' -Property "displayName,id" -ConsistencyLevel eventual
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
# Code snippets are only available for the latest version. Current version is 1.xfrom msgraph import GraphServiceClientfrom msgraph.generated.groups.item.members.graph.user.user_request_builder import UserRequestBuilderfrom kiota_abstractions.base_request_configuration import RequestConfiguration# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=pythonquery_params = UserRequestBuilder.UserRequestBuilderGetQueryParameters(count = True,orderby = ["displayName"],search = "\"displayName:Pr\"",select = ["displayName","id"],)request_configuration = RequestConfiguration(query_parameters = query_params,)request_configuration.headers.add("ConsistencyLevel", "eventual")result = await graph_client.groups.by_group_id('group-id').members.graph_user.get(request_configuration = request_configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OKContent-type: application/json{ "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users(displayName,id)", "@odata.count":7, "value":[ { "displayName":"Joseph Price", "id":"11111111-2222-3333-4444-555555555555" }, { "displayName":"Preston Morales", "id":"66666666-7777-8888-9999-000000000000" } ]}
Example 5: Use $filter to get group membership with a display name that starts with the letter 'A' including a count of returned objects
Request
The following example shows a request.
GET https://graph.microsoft.com/v1.0/groups/{id}/members?$count=true&$filter=startswith(displayName, 'a')ConsistencyLevel: eventual
// 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=csharpvar result = await graphClient.Groups["{group-id}"].Members.GetAsync((requestConfiguration) =>{requestConfiguration.QueryParameters.Count = true;requestConfiguration.QueryParameters.Filter = "startswith(displayName, 'a')";requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest major version. Current major version is $v1.*// Dependenciesimport ( "context" abstractions "github.com/microsoft/kiota-abstractions-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" graphgroups "github.com/microsoftgraph/msgraph-sdk-go/groups" //other-imports)headers := abstractions.NewRequestHeaders()headers.Add("ConsistencyLevel", "eventual")requestCount := truerequestFilter := "startswith(displayName, 'a')"requestParameters := &graphgroups.ItemMembersRequestBuilderGetQueryParameters{Count: &requestCount,Filter: &requestFilter,}configuration := &graphgroups.ItemMembersRequestBuilderGetRequestConfiguration{Headers: headers,QueryParameters: requestParameters,}// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=gomembers, err := graphClient.Groups().ByGroupId("group-id").Members().Get(context.Background(), configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
// Code snippets are only available for the latest version. Current version is 6.xGraphServiceClient graphClient = new GraphServiceClient(requestAdapter);DirectoryObjectCollectionResponse result = graphClient.groups().byGroupId("{group-id}").members().get(requestConfiguration -> {requestConfiguration.queryParameters.count = true;requestConfiguration.queryParameters.filter = "startswith(displayName, 'a')";requestConfiguration.headers.add("ConsistencyLevel", "eventual");});
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
const options = {authProvider,};const client = Client.init(options);let members = await client.api('/groups/{id}/members').header('ConsistencyLevel','eventual').filter('startswith(displayName, \'a\')').get();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
<?phpuse Microsoft\Graph\GraphServiceClient;use Microsoft\Graph\Generated\Groups\Item\Members\MembersRequestBuilderGetRequestConfiguration;$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);$requestConfiguration = new MembersRequestBuilderGetRequestConfiguration();$headers = ['ConsistencyLevel' => 'eventual',];$requestConfiguration->headers = $headers;$queryParameters = MembersRequestBuilderGetRequestConfiguration::createQueryParameters();$queryParameters->count = true;$queryParameters->filter = "startswith(displayName, 'a')";$requestConfiguration->queryParameters = $queryParameters;$result = $graphServiceClient->groups()->byGroupId('group-id')->members()->get($requestConfiguration)->wait();
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Import-Module Microsoft.Graph.GroupsGet-MgGroupMember -GroupId $groupId -CountVariable CountVar -Filter "startswith(displayName, 'a')" -ConsistencyLevel eventual
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
# Code snippets are only available for the latest version. Current version is 1.xfrom msgraph import GraphServiceClientfrom msgraph.generated.groups.item.members.members_request_builder import MembersRequestBuilderfrom kiota_abstractions.base_request_configuration import RequestConfiguration# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=pythonquery_params = MembersRequestBuilder.MembersRequestBuilderGetQueryParameters(count = True,filter = "startswith(displayName, 'a')",)request_configuration = RequestConfiguration(query_parameters = query_params,)request_configuration.headers.add("ConsistencyLevel", "eventual")result = await graph_client.groups.by_group_id('group-id').members.get(request_configuration = request_configuration)
For details about how toadd the SDK to your project andcreate an authProvider instance, see theSDK documentation.
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OKContent-type: application/json{ "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#directoryObjects", "@odata.count":76, "value":[ { "displayName":"AAD Contoso Users", "mail":"AADContoso_Users@contoso.com" } ]}