Table of contents

Supported queries, filters, and paging options | Graph API concepts

Jimaco Brannian|Last Updated: 3/28/2018
|
4 Contributors

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.

Important

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.

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:

RequestDescription
https://graph.windows.net/contoso.com/users?$orderby=displayName&api-version=1.6Returns a list of users ordered by their display name.
https://graph.windows.net/contoso.com/users?$orderby=displayName&$top=50&api-version=1.6Returns a list of the first 50 users ordered by their display name.

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:

RequestDescription
https://graph.windows.net/contoso.com/groups/1747ad35-dd4c-4115-8604-09b54f89277d?$expand=members&api-version=1.6Returns both the group object as well as its members.
https://graph.windows.net/contoso.com/users/derek@contoso.com?$expand=directReports&api-version=1.6Returns both the user object as well as its direct reports.
https://graph.windows.net/contoso.com/users/adam@contoso.com?$expand=manager&api-version=1.6Returns 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.

$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:

RequestDescription
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707402.....0000'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:

RequestDescription
https://graph.windows.net/contoso.com/users?$top=5&api-version=2013-11-08&$skiptoken=X'4453707.....00000'&previous-page=trueThe $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:

  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.

Top-Level ResourceQuery ResultsURI (for contoso.com)
Top-level resourcesReturns URI list of the top-level resources for directory services (also listed below)https://graph.windows.net/contoso.com?api-version=1.6
Company informationReturns company informationhttps://graph.windows.net/contoso.com/tenantDetails?api-version=1.6
ContactsReturns organizational contact informationhttps://graph.windows.net/contoso.com/contacts?api-version=1.6
UsersReturns user informationhttps://graph.windows.net/contoso.com/users?api-version=1.6
GroupsReturns group datahttps://graph.windows.net/contoso.com/groups?api-version=1.6
Directory RolesReturns all activated directory roles in the tenanthttps://graph.windows.net/contoso.com/directoryRoles?api-version=1.6
SubscribedSkusReturns the tenant's subscriptionshttps://graph.windows.net/contoso.com/subscribedSkus?api-version=1.6
Directory metadataReturns a Service Metadata Document that describes the data model (that is, structure and organization of directory resources)https://graph.windows.net/contoso.com/$metadata?api-version=1.6

Other query operations

The following table shows some additional example Graph API queries using contoso.com as the example tenant.

Query OperationURI (for contoso.com)
List all Users and Groupshttps://graph.windows.net/contoso.com/users?api-version=1.6

https://graph.windows.net/contoso.com/groups?api-version=1.6
Retrieve individual User by specifying the objectId or userPrincipalNamehttps://graph.windows.net/contoso.com/users/d1f67a6c-02c9-4fe5-81fb-58160ce24fe5?api-version=1.6

https://graph.windows.net/contoso.com/users/admin@contoso.com?api-version=1.6
Request and Filter for a user with displayName equal to “Jon Doe”https://graph.windows.net/contoso.com/users?$filter=displayName eq 'Jon Doe'&api-version=1.6
Request and Filter for specific users with firstName equal to “Jon”https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon'&api-version=1.6
Filter for givenName and surname values.https://graph.windows.net/contoso.com/users?$filter=givenName eq 'Jon' and surname eq 'Doe'&api-version=1.6
Retrieve individual group by specifying the objectIdhttps://graph.windows.net/contoso.com/groups/06790a81-0382-434c-b40e-216fa41bda21?api-version=1.6
Retrieve a user’s managerhttps://graph.windows.net/contoso.com/users/John.Smith@contoso.com/manager?api-version=1.6
Retrieve a user’s direct reports listhttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/directReports?api-version=1.6
Retrieve a list of links to a user’s direct reportshttps://graph.windows.net/contoso.com/users/3c4a09b0-a7b6-444e-9702-96983635a66e/$links/directReports?api-version=1.6
Retrieve membership list of a grouphttps://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/members?api-version=1.6
Retrieve a list of links to the members of a group.https://graph.windows.net/contoso.com/groups/3f575eef-bb04-44a5-a9af-eee9f547e3f9/$links/members?api-version=1.6
Retrieve a user’s group membership (not transitive)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/memberOf?api-version=1.6
Retrieve a list of the groups that the user is a member of (not transitive)https://graph.windows.net/contoso.com/users/ee6308f6-646a-4845-a4e1-57ac96ccc0c8/$links/memberOf?api-version=1.6
Request and filter for groups with displayName >= "az" and <= "dz"https://graph.windows.net/contoso.com/groups?$filter=displayName ge 'az' and displayName le 'dz'&api-version=1.6
Return all local account users in an Azure Active Directory B2C tenanthttps://graph.windows.net/contoso.com/users?filter=creationType eq 'LocalAccount'&api-version=1.6
Return local account user with the sign-in name "joe@example.com" from an Azure Active Directory B2C tenanthttps://graph.windows.net/contoso.com/users?$filter=signInNames/any(x:x/value eq 'joe@example.com')&api-version=1.6

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

© 2018 Microsoft