How to use $count in the Graph API queries

Usage

Microsoft Graph supports optional query parameters that you can use to specify and control the amount of data returned in a response.

One of those parameters is $count which can be used either as a query parameter or as a URL segment.

Query parameter

When using as a query parameter withe the syntax $count=true, the response will include a count of total number of items for the specified query. The number of items is in the @odata.count property.

Example: The query GET /v1.0/users?$count=true will return the collection of users alongside with total number of users.

URL segment

When using as a URL segment, it retrieves the integer total of the collection. Additionally, it supports either $filter or $search query parameter.

Let's focus on $count as a URL segment in the rest of the article.

Examples

There are two cases when $count is useful. When you are only interested in the statistics of how many items a given collection contains, or if a item is included in a collection.


Note : For users, groups, applications, service principals, organizational contacts and administrative units collection the request requires ConsistencyLevel header set to eventual.


Users

Total number of users

GET /v1.0/users/$count

Total number of guest users

GET /v1.0/users/$count?$filter=userType eq 'Guest'

Number of users created this year

GET /v1.0/users/$count?$filter=createdDateTime ge 2024-01-01T00:00:00Z and createdDateTime le 2024-12-31T00:00:00Z

Number of users with specific given name

GET /v1.0/users/$count?$filter=givenName eq 'Martin'

Number of user's contacts

GET /v1.0/users/{userId}/contacts/$count

Number of devices owned by a user

GET /v1.0/users/{userId}/ownedDevices/$count

Number of devices with specific operating system owned by a user

GET /v1.0/users/{userId}/ownedDevices/$count?$filter=operatingSystem eq 'Windows'

Groups

Total number of groups

GET /v1.0/groups/$count

Number of mail-enabled groups

GET /v1.0/groups/$count?$filter=mailEnabled eq true

Number of security groups

GET /v1.0/groups/$count?$filter=securityEnabled eq true

Total number of members in a group

GET /v1.0/groups/{groupId}/members/$count

Check if a user is a member of a group

GET /v1.0/groups/{groupId}/members/$count?$filter=id eq '{userId}'

The result equals to 1 means that user is a member, 0 means that user is not a member.

Total number of owners in a group

GET /v1.0/groups/{groupId}/owners/$count

Check if a user is an owner of a group

GET /v1.0/groups/{groupId}/owners/$count?$filter=id eq '{userId}'

The result equals to 1 means that user is an owner, 0 means that user is not an owner.

Applications

Total number of applications

GET /v1.0/applications/$count

Number of single tenant applications

GET /v1.0/applications/$count?$filter=signInAudience eq 'AzureADMyOrg'

Number of multitenant applications

GET /v1.0/applications/$count?$filter=signInAudience eq 'AzureADMultipleOrgs'

Number of owners of an application

GET /v1.0/applications/{appId}/owners/$count

Check if a user is an owner of an application

GET /v1.0/applications/{appId}/owners/$count?$filter=id eq '{userId}'

The result equals to 1 means that user is an owner, 0 means that user is not an owner.

Service principals

Total number of service principals

GET /v1.0/servicePrincipals/$count

Check if there is an instance of an app

GET /v1.0/servicePrincipals/$count?$filter=appId eq '{appId}'

The result equals to 1 means that a service principal exists for an app, 0 means that a service principal doesn't exist.

Number of service principals where granting app role assignment is not required

GET /v1.0/servicePrincipals/$count?$filter=appRoleAssignmentRequired eq false

Check if a user is an owner of an application

GET /v1.0/servicePrincipals/{servicePrincipalId}/owners/$count?$filter=id eq '{userId}'

The result equals to 1 means that user is an owner, 0 means that user is not an owner.

Organizational contacts

Total number of organizational contacts

GET /v1.0/contacts/$count

Check whether a mail is an organizational contacts

GET /v1.0/contacts/$count?$filter=mail eq '{mail}'

The result equals to 1 means that an organizational contact exists, 0 means that it doesn't exist.

Number of groups where an organizational contact is a member

GET /v1.0/contacts/{contactId}/memberOf/$count

Check whether an organizational contact is a member of specific group

GET /v1.0/contacts/{contactId}/memberOf/$count?$filter=id eq '{groupId}'

The result equals to 1 means that an organizational contact is a member of a group, 0 means that it's not a member.

Administrative units

Total number of administrative units

GET /v1.0/directory/administrativeUnits/$count

Check whether an administrative unit with specific name already exists

GET /v1.0/directory/administrativeUnits/$count?$filter=displayName eq '{unitName}'

The result equals to 1 means that an administrative unit exists, 0 means that it doesn't exist.

Number of members of an administrative unit

GET /v1.0/directory/administrativeUnits/{unitId}/members/$count

Check whether a user is member of an administrative unit

GET /v1.0/directory/administrativeUnits/{unitId}/members/$count?$filter=id eq '{userId}'

Messages

Total number of all emails

GET /v1.0/me/messages/$count

Number of unread emails

GET /v1.0/me/messages/$count?$filter=isRead eq false

Number of drafts

GET /v1.0/me/messages/$count?$filter=isDraft eq true

Total number of emails in inbox folder

GET /v1.0/me/mailFolders/inbox/messages/$count

Number of messages in a conversation

GET /v1.0/me/messages/$count?$filter=conversationId eq '{conversationId}'

Number of attachments in a message

GET /v1.0/me/messages/{messageId}/attachments/$count

Number of the app roles a user has been granted

GET /v1.0/users/{userId}/appRoleAssignments/$count

Conclusion

$count can be used either as a query parameter or as a URL segment.

When using as a URL segment, it supports $filter or $search query parameter. The most common use case is to retrieve a number of items for a specific collection, or to check whether an item is present inside the collection.

0
Buy Me a Coffee at ko-fi.com
An error has occurred. This application may no longer respond until reloaded. Reload x