As noted in Roadmap item #109557, Microsoft just released the set of Graph API endpoint for Forms usage reports. The Microsoft Forms activity report has been available for a while now under the Reports > Usage > Forms section of the Microsoft 365 admin center, so having the corresponding APIs released is a bit overdue. For the time being, the set of endpoints is only available under the /beta version, even though the Roadmap item designates them as GA.
The official documentation has not been updated yet, however the $metadata document gives us all the information we need. A total of four endpoints have been introduced, using the familiar schema – two giving us the total count of activities and the count of activities per user, and two giving us detailed breakdown either for a specific date or a predetermined period of time. Below is the corresponding metadata exert:
<Function Name="getFormsUserActivityCounts" IsBound="true"> <Parameter Name="reportRoot" Type="graph.reportRoot" /> <Parameter Name="period" Type="Edm.String" Nullable="false" Unicode="false" /> <ReturnType Type="Edm.Stream" Nullable="false" /> </Function> <Function Name="getFormsUserActivityUserCounts" IsBound="true"> <Parameter Name="reportRoot" Type="graph.reportRoot" /> <Parameter Name="period" Type="Edm.String" Nullable="false" Unicode="false" /> <ReturnType Type="Edm.Stream" Nullable="false" /> </Function> <Function Name="getFormsUserActivityUserDetail" IsBound="true"> <Parameter Name="reportRoot" Type="graph.reportRoot" /> <Parameter Name="date" Type="Edm.Date" Nullable="false" /> <ReturnType Type="Edm.Stream" Nullable="false" /> </Function> <Function Name="getFormsUserActivityUserDetail" IsBound="true"> <Parameter Name="reportRoot" Type="graph.reportRoot" /> <Parameter Name="period" Type="Edm.String" Nullable="false" Unicode="false" /> <ReturnType Type="Edm.Stream" Nullable="false" /> </Function>
With this information at hand, we can query the corresponding Graph API endpoints and fetch the reports. For example, in order to get the total activities count, we can query the getFormsUserActivityCounts endpoint and provide the requested period value, i.e. period=’D90′:
GET https://graph.microsoft.com/beta/reports/getFormsUserActivityCounts(period='D90')
The output will be returned as JSON by default, but you can also request a CSV file if needed. The corresponding $format query parameter controls this behavior ($format=text/csv for the CSV file; $format=application/json for JSON).
Similarly, to get the detailed breakdown per user, we can use the getFormsUserActivityUserDetail endpoint, either for a given period or a specific date. As customary with other reports, the set of users returned will include accounts corresponding to shared mailboxes, resource mailboxes, and so on, so you might have to trim it a bit after fetching the data.
GET https://graph.microsoft.com/beta/reports/getFormsUserActivityUserDetail(period='D90')
The set of properties returned includes the reportRefreshDate, each user’s identifier (userPrincipalName), lastActivityDate for the user within the Forms app, and the count of created forms (createdCount) and form responses (respondedCount) for the requested period (reportPeriod), encapsulated in the formsUsageUserDetailsByPeriod property. Here’s an example JSON output from the Graph explorer:
And that’s pretty much all there is to it. Hopefully, we will see the set of Forms reports endpoint available under /v1.0 sometime this year 🙂