Using the Power BI REST APIs

The Power BI REST APIs provide service endpoints for embedding, administration, governance and user resources.

With Power BI REST APIs you can do the following:

  • Manage Power BI content

  • Perform admin operations

  • Embed Power BI Content

Note

  • Some of the Power BI APIs refer to workspaces as groups. Any reference to groups means that you're working with workspaces.

  • When accessing Power BI REST API, your request and response content and data may be processed by data centers in regions other than the home region of your Power BI tenant.

Scopes

To use the Power BI REST APIs, you need to register an Azure Active Directory (Azure AD) application in Azure. The Azure AD app establishes permissions for Power BI REST resources, and allows access to the Power BI REST APIs. To learn how to register an app, see Register an Azure AD application to use with Power BI.

After registering an Azure AD app, you can authenticate against it using either the Azure AD (v1.0; ADAL) or the Microsoft identity platform (v2.0; MSAL) endpoints. To learn more about how these authentication methods work, see Why update to Microsoft identity platform (v2.0)?

For more information about Power BI access permissions, see Permissions and consent in the Microsoft identity platform endpoint.

Using a service principal

Scopes are not required if you're using a service principal. Once you enable a service principal to be used with Power BI, the application's AD permissions don't take effect anymore. When using a service principal, the application's permissions are managed through the Power BI admin portal. For more information see Enable the Power BI service admin settings.

Adding scopes

To add permissions to your Azure AD app, follow these steps:

  1. Open your App in Azure.

  2. From the left, under Manage, select API permissions.

  3. Select Add a permission.

  4. In the Request API permissions window, select Power BI Service.

  5. Select Delegated permissions. A list of APIs is displayed.

  6. Expand the API you want to add permissions to, and select the permissions you want to add to it.

  7. Select Add permissions.

Removing scopes

To remove a permissions from your Azure AD app, follow these steps:

  1. Open your App in Azure.

  2. From the left, under Manage, select API permissions.

  3. Select the Context menu (permission ellipsis).

  4. Select Remove permission.

Throttling

Power BI uses throttling to maintain optimal performance and reliability. To prevent overuse of resources from single users, Power BI limits the number of API calls within a time window per user.

When a user sends a number of requests that exceeds a predetermined limit during a time window, Power BI throttles any further requests from that user for a short period.

When applications experience throttling, Power BI returns an HTTP status code 429 (Too many requests) with a Retry-After HTTP header in the response, indicating how many seconds the calling application has to wait before making a new request.

REST Operation groups

This table lists the Power BI REST API operation groups.

Operation group Description
Admin Operations for working with administrative tasks.
Apps Operations for working with Apps.
Available Features Operations that return available features.
Capacities Operations for working with capacities.
Dashboards Operations for working with dashboards.
Dataflow Storage Accounts Operations for working with dataflow storage accounts.
Dataflows Operations for working with dataflows.
Datasets Operations for working with datasets.
Embed Token Operations for working with embed tokens.
Gateways Operations for working with gateways.
Groups Operations for working with groups.
Imports Operations for working with imports.
Pipelines Operations for working with deployment pipelines.
Push Datasets Operations for working with push datasets.
Reports Operations for working with reports.
Template Apps Operations for working with Template Apps.
Users Operations for working with users.

Next steps