Announcing new Admin APIs to retrieve email subscriptions and widely shared reports

[talk2rick]

Power BI admin APIs are not only instrumental in helping our admins with many administrative tasks, but they are also critical in examining activities and usage patterns that ensure governance and satisfy compliance or auditing requirements. Several months ago, we rolled out a series of APIs to provide insight into who has access to what Power BI assets (see previous blog entries here and here). Today we are adding new APIs to provide an inventory of reports and dashboards that are delivered via email subscriptions, shared with the entire tenant, or published to web. Read on to learn more!

New APIs to retrieve report or dashboard email subscriptions

Email subscription for reports and dashboards is a popular feature that makes it easy for you to stay up to date about the data that matters the most to you. Going through the UI is cumbersome and analyzing the audit logs can only go back 90 days, so customers have been asking for an API to retrieve information about existing email subscriptions so that they can perform report access inventory and assess oversharing risk in a more efficient manner. Today we are pleased to release new APIs to Public Preview that provide you with this information.

How do these APIs help you as a Power BI service administrator? Sometimes reports or dashboard subscriptions do not go out as planned due to after-the-fact updates or data freshness issues. By using these APIs, you would be able to retrieve a list of subscriptions of impacted reports and notify subscribers.

3 separate APIs provide administrators with a list of subscriptions of a given report, a dashboard, or a Power BI user.

Below is an example of the API to retrieve a report’s subscriptions:

GET https://api.powerbi.com/v1.0/myorg/admin/reports/{reportID}/subscriptions

And the result looks like this:

{
  "value": [
    {
      "id": "<redacted>",
      "title": "2111080010000830_ASQL ",
      "artifactId": "<redacted>",
      "artifactDisplayName": "2111080010000830_ASQL",
      "artifactType": "PaginatedReport",
      "isEnabled": true,
      "frequency": "Monthly",
      "startDate": "11/16/2021 12:00:00 AM",
      "endDate": "11/16/2022 12:00:00 AM",
      "linkToContent": true,
      "previewImage": false,
      "owner": {
        "emailAddress": "<redacted>",
        "displayName": "Admin User",
        "identifier": "<redacted>",
        "graphId": "<redacted>",
        "principalType": "User"
      },
      "users": [
        {
          "emailAddress": "<redacted>",
          "displayName": "Admin User",
          "identifier": "<redacted>",
          "graphId": "<redacted>",
          "principalType": "User",
          "userType": "Member"
        },
        {
          "emailAddress": "<redacted>",
          "principalType": "User"
        }
      ]
    }
  ]
}

A few additional notes:

1. For the get subscriptions per report API, both Power BI report and Paginated report are supported
2. For the get subscriptions per user API, both UPN and graph ID are supported as input parameters
3. Also, for the get subscriptions per user API, a single response contains results for a single artifact type only. If there is more than one type of artifact in the response, then there will be a continuation token and URL for you to make additional calls. There can only be 3 types of artifacts that support email subscriptions: Power BI report, Power BI Paginated report, and Power BI dashboard
4. External subscribers or AAD guest users are supported too. In the “users” array, AAD guest users will be marked as “Guest” in the userType parameter

New APIs to retrieve widely shared reports

Power BI reports can be shared widely with the whole organization or publicly via publish to web. We have received consistent feedback that while users love the ease of sharing, administrators want an efficient way to keep inventory of these widely shared reports to meet compliance requirements. Today we are releasing to Public Preview new APIs to retrieve Power BI reports that are shared either with the whole organization or with the world via publish to web.

How do these APIs help you as a Power BI administrator? Perhaps you have been asked by your Infosec team to keep track of Power BI reports that are shared with the entire company or have an active embed code allowing public access. These new APIs make it a breeze to compile this information.

For example, to get a list of all the reports that have been shared with everyone in the company, simply call:

GET https://api.powerbi.com/v1.0/myorg/admin/widelySharedArtifacts/linksSharedToWholeOrganization

And the result looks like:

{
  "ArtifactAccessEntities": [
    {
      "artifactId": "<redacted>",
      "displayName": "Human Resources Sample",
      "artifactType": "Report",
      "accessRight": "ReadReshare",
      "shareType": "Link",
      "sharer": {
        "emailAddress": "<redacted>",
        "displayName": "Admin User",
        "identifier": "<redacted>",
        "graphId": "<redacted>",
        "principalType": "User"
      }
    },
...
  ]
}

If you want to get a list of all Power BI reports that have been published to web:

GET https://api.powerbi.com/v1.0/myorg/admin/widelySharedArtifacts/publishedToWeb

With the result that looks like the previous API:

{
  "ArtifactAccessEntities": [
    {
      "artifactId": "<redacted>",
      "displayName": "Incremental Refresh",
      "artifactType": "Report",
      "accessRight": "None",
      "shareType": "PublishToWeb",
      "sharer": {
        "emailAddress": "<redacted>",
        "displayName": "<redacted>",
        "identifier": "<redacted>",
        "graphId": "<redacted>",
        "principalType": "User"
      }
    }
  ]
}

Note that since only Power BI report can be widely shared via these two methods, it is the only artifact type that can be returned in the response of these APIs.

Learn more about this API on the documentation page.

Quick guidance for GetGroupsAsAdmin

Calling GetGroupsAsAdmin is a popular way of gathering information on Power BI workspaces but might not be the most performant if you have to expand the response to include artifacts contained within. If you need to query for or iterate through many workspaces, we recommend that you:

1. Make use of the $filter parameters “type” and “state”, since these two parameters have been optimized for performance, rather than retrieving all workspaces first and filtering on the response. If you need help on the proper syntax for using the $filter parameter, refer to this helpful link
2. Be mindful of using the $expand filter, since it tends to make the API call more expensive by potentially adding large number of artifacts and/or user metadata to the response
3. Leverage the Scanner API, which is non-blocking and designed to handle large number of workspaces without any of the usual API call limitation

Please note that due to the large volume of calls to GetGroupsAsAdmin API, we have reduced the usual 200 calls/hour/tenant limit to 50. We will also terminate calls longer than 30 seconds for a response in order to avoid degrading Power BI service reliability.

Stay tuned for an upcoming Power BI Dev Camp session some time in February, during which we’ll provide additional guidance on using Admin APIs. In the meantime, check out this awesome session by Ted on Building Solutions using Power Automate and the Power BI REST API.

That’s it! As always, leave any feedback or questions in the comments below. We are always looking forward to hearing from you!