At a glance
- Availability: Experimental (how to enable).
- Auth: OAuth 2.0.
- Connection: A user authorizes the connection in the provider’s consent screen.
- Scopes:
https://analysis.windows.net/powerbi/api/Workspace.Read.All,https://analysis.windows.net/powerbi/api/Dataset.Read.All,https://analysis.windows.net/powerbi/api/Report.Read.All,offline_access. - Optional scopes:
https://analysis.windows.net/powerbi/api/Dataset.ReadWrite.All. - Docs: https://learn.microsoft.com/en-us/rest/api/power-bi/
Credentials
Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.Setup
- Get a Power BI account: Sign in at https://app.powerbi.com with a work or school account. For testing, you can create a free Microsoft 365 developer tenant or start a Power BI trial and publish a sample report.
- Register an Azure app: In the Azure portal, open Microsoft Entra ID > App registrations > New registration. Choose ‘Accounts in any organizational directory’ and add your callback URL as a Web redirect URI.
- Add Power BI delegated permissions: Under API permissions, select Add a permission > Power BI Service > Delegated permissions, and add Workspace.Read.All, Dataset.Read.All, and Report.Read.All (plus Dataset.ReadWrite.All if you want to trigger refreshes).
- Create a client secret: Under Certificates & secrets, create a client secret. Set MICROSOFT_CLIENT_ID to the Application (client) ID and MICROSOFT_CLIENT_SECRET to the secret value.
- Execute DAX Query requires the tenant setting ‘Dataset Execute Queries REST API’ (Power BI admin portal > Integration settings) to be enabled, and the user needs read and Build permissions on the dataset.
- Execute DAX Query is limited to one query per call, 100,000 rows or 1,000,000 values, and 15 MB of data per query.
- Dataset refreshes on shared capacities are limited to eight per day per dataset and only accept the notifyOption body field; Refresh Dataset needs the Dataset.ReadWrite.All scope.
- Power BI REST APIs refer to workspaces as ‘groups’.
Tools
| Tool | Access | Description |
|---|---|---|
| List Workspaces | Read | List Power BI workspaces (groups) the signed-in user has access to |
| List My Workspace Datasets | Read | List datasets in the signed-in user’s My workspace |
| List Workspace Datasets | Read | List datasets in a specific Power BI workspace |
| List My Workspace Reports | Read | List reports in the signed-in user’s My workspace |
| List Workspace Reports | Read | List reports in a specific Power BI workspace |
| Execute DAX Query | Read | Run a read-only DAX query against a dataset and return the resulting rows |
| Refresh Dataset | Write | Trigger a data refresh for a dataset in the signed-in user’s My workspace (returns 202 Accepted; the refresh runs asynchronously). Datasets in shared workspaces are not supported by this endpoint |
| Refresh Workspace Dataset | Write | Trigger a data refresh for a dataset in a specific workspace (returns 202 Accepted; the refresh runs asynchronously) |
| List Refresh History | Read | Get the refresh history of a dataset in the signed-in user’s My workspace - the way to follow up the 202 returned by Refresh Dataset |
| List Workspace Refresh History | Read | Get the refresh history of a dataset in a specific workspace, including status and failure error codes |
Example prompts
- List my Power BI workspaces and the datasets and reports inside each one.
- Run a DAX query against one of my Power BI datasets and summarize the result table.
- Trigger a refresh for my Power BI dataset and confirm it was accepted.