List users

Namespace: microsoft.graph

Retrieve a list of user objects.

Note: This request might have replication delays for users that were recently created, updated, or deleted.

This API is available in the following national cloud deployments.

Global service	US Government L4	US Government L5 (DOD)	China operated by 21Vianet
✅	✅	✅	✅

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegated (personal Microsoft account)	Not supported.
Application	User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Guests can't call this API. For more information about the permissions for member and guests, see What are the default user permissions in Microsoft Entra ID?

HTTP request

GET /users

Optional query parameters

This method supports the $count, $expand, $filter, $orderby, $search, $select, and $top OData query parameters to help customize the response. $skip isn't supported. You must specify $select=signInActivity or $filter=signInActivity while listing users, as the signInActivity property isn't returned by default.

Some queries are supported only when you use the ConsistencyLevel header set to eventual and $count. For more information, see Advanced query capabilities on directory objects. The $count and $search parameters are currently not available in Azure AD B2C tenants.

By default, only a limited set of properties are returned (businessPhones, displayName, givenName, id, jobTitle, mail, mobilePhone, officeLocation, preferredLanguage, surname, and userPrincipalName).To return an alternative property set, specify the desired set of user properties using the OData $select query parameter. For example, to return displayName, givenName, and postalCode, add the following to your query $select=displayName,givenName,postalCode.

Extension properties also support query parameters as follows:

Extension type	Comments
onPremisesExtensionAttributes 1-15	Returned only with $select. Supports $filter (eq, ne, and eq on null values).
Schema extensions	Returned only with $select. Supports $filter (eq, ne, and eq on null values).
Open extensions	Returned only with $expand, that is, users?$expand=extensions.
Directory extensions	Returned only with $select. Supports $filter (eq, ne, and eq on null values).

Certain properties can't be returned within a user collection. The following properties are only supported when retrieving a single user: aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, mailboxSettings.

The following properties aren't supported in personal Microsoft accounts and will be null: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.

Request headers

Header	Value
Authorization	Bearer {token} (required)
ConsistencyLevel	eventual. This header and $count are required when using $search, or in specific usage of $filter. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and collection of user objects in the response body. If a large user collection is returned, you can use paging in your app.

Attempting to use $select on the /users collection to retrieve properties that can't be returned within a user collection (for example, the request ../users?$select=aboutMe) returns a 501 Not Implemented error code.

Examples

Example 1: Get all users

Request

Here's an example of the request.

HTTP

GET https://graph.microsoft.com/v1.0/users

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.Users.GetAsync();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



users, err := graphClient.Users().Get(context.Background(), nil)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->users()->get()->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)


result = await graph_client.users.get()

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@contoso.com",
            "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
        },
        {
            "businessPhones": [
                "425-555-0100"
            ],
            "displayName": "MOD Administrator",
            "givenName": "MOD",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "425-555-0101",
            "officeLocation": null,
            "preferredLanguage": "en-US",
            "surname": "Administrator",
            "userPrincipalName": "admin@contoso.com",
            "id": "4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
        }
    ]
}

Example 2: Get a user account using a sign-in name

Request

Here's an example of the request.

Note: When filtering for an issuerAssignedId, you must supply both issuer and issuerAssignedId. However, the issuer value will be ignored in certain scenarios. For more information on filtering on identities, see objectIdentity resource type

HTTP

GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","id" };
	requestConfiguration.QueryParameters.Filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')" --select "displayName,id"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","id"},
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.filter("identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')")
	.select("displayName,id")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.filter('identities/any(c:c/issuerAssignedId eq \'j.smith@yahoo.com\' and c/issuer eq \'My B2C tenant\')')
	.select('displayName,id')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","id"];
$queryParameters->filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')";
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Property "displayName,id" -Filter "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		select = ["displayName","id"],
		filter = "identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

Note: The response object shown here might be shortened for readability.

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

Example 3: Get only a count of users

Request

Here's an example of the request. This request requires the ConsistencyLevel header set to eventual because $count is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/users/$count
ConsistencyLevel: eventual

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
await graphClient.Users.Count.GetAsync((requestConfiguration) =>
{
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users count get --consistency-level "eventual"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")

configuration := &graphusers.Users$countRequestBuilderGetRequestConfiguration{
	Headers: headers,
}

graphClient.Users().Count().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));

int int32 = graphClient.users().count()
	.buildRequest( requestOptions )
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let int32 = await client.api('/users/$count')
	.header('ConsistencyLevel','eventual')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new CountRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;


$graphServiceClient->users()->count()->get($requestConfiguration)->wait();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUserCount -ConsistencyLevel eventual 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)


request_configuration = CountRequestBuilder.CountRequestBuilderGetRequestConfiguration()
request_configuration.headers.add("ConsistencyLevel", "eventual")


await graph_client.users.count.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

