Supported queries, filters, and paging options | Graph API concepts
This topic lists query options, filters, and paging operations that you can use with the Azure Active Directory (AD) Graph API. The final section gives some examples of common queries that you can perform with the Azure AD Graph API.
We strongly recommend that you use Microsoft Graph instead of Azure AD Graph API to access Azure Active Directory resources. Our development efforts are now concentrated on Microsoft Graph and no further enhancements are planned for Azure AD Graph API. There are a very limited number of scenarios for which Azure AD Graph API might still be appropriate; for more information, see the Microsoft Graph or the Azure AD Graph blog post in the Office Dev Center.
The queries below all address the tenant using a domain name. You can replace contoso.com with one of your tenant’s registered domain names, with your tenant's ID (GUID), or with the
MyOrganization alias (for delegated access). In some cases, you may be able to use the
me alias. For information about ways of addressing the tenant, see Operations overview.
The Graph supports the following query options: $filter, $orderby, $expand, $top, and $format. The following query options are not currently supported: $count, $inlinecount, and $skip.
The following general restrictions apply to queries that contain a filter:
$filter cannot be combined with $orderby expressions.
The following restrictions apply to filter expressions:
Logical operators: and and or are supported. For example:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=accountEnabled eq true and (userPrincipalName eq 'firstname.lastname@example.org' or mail eq 'email@example.com')
Comparison operators: eq (equal to), ge (greater than or equal to), and le (less than or equal to) are supported.
startswith is supported. For example:
any is supported when querying multi-valued properties. For example:
https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=userPrincipalName eq 'Mary@Contoso.com' or proxyAddresses/any(c:c eq 'smtp:Mary@Contoso.com')
Arithmetic operators: not supported.
Functions: not supported.
null values are not supported as an operand in filter expressions. For example, you cannot specify a null value to filter for unset properties.
To filter on a binary property such as the issuerUserId in userIdentities, the value must first be base64 encoded before it can be used in the $filter string.
$orderby will sort the returned objects by the specified parameter. Example requests using the $orderby option:
||Returns a list of users ordered by their display name.|
||Returns a list of the first 50 users ordered by their display name.|
The following restrictions apply to $orderby expressions:
$orderby cannot be combined with $filter expressions.
$expand will return an object and its linked objects. Example requests using the $expand option:
||Returns both the group object as well as its members.|
||Returns both the user object as well as its direct reports.|
||Returns both the user object as well as its manager.|
The following restrictions apply to $expand expressions:
- The maximum number of returned objects for a request is 20.
You can page forward and backward in the Graph. A response that contains paged results will include a skip token (odata.nextLink) that allows you to get the next page of results. This skip token can be combined with a previous-page=true query argument to page backwards.
The follow example request demonstrates paging forward:
||The $skiptoken parameter from the previous response is included, and allows you to get the next page of results.|
The following example request demonstrates paging backward:
||The $skiptoken parameter from the previous response is included. When this is combined with the &previous-page=true parameter, the previous page of results will be retrieved.|
The following steps demonstrate the request/response flow to page forward and backward:
- A request is made to get a list of the first 10 users out of 15. The response contains a skip token to indicate the final page of 10 users.
- To get the final 5 users, another request is made that contains the skip token returned from the previous response.
- To page backward, a request is made using the skip token returned in step 1 and the parameter &previous-page=true is added to the request.
- The response contains the previous (first) page of 10 users. In a different scenario where more pages are left, a new skip token would be returned. This new skip token can be added to the request along with &previous-page=true to page backward again.
The following restrictions apply to paged requests:
- The default page size is 100. The maximum page size is 999.
- Queries against roles do not support paging. This includes reading role objects themselves as well as role members.
- Resource listing, such as a search for all users in a tenant (/users), queries do support paging. For example:
https://graph.windows.net/contoso.com/users?api-version=1.6. However, across all types when a filter is applied, paging is not supported and only the first page of results is returned.
- Paging is not supported for link searches, such as for querying group members. For example:
- The result set of a query for all users is ordered by the UserPrincipalName property. For example:
- The result set of a query for all other top-level resources, such as Groups, Contacts, etc. is ordered by the objectId property. For example:
- The order of the results of queries other than for top-level resources is indeterminate.
The following sections show some examples of common queries you can perform with the Graph API.
Querying top-level resources
The following queries demonstrate how to access top-level resources with the Graph API using contoso.com as the example tenant. Note that an Authorization header containing a valid bearer token received from Azure AD will be required to run queries against a tenant.
|Top-Level Resource||Query Results||URI (for contoso.com)|
|Top-level resources||Returns URI list of the top-level resources for directory services (also listed below)||
|Company information||Returns company information||
|Contacts||Returns organizational contact information||
|Users||Returns user information||
|Groups||Returns group data||
|Directory Roles||Returns all activated directory roles in the tenant||
|SubscribedSkus||Returns the tenant's subscriptions||
|Directory metadata||Returns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)||
Other query operations
The following table shows some additional example Graph API queries using contoso.com as the example tenant.
|Query Operation||URI (for contoso.com)|
|List all Users and Groups||
|Retrieve individual User by specifying the objectId or userPrincipalName||
|Request and Filter for a user with displayName equal to “Jon Doe”||
|Request and Filter for specific users with firstName equal to “Jon”||
|Filter for givenName and surname values.||
|Retrieve individual group by specifying the objectId||
|Retrieve a user’s manager||
|Retrieve a user’s direct reports list||
|Retrieve a list of links to a user’s direct reports||
|Retrieve membership list of a group||
|Retrieve a list of links to the members of a group.||
|Retrieve a user’s group membership (not transitive)||
|Retrieve a list of the groups that the user is a member of (not transitive)||
|Request and filter for groups with displayName >= "az" and <= "dz"||
|Return all local account users in an Azure Active Directory B2C tenant||
|Return local account user with the sign-in name "firstname.lastname@example.org" from an Azure Active Directory B2C tenant||
Note: White space in the query string should be URL-encoded before sending a request. For example, the following query string,
https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6, should be URL encoded as: