List users
Namespace: microsoft.graph
Important
APIs under the /beta
version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
Retrieve a list of user objects.
This operation returns by default only a subset of the more commonly used properties for each user. These default properties are noted in the Properties section. To get properties that are not returned by default, do a GET operation for the user and specify the properties in a $select
OData query option.
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 |
Guest users cannot call this API. For more information about the permissions for member and guest users, see What are the default user permissions in Azure Active Directory?
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. The default and maximum page sizes are 100 and 999 user objects respectively. Some queries are supported only when you use the ConsistencyLevel header set to eventual
and $count
. For more information, see Advanced query capabilities on Azure AD directory objects. The $count
and $search
parameters are currently not available in Azure AD B2C tenants.
Certain properties cannot 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 are not supported in personal Microsoft accounts and will be null
: aboutMe, birthday, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills, streetAddress.
Retrieve extensions and associated data
Extension type | Comments |
---|---|
onPremisesExtensionAttributes 1-15 | Returned by default. Supports $filter (eq ). |
Schema extensions | Returned only with $select . Supports $filter (eq ). |
Open extensions | Returned only with $expand , that is, users?$expand=extensions . |
Directory extensions | Returned by default. Supports $filter (eq ). |
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 Azure AD directory objects. |
Request body
Do not 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.
Attempting to use $select
on the /users
collection to retrieve properties that cannot 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
The following is an example of the request.
GET https://graph.microsoft.com/beta/users
Response
The following is 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":"contoso1",
"mail":"'contoso1@gmail.com",
"mailNickname":"contoso1_gmail.com#EXT#",
"otherMails":["contoso1@gmail.com"],
"proxyAddresses":["SMTP:contoso1@gmail.com"],
"userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
}
]
}
Example 2: Get a user account using a sign-in name
Find a user account using a sign-in name (also known as a local account).
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 details on filtering on identities see objectIdentity resource type.
Request
The following is an example of the request.
GET https://graph.microsoft.com/beta/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')
Response
The following is 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 users including their last sign-in time
Request
The following is an example of the request. Details for the signInActivity property require an Azure AD Premium P1/P2 license and the AuditLog.Read.All permission.
Note: There's a known issue with retrieving the signInActivity property.
GET https://graph.microsoft.com/beta/users?$select=displayName,userPrincipalName,signInActivity
Response
The following is 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/beta/$metadata#users(displayName,userPrincipalName,signInActivity)",
"value": [
{
"displayName": "Adele Vance",
"userPrincipalName": "AdeleV@contoso.com",
"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",
"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"
}
}
]
}
Example 4: List the last sign-in time of users with a specific display name
Request
The following is an example of the request. Details for the signInActivity property require an Azure AD Premium P1/P2 license and the AuditLog.Read.All permission.
Note: There's a known issue with retrieving the signInActivity property.
GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity
Response
The following is 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/beta/users?$filter=startswith(displayName,'Eric')&$select=displayName,signInActivity",
"value": [
{
"displayName": "Eric Solomon",
"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"
}
}
]
}
Example 5: List the last sign-in time of users in a specific time range
Request
The following is an example of the request. Details for the signInActivity property require an Azure AD Premium P1/P2 license and the AuditLog.Read.All permission.
Note: There's a known issue with retrieving the signInActivity property.
GET https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z
Response
The following is 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/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z",
"value": [
{
"displayName": "Adele Vance",
"userPrincipalName": "AdeleV@contoso.com",
"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",
"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"
}
}
]
}
Example 6: Get only a count of users
Request
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users/$count
ConsistencyLevel: eventual
Response
The following is an example of the response.
HTTP/1.1 200 OK
Content-type: text/plain
893
Example 7: Use $filter and $top to get one user with a display name that starts with 'a' including a count of returned objects
Request
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual
Response
The following is 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/beta/$metadata#users",
"@odata.count":1,
"value":[
{
"displayName":"a",
"mail":"a@contoso.com",
"mailNickname":"a_contoso.com#EXT#",
"otherMails":["a@contoso.com"],
"proxyAddresses":["SMTP:a@contoso.com"],
"userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
}
]
}
Example 8: 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
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual
Response
The following is 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/beta/$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 9: Use $search to get users with display names that contain the letters 'wa' including a count of returned objects
Request
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual
Response
The following is 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/beta/$metadata#users",
"@odata.count":7,
"value":[
{
"displayName":"Oscar Ward",
"givenName":"Oscar",
"mail":"oscarward@contoso.com",
"mailNickname":"oscward",
"userPrincipalName":"oscarward@contoso.com"
}
]
}
Example 10: Use $search to get users with display names that contain the letters 'wa' or the letters 'ad' including a count of returned objects
Request
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users?$search="displayName:wa" OR "displayName:ad"&$orderby=displayName&$count=true
ConsistencyLevel: eventual
Response
The following is 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/beta/$metadata#users",
"@odata.count":7,
"value":[
{
"displayName":"Oscar Ward",
"givenName":"Oscar",
"mail":"oscarward@contoso.com",
"mailNickname":"oscward",
"userPrincipalName":"oscarward@contoso.com"
},
{
"displayName":"contosoAdmin1",
"mail":"'contosoadmin1@gmail.com",
"mailNickname":"contosoadmin1_gmail.com#EXT#",
"proxyAddresses":["SMTP:contosoadmin1@gmail.com"],
"userPrincipalName":"contosoadmin1_gmail.com#EXT#@microsoft.onmicrosoft.com"
}
]
}
Example 11: Use $filter to get users who are assigned a specific license
Request
The following is 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 Azure AD directory objects.
Note: The
$count
and$search
query parameters are currently not available in Azure AD B2C tenants.
GET https://graph.microsoft.com/beta/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)
Response
The following is an example of the response.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$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 12: Get the value of a schema extension for all users
In this example, the ID of the schema extension is ext55gb1l09_msLearnCourses
.
Request
GET https://graph.microsoft.com/beta/users?$select=ext55gb1l09_msLearnCourses
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/beta/$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'
. Theeq
andnot
operators are supported.
Feedback
Submit and view feedback for