HTTP/1.1 200 OK
Content-type: text/plain

893

Example 4: Use $filter and $top to get one user with a display name that starts with 'a' including a count of returned objects

Request

Here's an example of the request. This request requires the ConsistencyLevel header set to eventual and the $count=true query string because the request has both the $orderby and $filter query parameters. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

Response

Here's an example of the response.

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/v1.0/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Example 5: Use $filter to get all users with a mail that ends with 'a@contoso.com', including a count of returned objects, with the results ordered by userPrincipalName

Request

Here's an example of the request. This request requires the ConsistencyLevel header set to eventual and the $count=true query string because the request has both the $orderby and $filter query parameters, and also uses the endsWith operator. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "endswith(mail,'a@contoso.com')";
	requestConfiguration.QueryParameters.Orderby = new string []{ "userPrincipalName" };
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endswith(mail,'a@contoso.com')" --count "true" --orderby "userPrincipalName" --consistency-level "eventual"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "endswith(mail,'a@contoso.com')"
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
	Orderby: [] string {"userPrincipalName"},
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));

UserCollectionPage users = graphClient.users()
	.buildRequest( requestOptions )
	.filter("endswith(mail,'a@contoso.com')")
	.orderBy("userPrincipalName")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.filter('endswith(mail,\'a@contoso.com\')')
	.orderby('userPrincipalName')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "endswith(mail,'a@contoso.com')";
$queryParameters->orderby = ["userPrincipalName"];
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Filter "endswith(mail,'a@contoso.com')" -Sort "userPrincipalName" -CountVariable CountVar  -ConsistencyLevel eventual 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		filter = "endswith(mail,'a@contoso.com')",
		orderby = ["userPrincipalName"],
		count = True,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

Example 6: Use $search to get users with display names that contain the letters 'wa' including a count of returned objects

Request

Here's an example of the request. This request requires the ConsistencyLevel header set to eventual because $search is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Search = "\"displayName:wa\"";
	requestConfiguration.QueryParameters.Orderby = new string []{ "displayName" };
	requestConfiguration.QueryParameters.Count = true;
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa"" --count "true" --orderby "displayName" --consistency-level "eventual"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestSearch := "\"displayName:wa\""
requestCount := true

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Search: &requestSearch,
	Orderby: [] string {"displayName"},
	Count: &requestCount,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

LinkedList<Option> requestOptions = new LinkedList<Option>();
requestOptions.add(new HeaderOption("ConsistencyLevel", "eventual"));
requestOptions.add(new QueryOption("$search", "\"displayName:wa\""));

UserCollectionPage users = graphClient.users()
	.buildRequest( requestOptions )
	.orderBy("displayName")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.header('ConsistencyLevel','eventual')
	.search('displayName:wa')
	.orderby('displayName')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->search = "\"displayName:wa\"";
$queryParameters->orderby = ["displayName"];
$queryParameters->count = true;
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Search '"displayName:wa"' -Sort "displayName" -CountVariable CountVar  -ConsistencyLevel eventual 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		search = "\"displayName:wa\"",
		orderby = ["displayName"],
		count = True,
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

Example 7: Use $search to get users with display names that contain the letters 'wa' or the letters 'ad' including a count of returned objects

Request

Here's an example of the request. This request requires the ConsistencyLevel header set to eventual because $search is in the request. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

Note: The $count and $search query parameters are currently not available in Azure AD B2C tenants.

HTTP

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:ad"&$orderbydisplayName&$count=true
ConsistencyLevel: eventual

C#

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --search ""displayName:wa" OR "displayName:ad"" --count "true" --consistency-level "eventual"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Search '"displayName:wa" OR "displayName:ad"' -Orderbydisplayname =  -CountVariable CountVar  -ConsistencyLevel eventual 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "givenName":"Contoso Administrator",
      "mail":"'contosoadmin1@fabrikam.com",
      "userPrincipalName":"contosoadmin1_fabrikam.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

Example 8: Get guest (B2B) users from a specific tenant or domain by userPrincipalName

Request

Here's an example of the request. The userPrincipalName value for guest (B2B collaboration) users always contains the "#EXT#" identifier. For example, the userPrincipalName of a user in their home tenant is AdeleV@adatum.com. When you invite the user to collaborate in your tenant, contoso.com, their userPrincipalName in your tenant is "AdeleV_adatum.com#EXT#@contoso.com".

This request requires the ConsistencyLevel header set to eventual and the $count=true query string because the request includes the endsWith operator. For more information about the use of ConsistencyLevel and $count, see Advanced query capabilities on directory objects.

NOTE: You must encode the reserved character "#" in the userPrincipalName value as "%23" in the request URL. For more information, see Encoding special characters.

