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.

This article applies to Azure AD Graph API. For similar info related to Microsoft Graph API, see query parameters and paging filters.

Addressing

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.

Supported query options

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.

$filter

The following general restrictions apply to queries that contain a filter:

• $filter cannot be combined with $orderby expressions.

• Filtering is not supported for queries on DirectoryRole or SubscribedSku directory objects.

• Not all properties of supported directory objects can be used in a filter expression. For information about filterable properties of supported types, see User, Group, and Contact.

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 'jonlawr@contoso.com' or mail eq 'jonlawr@contoso.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: https://graph.windows.net/contoso.com/users?api-version=2013-11-08&$filter=startswith(displayName,'Mary')

• 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

$orderby will sort the returned objects by the specified parameter. Example requests using the $orderby option:

The following restrictions apply to $orderby expressions:

• Two sort orders are currently supported: DisplayName for User and Group objects, and UserPrincipalName for User objects. The default sort order for users is by UserPrincipalName.

• $orderby cannot be combined with $filter expressions.

$expand

$expand will return an object and its linked objects. Example requests using the $expand option:

The following restrictions apply to $expand expressions:

• The maximum number of returned objects for a request is 20.

$top

$top is not supported for queries on DirectoryRole or SubscribedSku directory objects.

Paging support

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 following example request demonstrates paging backward:

The following steps demonstrate the request/response flow to page forward and backward:

1. 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.
2. To get the final 5 users, another request is made that contains the skip token returned from the previous response.
3. 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.
4. 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: https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6.

Sort order

• The result set of a query for all users is ordered by the UserPrincipalName property. For example: https://graph.windows.net/contoso.com/users?api-version=1.6.
• 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: https://graph.windows.net/contoso.com/groups?api-version=1.6.
• The order of the results of queries other than for top-level resources is indeterminate.

Common queries

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.

Other query operations

The following table shows some additional example Graph API queries using contoso.com as the example 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: https://graph.windows.net/contoso.com/users?$filter=displayName%20eq%20'Jon%20Doe'&api-version=1.6.

Additional resources

• Azure AD Graph API differential query
• Azure AD Graph API reference