diff --git a/api-reference/beta/api/user-list.md b/api-reference/beta/api/user-list.md index f230e91d0d9..a206bb938f3 100644 --- a/api-reference/beta/api/user-list.md +++ b/api-reference/beta/api/user-list.md @@ -48,9 +48,17 @@ GET /users ## Optional query parameters -This method supports the `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, and `$top` [OData query parameters](/graph/query-parameters) to help customize the response. `$skip` isn't supported. The default and maximum page sizes are 100 and 999 user objects respectively, except when you specify `$select=signInActivity` or `$filter=signInActivity`. When `signInActivity` is selected or filtered on, the maximum page size is 999. 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](/graph/aad-advanced-queries). The `$count` and `$search` parameters are currently not available in Azure AD B2C tenants. +This method supports the `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, and `$top` [OData query parameters](/graph/query-parameters) to help customize the response. `$skip` isn't supported. The default and maximum page sizes are 100 and 999 user objects respectively, except when you specify `$select=signInActivity` or `$filter=signInActivity`. When `signInActivity` is selected or filtered on, the maximum page size is 500. 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](/graph/aad-advanced-queries). The `$count` and `$search` parameters are currently not available in Azure AD B2C tenants. -[Extension properties](/graph/extensibility-overview) also support query parameters, in some cases, only with advanced query parameters. For more information, see [support for `$filter` by extension properties](/graph/aad-advanced-queries#:~:text=The%20following%20table%20shows%20support%20for%20%24filter%20by%20extension%20properties%20on%20the%20user%20object.). + +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 cannot be returned within a user collection. The following properties are only supported when [retrieving a single user](./user-get.md): **aboutMe**, **birthday**, **hireDate**, **interests**, **mySite**, **pastProjects**, **preferredName**, **responsibilities**, **schools**, **skills**, **mailboxSettings**. @@ -327,7 +335,8 @@ Content-type: application/json The following example shows a request. > [!Note] -> Details for the **signInActivity** property require a Microsoft Entra ID P1 or P2 license and the `AuditLog.Read.All` permission. +> * Details for the **signInActivity** property require a Microsoft Entra ID P1 or P2 license and the `AuditLog.Read.All` permission. +> * When you specify `$select=signInActivity` or `$filter=signInActivity` when listing users, the maximum page size for `$top` is 500. Requests with `$top` set higher than 500 return pages with up to 500 users. The **signInActivity** property supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`) *but* not with any other filterable properties. # [HTTP](#tab/http) ```http -GET https://graph.microsoft.com/beta/users?filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z +GET https://graph.microsoft.com/beta/users?$filter=signInActivity/lastSignInDateTime le 2021-07-21T00:00:00Z ``` #### Response diff --git a/api-reference/beta/resources/signinactivity.md b/api-reference/beta/resources/signinactivity.md index 94052a15dd9..10773e09681 100644 --- a/api-reference/beta/resources/signinactivity.md +++ b/api-reference/beta/resources/signinactivity.md @@ -18,6 +18,8 @@ Provides the last interactive or non-interactive sign-in *attempt* time for a sp Effective December 1, 2023, the **lastSuccessfulSignInDateTime** property is available to provide the last *successful* sign-in time for a specific user, regardless of whether the sign-in was interactive or non-interactive. The data isn't backfilled for this property. +See an example of [getting the **signInActivity** details](../api/user-list.md#example-4-list-the-last-sign-in-time-of-users-with-a-specific-display-name). + ## Properties | Property | Type | Description | diff --git a/api-reference/v1.0/api/user-list.md b/api-reference/v1.0/api/user-list.md index dbbb148bcf3..c96e6d8555b 100644 --- a/api-reference/v1.0/api/user-list.md +++ b/api-reference/v1.0/api/user-list.md @@ -45,9 +45,7 @@ GET /users ## Optional query parameters -This method supports the `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, and `$top` [OData query parameters](/graph/query-parameters) to help customize the response. `$skip` isn't supported. You must specify `$select=signInActivity` or `$filter=signInActivity` while [listing users](../api/user-list.md), 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](/graph/aad-advanced-queries). The `$count` and `$search` parameters are currently not available in Azure AD B2C tenants. +This method supports the `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, and `$top` [OData query parameters](/graph/query-parameters) to help customize the response. `$skip` isn't supported. The default and maximum page sizes are 100 and 999 user objects respectively, except when you specify `$select=signInActivity` or `$filter=signInActivity`. When `signInActivity` is selected or filtered on, the maximum page size is 500. 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](/graph/aad-advanced-queries). 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](../resources/user.md) 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`. @@ -867,7 +865,7 @@ The following example shows a request. > [!Note] > * Details for the **signInActivity** property require a Microsoft Entra ID P1 or P2 license and the `AuditLog.Read.All` permission. -> * When you specify `$select=signInActivity` or `$filter=signInActivity` when listing users, the maximum page size for `$top` is 120. Requests with `$top` set higher than 120 return pages with up to 120 users. The **signInActivity** property supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`) *but* not with any other filterable properties. +> * When you specify `$select=signInActivity` or `$filter=signInActivity` when listing users, the maximum page size for `$top` is 500. Requests with `$top` set higher than 500 return pages with up to 500 users. The **signInActivity** property supports `$filter` (`eq`, `ne`, `not`, `ge`, `le`) *but* not with any other filterable properties. # [HTTP](#tab/http) | | |--|--| -|| | +|| | ### Identity and access reports best practices + Microsoft Entra reporting APIs are throttled when Microsoft Entra ID receives too many calls during a given timeframe from a tenant or app. Calls might also be throttled if the service takes too long to respond. If your requests still fail with a `429 Too Many Requests` error code despite applying the [best practices to handle throttling](/graph/throttling#best-practices-to-handle-throttling), try reducing the amount of data returned. Try these approaches first: - Use filters to target your query to just the data you need. If you only need a certain type of event or a subset of users, for example, filter out other events using the `$filter` and `$select` query parameters to reduce the size of your response object and the risk of throttling. - If you need a broad set of Microsoft Entra ID reporting data, use `$filter` on the **createdDateTime** to limit the number of sign-in events you query in a single call. Then, iterate through the next timespan until you have all the records you need. For example, if you're being throttled, you can begin with a call that requests three days of data and iterate with shorter timespans until your requests are no longer throttled. +- The `$select=signInActivity` parameter on the [List users](/graph/api/user-list) operation may cause stricter throttling than standard Microsoft Graph API calls. To avoid these limits, only use this parameter when necessary. If you need sign-in activity data, use `$top=500` to get the maximum 500 users per page instead of the default 100. This reduces the total number of API calls required.