HTTP

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "id","displayName","mail","identities" };
	requestConfiguration.QueryParameters.Filter = "endsWith(userPrincipalName,'";
	requestConfiguration.Headers.Add("ConsistencyLevel", "eventual");
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --filter "endsWith(userPrincipalName,'" --select "id,displayName,mail,identities" --consistency-level "eventual"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-sdk-go/users"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


headers := abstractions.NewRequestHeaders()
headers.Add("ConsistencyLevel", "eventual")


requestFilter := "endsWith(userPrincipalName,'"

requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Select: [] string {"id","displayName","mail","identities"},
	Filter: &requestFilter,
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	Headers: headers,
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

Snippet not available

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$headers = [
		'ConsistencyLevel' => 'eventual',
	];
$requestConfiguration->headers = $headers;

$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["id","displayName","mail","identities"];
$queryParameters->filter = "endsWith(userPrincipalName,'";
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Property "id,displayName,mail,identities" -Filter "endsWith(userPrincipalName,'"  -ConsistencyLevel eventual 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		select = ["id","displayName","mail","identities"],
		filter = "endsWith(userPrincipalName,'",
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)
request_configuration.headers.add("ConsistencyLevel", "eventual")


result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

Example 9: Use $filter to get users who are assigned a specific license

Request

Here's an example of the request.

GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

Response

Here's an example of the response.

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

Example 10: Get the value of a schema extension for all users

In this example, the ID of the schema extension is ext55gb1l09_msLearnCourses.

Request

HTTP

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

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "ext55gb1l09_msLearnCourses" };
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --select "ext55gb1l09_msLearnCourses"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Select: [] string {"ext55gb1l09_msLearnCourses"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.select("ext55gb1l09_msLearnCourses")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.select('ext55gb1l09_msLearnCourses')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["ext55gb1l09_msLearnCourses"];
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Property "ext55gb1l09_msLearnCourses" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		select = ["ext55gb1l09_msLearnCourses"],
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

In the following response, the schema extension property ext55gb1l09_msLearnCourses is unassigned in two of the user objects.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)",
    "value": [
        {},
        {
            "ext55gb1l09_msLearnCourses": {
                "@odata.type": "#microsoft.graph.ComplexExtensionValue",
                "courseType": "Developer",
                "courseName": "Introduction to Microsoft Graph",
                "courseId": 1
            }
        },
        {}
    ]
}

Note: You can also apply $filter on the schema extension property to retrieve objects where a property in the collection matches a specified value. The syntax is /users?$filter={schemaPropertyID}/{propertyName} eq 'value'. For example, GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer'. The eq and not operators are supported.

Example 11: Get users including their last sign-in time

Request

Here's an example of the request. Details for the signInActivity property require a Microsoft Entra ID P1 or P2 license and the AuditLog.Read.All permission.

Note: When you specify $select=signInActivity or $filter=signInActivity while listing users, the maximum page size for $top is 120. Requests with $top set higher than 120 will return pages with up to 120 users. signInActivity supports $filter (eq, ne, not, ge, le) but not with any other filterable properties.

HTTP

GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity

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.Users.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Select = new string []{ "displayName","userPrincipalName","signInActivity" };
});

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users list --select "displayName,userPrincipalName,signInActivity"

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestParameters := &graphusers.UsersRequestBuilderGetQueryParameters{
	Select: [] string {"displayName","userPrincipalName","signInActivity"},
}
configuration := &graphusers.UsersRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

users, err := graphClient.Users().Get(context.Background(), configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

UserCollectionPage users = graphClient.users()
	.buildRequest()
	.select("displayName,userPrincipalName,signInActivity")
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

let users = await client.api('/users')
	.select('displayName,userPrincipalName,signInActivity')
	.get();

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PHP

<?php

// THIS SNIPPET IS A PREVIEW VERSION OF THE SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new UsersRequestBuilderGetRequestConfiguration();
$queryParameters = UsersRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->select = ["displayName","userPrincipalName","signInActivity"];
$requestConfiguration->queryParameters = $queryParameters;


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

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

PowerShell

Import-Module Microsoft.Graph.Users

Get-MgUser -Property "displayName,userPrincipalName,signInActivity" 

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Python

# THE PYTHON SDK IS IN PREVIEW. FOR NON-PRODUCTION USE ONLY

graph_client = GraphServiceClient(credentials, scopes)

query_params = UsersRequestBuilder.UsersRequestBuilderGetQueryParameters(
		select = ["displayName","userPrincipalName","signInActivity"],
)

request_configuration = UsersRequestBuilder.UsersRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.users.get(request_configuration = request_configuration)

For details about how to add the SDK to your project and create an authProvider instance, see the SDK documentation.

Response

Here's an example of the response.

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/v1.0/$metadata#users(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "1aecaf40-dc3a-461f-88a8-d06994e12898",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "id": "f0662ee5-84b1-43d6-8338-769cce1bc141",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200"
      }
    }
  ]
}