Accessing Microsoft Teams Usage Data in code with Microsoft Graph

A little while ago, Microsoft added some Teams Usage Reports to the Office 365 Portal. You can read more about it and see some screenshots on Tom Arbuthnot’s blog post.

If you’d rather take that data and consume it in a more programmatic fashion, then you can also access the same data using Microsoft Graph. This blog post covers how to do that.

In the same way that the Office 365 Portal has two reports, one for users and one for devices, there are two different data sets you can access – users and devices.

CSV & JSON

One of the nice things about these API calls is that they all work in the same way. By default, they will return CSV. In fact, what they’ll return is a 302 response (not 200), with a link to where you can download the CSV. That link is a unique, pre-authenticated link for the CSV you asked for. This is nice because if the CSV file is very large you may not want to actually download it initially, so having the option to decide what to do with it give some options for a nice user experience.

You can also get the data for any of these calls in JSON, by appending  ?$format=application/json to the end of the URL. That will return the data in JSON, and it’s what I’ve done for the screenshots in the examples below.

FYI: all these API calls are currently in Beta, which means they’re subject to change without notice.

Device Usage Reporting

There are 3 separate API calls you can make for device usage:

Get Teams Device Usage User Detail

This shows you, for each person, whether or not they’ve accessed Teams using a variety of different devices. There’s no indication of how much, just whether they have or not in the reporting period.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsDeviceUsageUserDetail(period='D7')?$format=application/json

or

GET https://graph.microsoft.com/beta/reports/getTeamsDeviceUsageUserDetail(date=2017-12-22)?$format=application/json

The first call is an aggregation of the last 7 days, split by user. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only). The second call allows you to specify an exact date within the last 30 days.

Regardless of the report or whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• User Principal Name (String)
• Last Activity Date (Date)
• Is Deleted (Boolean)
• Deleted Date (Date)
• Used Web (Boolean)
• Used Windows Phone (Boolean)
• Used iOS (Boolean)
• Used Mac (Boolean)
• Used Android Phone (Boolean)
• Used Windows (Boolean)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsdeviceusageuserdetail
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsdeviceusageuserdetail

Get Teams Device Usage User Counts

This shows you how many people accessed Teams per device for the reporting period. This is daily unique users per device type.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsDeviceUsageUserCounts(period='D7')?$format=application/json

The call is an aggregation of the last 7 days, split by day. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only).

Regardless of whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• Web (Int64)
• Windows Phone (Int64)
• Android Phone (Int64)
• iOS (Int64)
• Mac (Int64)
• Windows (Int64)
• Report Date (Date)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsdeviceusageusercounts
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsdeviceusageusercounts

Get Teams Device Usage Distribution User Counts

This shows you the number of unique users by device type over the selected reporting period.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsDeviceUsageDistributionUserCounts(period='D7')?$format=application/json

The call is an aggregation of the last 7 days. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only).

Regardless of whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• Web (Int64)
• Windows Phone (Int64)
• Android Phone (Int64)
• iOS (Int64)
• Mac (Int64)
• Windows (Int64)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsdeviceusagedistributionusercounts
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsdeviceusagedistributionusercounts

User Activity Reporting

There are 3 separate API calls you can make for Teams user activity reporting:

Get Teams User Activity User Detail

This shows you in a bit more detail how each user is using Microsoft Teams, giving you details about how many calls, messages, team chats etc they have made.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsUserActivityUserDetail(period='D7')?$format=application/json

or

GET https://graph.microsoft.com/beta/reports/getTeamsUserActivityUserDetail(date=2017-09-01)?$format=application/json

The first call is an aggregation of the last 7 days, split by user. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only). The second call allows you to specify an exact date within the last 30 days.

Regardless of the report or whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• User Principal Name (String)
• Last Activity Date (Date)
• Is Deleted (Boolean)
• Deleted Date (Date)
• Assigned Products (String collection)
• Team Chat Message Count (Int64)
• Private Chat Message Count (Int64)
• Call Count (Int64)
• Meeting Count (Int64)
• Has Other Action (Boolean)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsuseractivityuserdetail
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsuseractivityuserdetail

Get Teams User Activity Counts

This gives you an aggregated view of how much Teams activity is happening over the reporting period. You could use this to gauge how well Teams is being used in your organization.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsUserActivityCounts(period='D7')?$format=application/json

The call is an aggregation of the last 7 days, split by day. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only).

Regardless of whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• Report Date (Date)
• Team Chat Messages (Int64)
• Private Chat Messages (Int64)
• Calls (Int64)
• Meetings (Int64)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsuseractivitycounts
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsuseractivitycounts

Get Teams User Activity User Counts

This gives you an aggregated view of the number of users performing different Teams activity during the reporting period. This is subtly different from the previous one, which measured activity.

How to call:

GET https://graph.microsoft.com/beta/reports/getTeamsUserActivityUserCounts(period='D7')?$format=application/json

The call is an aggregation of the last 7 days, split by day. You can change this number to see aggregations for the previous 7, 30, 90, or 180 days (only).

Regardless of whether you’re returning CSV or JSON, the following fields are returned:

• Report Refresh Date (Date)
• Report Date (Date)
• Team Chat Messages (Int64)
• Private Chat Messages (Int64)
• Calls (Int64)
• Meetings (Int64)
• Other Actions (Int64)
• Report Period (String)

More info about the call (including Authentication and Permissions): https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/reportroot_getteamsuseractivityusercounts
More info about the return type: https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/teamsuseractivityusercounts

Use Graph Explorer to Try It

You can use Graph Explorer to see how these API calls look in your tenant. To do this:

Go to https://developer.microsoft.com/en-us/graph/graph-explorer:

At the top left, click to Sign in with Microsoft and log in. If you’re just trying things out and want to see something as quickly as possible, log in as a Office365 Administrator. Otherwise you’ll find you won’t have enough permissions and will need to modify your permission set (which will likely require administrator approval).

Once you’re signed in, you can simply copy the URLs of the API calls above and paste them into the Explorer address bar (not the browser address bar!) and click Run Query. Keep them outputting JSON if you want to see the data – the Graph Explorer doesn’t handle the CSV redirect response very well: