> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Power BI
> Query Power BI datasets with DAX, manage workspaces, reports, dashboards and refreshes from Agent Factory agents and Builder workflows, with per-user Microsoft Entra ID OAuth
The Power BI app provides read/write access to the [Microsoft Power BI REST API (v1.0)](https://learn.microsoft.com/en-us/rest/api/power-bi/) through its official endpoints. It can be consumed two ways: as a remote MCP server that **Agent Factory** agents call as tools, or as a Builder app whose instructions you call directly from DSUL. The MCP surface groups every operation into **eleven entity tools** (`workspaces`, `datasets`, `query`, `refresh`, `reports`, `dashboards`, `dataflows`, `gateways`, `imports`, `capacities`, `admin`), each driven by an `action` argument, and runs in the **tenant app-instance context** (it resolves the installing workspace's own credentials and authorizes the calling agent against a per-workspace allowlist). Authentication is **per-user OAuth2 authorization-code with PKCE against Microsoft Entra ID**: each end user signs in with their own Microsoft account, so every call runs with that user's Power BI permissions.
Run DAX queries against datasets, inspect schema, parameters and datasources, trigger and schedule refreshes
List, clone, rebind, export (PDF/PPTX/PNG) reports and dashboards, manage tiles and generate embed tokens
Manage workspaces (groups) and their users, gateways, dataflows, imports and capacities, plus tenant admin APIs
## Who is this for?
This connector is used by three different roles. Jump to the section that matches yours — each one is self-contained.
You build agents in **Agent Factory** and want them to query and manage Power BI. → *Agent builder* tab.
You run the platform and register the shared Microsoft Entra ID OAuth application. → *Platform admin setup* accordion below.
You write Builder automations (DSUL) that call Power BI operations directly. → *Workspace builder* tab.
## Prerequisites
* A **Microsoft Power BI** account (Power BI Pro / Premium Per User, or access to a Premium / Fabric capacity for paginated exports and the admin APIs).
* A **Microsoft Entra ID** (formerly Azure AD) tenant where you can register an OAuth **application** — done in the [Microsoft Entra admin center](https://entra.microsoft.com) under **App registrations**.
* The application must request delegated **Power BI service** permissions; the connector requests this default scope set:
```text theme={null}
https://analysis.windows.net/powerbi/api/.default
offline_access
openid
profile
```
* For tenant-wide admin operations (`admin` tool), the connected user must be a **Fabric / Power BI administrator**, and the Power BI tenant settings must allow service-principal / API access where applicable.
* To run DAX queries, the **"Dataset Execute Queries REST API"** must be enabled in the Power BI tenant settings.
**Goal:** two one-time tasks — (1) register the shared **Microsoft Entra ID OAuth application** and enter its credentials through the connector's configuration app so every workspace lets its users sign in with their own Microsoft account, and (2) expose Power BI as a reusable **capability** in AI Governance so agent builders can pick it without pasting endpoint URLs.
## 1. Configure the connector
In the [Microsoft Entra admin center](https://entra.microsoft.com), open **Identity > Applications > App registrations > New registration**. Choose a *Web* platform and set the single redirect URI to the connector's OAuth callback:
```text theme={null}
/workspaces/slug:powerbi/webhooks/oauthCallback
```
(e.g. `https://api.studio.prisme.ai/v2/workspaces/slug:powerbi/webhooks/oauthCallback` on production). Under **API permissions**, add the **Power BI Service** delegated permissions matching the scopes in *Prerequisites*, then create a **client secret**. Save the **Application (client) ID**, the **client secret** and the **directory (tenant) ID**.
Open the central `powerbi` workspace and launch its **Configuration app** — `/apps/powerbi` (e.g. `https://studio.prisme.ai/apps/powerbi`), also linked as `Configuration app` on the installed instance. Follow the in-app instructions to paste the **client ID**, **client secret** and **tenant** — the app stores them in the workspace's secrets for you. Do not edit Studio's raw Secrets by hand.
Each consuming workspace opens the same configuration app, then its users click **Connexion** to sign in with their own Microsoft account (PKCE authorization-code flow). Tokens are stored per user and refreshed automatically.
## 2. Declare the capability in AI Governance
Generic connectors — broad tool surfaces meant to be shared across many agents, like Power BI — are best exposed as a named **capability** in AI Governance. Agent builders then enable that capability on their agents instead of pasting a raw MCP endpoint.
Create (or edit) the **Power BI** capability.
Set the capability's MCP server URL to the connector's **MCP Endpoint**, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` in the scope is what lets the connector identify and authorize the calling agent.
Once created, the capability appears in the capability picker for agent builders in your organization, who enable it on their agents. Access to the catalog follows your organization's existing roles; there is no per-capability role grant.
From an agent that has the capability, trigger any tool. The user is prompted to connect once (Microsoft sign-in); subsequent calls reuse the stored token transparently and refresh it automatically.
Declaring the capability makes the connector **available**; it does not by itself authorize a specific agent. This connector follows the **tenant-context model** — which agents may actually call it is gated per-workspace by the **authorized-agents allowlist** in the configuration app (see the *Workspace builder* tab). There is also **no OAuth auth-config JSON** to attach in Governance: connect / status / disconnect are handled by the connector's own webhooks, wired automatically.
***
## Agent builder
**Goal:** let an agent you build in Agent Factory query and manage Power BI through MCP tools.
Before an agent can call the connector, a *Workspace builder* must have installed and configured the Power BI app in a workspace (see the *Workspace builder* tab), and a *Platform admin* must have registered the Microsoft Entra ID OAuth application (see the *Platform admin setup* accordion above).
This connector runs in the **tenant app-instance context**: your agent is authorized two ways at once — it is identified by the `agent_id` that Agent Factory injects through the capability *Scope*, and that agent must appear in the connector's **authorized-agents allowlist** (managed in the configuration app). The Power BI access token itself is resolved server-side from the connected user's OAuth session.
There are two ways to wire it up. Pick based on how much isolation you need.
## Option A — Enable the shared capability from the catalog
The fastest path: a *Platform admin* (or a workspace owner via the config app's one-click **Add to catalog** button) has already published a **Power BI** capability to your organization's catalog, so you just pick it.
Open the agent you want to extend and go to its capabilities / tools.
Browse the capability catalog, select **Power BI**, and enable it. The MCP endpoint URL and the *Scope* (`context_id,agent_id,user_id`) are already wired — nothing to paste, and the shared instance accepts every agent granted the capability, so there is no allowlist step on your side.
On the first tool call, an unconnected user is prompted to sign in — Agent Factory surfaces a `connect_url`. Subsequent calls reuse the stored token.
Convenient, but your agent runs against a **shared, platform-managed instance**: its Entra ID OAuth client is owned by someone else and the instance accepts every agent that is granted the capability. Prefer Option B for anything beyond quick experiments.
## Option B — Run it from your own workspace (recommended)
For production agents, install the connector in **your own workspace** and point the agent at *that* workspace's MCP endpoint.
**Prefer this mode for security.** Because the MCP runs in *your* app-instance context, the OAuth client, the per-user Power BI tokens and the authorized-agents allowlist are all **scoped to your workspace** — not shared platform-wide. You decide exactly which agents may call it and which Microsoft accounts back them, and a misconfiguration elsewhere can never expose your data. The shared catalog capability (Option A) is a broad surface many agents can reach; your own workspace is an isolated, least-privilege boundary.
Follow the *Workspace builder* tab: install **Power BI** in your workspace, open its **Configuration app**, and connect a Microsoft account.
In that workspace's config app, open **Authorized agents** and tick your agent (the **Install capability** button does this for you), or enable **Allow all agents**.
In your agent, add a capability pointing at **your workspace's MCP Endpoint** URL, and set its **Scope** to:
```text theme={null}
context_id,agent_id,user_id
```
The `agent_id` is what lets the connector identify and authorize your agent — without it, every call is rejected with an explicit "agent could not be identified" message. This *Scope* is separate from the Microsoft OAuth scopes.
On the first tool call, the user is prompted to sign in (or uses **Connexion** in the config app).
## Brief the agent in its system prompt
Whichever option you pick, wiring the capability is not enough — the agent must know the MCP exists and when to use it. Copy-pasteable starter:
```text theme={null}
You have access to the Power BI MCP server (tools: workspaces, datasets, query, refresh, reports, dashboards, dataflows, gateways, imports, capacities, admin). Each tool takes an `action` argument plus per-action parameters. Use the `query` tool (action executeQuery) to answer data questions with DAX against a dataset; use `datasets` getSchema first to discover tables and columns. Power BI's `groupId` is the workspace id and is optional (empty = "My workspace"). Prefer calling a tool over guessing, and confirm with the user before any destructive action (delete a dataset/report, cancel a refresh).
```
**Legacy AI Knowledge agents** (no native MCP picker): add the connector under **Advanced > Tools > MCP** and paste the **MCP Endpoint** URL. The agent still has to be allowlisted in the config app and its identity propagated so the connector can read its `agent_id`.
**Restricting to read-only (least privilege).** Power BI tools cover both reads and writes (refresh, take over, create/delete). The connector requests the `.default` scope, so the issued token inherits **exactly** the permissions granted to the Microsoft Entra **app registration** — it never forces write access. To allow only read access, grant the app only read-level **Power BI Service** delegated permissions (e.g. `Dataset.Read.All`, `Report.Read.All`, `Dashboard.Read.All`, `Workspace.Read.All`) instead of their `*.ReadWrite.All` variants. The connection still succeeds (the connection check is a read); any write call is then rejected by Power BI with `403 Forbidden`, surfaced to the agent as an error. This restriction lives on the Entra app, outside any tenant's reach — a hard guarantee.
## Available Tools
Each tool takes an `action` argument selecting the concrete operation, plus the per-action parameters. `groupId` (the workspace id) is optional on most data tools — empty means "My workspace".
| Tool | Description |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspaces` | Power BI workspaces (groups): list, create, delete and manage workspace users. Actions: `list`, `create`, `delete`, `listUsers`, `addUser`, `updateUser`, `deleteUser`. |
| `datasets` | Datasets (semantic models): list, get, delete, inspect/update datasources & parameters, get schema, take over, bind to a gateway. Actions: `list`, `get`, `delete`, `getTables`, `getDatasources`, `updateDatasources`, `getParameters`, `updateParameters`, `takeOver`, `bindToGateway`, `getSchema`. |
| `query` | Run a DAX query against a dataset and return result rows. Action: `executeQuery`. |
| `refresh` | Dataset refreshes: trigger, read history, get/update schedule, cancel an in-progress refresh. Actions: `trigger`, `history`, `getSchedule`, `updateSchedule`, `cancel`. |
| `reports` | Reports: list, get, delete, clone, rebind, get pages, export (PDF/PPTX/PNG), poll/download an export, update content, generate an embed token. Actions: `list`, `get`, `delete`, `clone`, `rebind`, `getPages`, `getPage`, `export`, `getExportStatus`, `getExportFile`, `updateContent`, `generateToken`. |
| `dashboards` | Dashboards & tiles: list, get, create dashboards; list/get/clone tiles; generate an embed token. Actions: `list`, `get`, `create`, `getTiles`, `getTile`, `cloneTile`, `generateToken`. |
| `dataflows` | Dataflows: list, get (model.json), delete, refresh, list transactions and datasources. Actions: `list`, `get`, `delete`, `refresh`, `getTransactions`, `getDatasources`. |
| `gateways` | On-premises data gateways: list, get, list/create/delete datasources, get a datasource status. Actions: `list`, `get`, `getDatasources`, `createDatasource`, `deleteDatasource`, `getDatasourceStatus`. |
| `imports` | Imports: list imports, get an import, create a temporary upload location (to publish a PBIX). Actions: `list`, `get`, `createUploadLocation`. |
| `capacities` | Premium / Fabric capacities: list capacities, get workloads, get refreshables. Actions: `list`, `getWorkloads`, `getRefreshables`. |
| `admin` | Tenant ADMIN APIs (require the connected user to be a Fabric/Power BI admin): list all workspaces/datasets/reports/dashboards/dataflows, get workspace users, query the activity log, list capacities, get modified workspaces, run the metadata scanner. Actions: `listGroups`, `getGroupUsers`, `listDatasets`, `listReports`, `listDashboards`, `listDataflows`, `getActivityEvents`, `listCapacities`, `getModifiedWorkspaces`, `scanWorkspaces`, `getScanStatus`, `getScanResult`. |
## Output Formats
Every tool accepts an `outputFormat` argument that controls the MCP response shape:
* **`verbose`** (default) — human-readable text optimized for LLM consumption
* **`structured`** — machine-readable JSON in `structuredContent`
* **`both`** — verbose text plus the structured payload
## Tool Details
### query
```json theme={null}
{
"name": "query",
"arguments": {
"action": "executeQuery",
"groupId": "f089354e-8366-4e18-aae3-a5f3c3b0c4d8",
"datasetId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
"daxQuery": "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)"
}
}
```
| Parameter | Required | Description |
| ---------------------- | ------------------ | ---------------------------------------------------------------------- |
| `action` | Yes | `executeQuery`. |
| `datasetId` | Yes | Target dataset (semantic model) id. |
| `daxQuery` | Yes (or `queries`) | A single DAX query string. Use `queries` for the raw multi-query body. |
| `groupId` | No | Workspace id; omit for "My workspace". |
| `impersonatedUserName` | No | UPN to impersonate for row-level security (admin / service principal). |
### datasets
```json theme={null}
{
"name": "datasets",
"arguments": {
"action": "getSchema",
"groupId": "f089354e-8366-4e18-aae3-a5f3c3b0c4d8",
"datasetId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229"
}
}
```
| Parameter | Required | Description |
| ----------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `action` | Yes | One of `list`, `get`, `delete`, `getTables`, `getDatasources`, `updateDatasources`, `getParameters`, `updateParameters`, `takeOver`, `bindToGateway`, `getSchema`. |
| `datasetId` | For all but `list` | Target dataset id. |
| `groupId` | No | Workspace id; omit for "My workspace". |
| `gatewayObjectId` | For `bindToGateway` | Gateway to bind the dataset to. |
| `updateDetails` | For `updateDatasources`/`updateParameters` | The update payload (datasource mappings or parameter values). |
`getTables` works **only** for Push-API datasets. On a normal import / DirectQuery semantic model use `getSchema` (column schema via DAX), or the `query` tool with `EVALUATE INFO.VIEW.TABLES()` / `EVALUATE INFO.VIEW.COLUMNS()`.
### refresh
```json theme={null}
{
"name": "refresh",
"arguments": {
"action": "trigger",
"groupId": "f089354e-8366-4e18-aae3-a5f3c3b0c4d8",
"datasetId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
"notifyOption": "MailOnFailure"
}
}
```
| Parameter | Required | Description |
| -------------- | ------------ | ------------------------------------------------------------------------------- |
| `action` | Yes | One of `trigger`, `history`, `getSchedule`, `updateSchedule`, `cancel`. |
| `datasetId` | Yes | Target dataset id. |
| `groupId` | No | Workspace id; omit for "My workspace". |
| `refreshId` | For `cancel` | Id of the in-progress refresh to cancel. |
| `notifyOption` | No | Completion notification: `MailOnFailure`, `MailOnCompletion`, `NoNotification`. |
### reports
```json theme={null}
{
"name": "reports",
"arguments": {
"action": "export",
"groupId": "f089354e-8366-4e18-aae3-a5f3c3b0c4d8",
"reportId": "5b218778-e7a5-4d73-8187-f10824047715",
"format": "PDF"
}
}
```
| Parameter | Required | Description |
| ------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | One of `list`, `get`, `delete`, `clone`, `rebind`, `getPages`, `getPage`, `export`, `getExportStatus`, `getExportFile`, `updateContent`, `generateToken`. |
| `reportId` | For all but `list` | Target report id. |
| `groupId` | No | Workspace id; omit for "My workspace". |
| `format` | For `export` | `PDF`, `PPTX` or `PNG` (export is async — poll `getExportStatus`, then `getExportFile`). |
| `targetWorkspaceId` / `targetModelId` | For `clone` / `rebind` | Destination workspace / dataset to clone into or rebind to. |
### dashboards
```json theme={null}
{
"name": "dashboards",
"arguments": {
"action": "generateToken",
"groupId": "f089354e-8366-4e18-aae3-a5f3c3b0c4d8",
"dashboardId": "69ffaa6c-b36d-4d01-96f5-1ed67c64d4af",
"accessLevel": "View"
}
}
```
| Parameter | Required | Description |
| ------------- | --------------------------- | ------------------------------------------------------------------------------------ |
| `action` | Yes | One of `list`, `get`, `create`, `getTiles`, `getTile`, `cloneTile`, `generateToken`. |
| `dashboardId` | For all but `list`/`create` | Target dashboard id. |
| `groupId` | No | Workspace id; omit for "My workspace". |
| `tileId` | For `getTile`/`cloneTile` | Target tile id. |
| `accessLevel` | For `generateToken` | Embed token access level, e.g. `View`. |
### admin
```json theme={null}
{
"name": "admin",
"arguments": {
"action": "getActivityEvents",
"startDateTime": "2026-06-01T00:00:00Z",
"endDateTime": "2026-06-01T23:59:59Z"
}
}
```
| Parameter | Required | Description |
| ------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | Yes | One of `listGroups`, `getGroupUsers`, `listDatasets`, `listReports`, `listDashboards`, `listDataflows`, `getActivityEvents`, `listCapacities`, `getModifiedWorkspaces`, `scanWorkspaces`, `getScanStatus`, `getScanResult`. |
| `groupId` | For `getGroupUsers` and per-workspace listings | Workspace id. |
| `startDateTime` / `endDateTime` | For `getActivityEvents` | ISO 8601 window (same UTC day, per the Power BI admin API). |
| `workspaces` | For `scanWorkspaces` | Array of workspace ids to scan. |
| `scanId` | For `getScanStatus`/`getScanResult` | Id returned by `scanWorkspaces`. |
All `admin` actions require the **connected user to be a Fabric / Power BI administrator**; otherwise the provider returns `401` / `403`.
## Workspace builder
## Installation
1. Go to **Apps** in your workspace
2. Search for **Power BI** and install it
3. Open the **Configuration app** (the link auto-populated on install) to connect a Microsoft account and manage the authorized-agents allowlist
## Configuration
| Field | Description |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Configuration app** | Auto-populated on install — open this link to register the Microsoft Entra ID OAuth credentials, connect a Microsoft account, and manage the authorized-agents allowlist. |
The configuration app drives everything; the app instance itself has no per-field credential form. Authentication is a single mode:
| Auth mode | What you provide | Best for |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| Per-user OAuth2 (PKCE) | Microsoft Entra ID **client ID + secret + tenant** (entered once in the config app), then each user clicks **Connexion** | Every workspace — each user acts with their own Power BI permissions |
Credentials are provisioned into the workspace's Secrets by the `onInstall` flow and resolved server-side. The agent allowlist (**Authorized agents**) gates which Agent Factory agents may call the MCP endpoint — see the *Agent builder* tab. Per-user tokens are refreshed automatically; a revoked token drops the connection and the user is asked to reconnect.
## Available Instructions
Every instruction resolves credentials from the workspace configuration. Operations are grouped by Power BI resource; the MCP server exposes the same operations behind the eleven entity tools (see the *Agent builder* tab). `groupId` is the workspace id and is optional on data operations (omit for "My workspace").
### Workspaces (groups)
| Instruction | Description | Returns |
| --------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `listWorkspaces` | List the workspaces (groups) the user can access. | `{ value: [{ id, name, isReadOnly, type }] }` |
| `createWorkspace` | Create a workspace by `name`. | The created group `{ id, name }`. |
| `deleteWorkspace` | Delete a workspace by `groupId`. | Empty (HTTP 200). |
| `listWorkspaceUsers` | List the users/roles of a workspace by `groupId`. | `{ value: [{ identifier, principalType, groupUserAccessRight }] }` |
| `addWorkspaceUser` | Grant a user/group access: `user` = `{ identifier, principalType, groupUserAccessRight }`. | Empty (HTTP 200). |
| `updateWorkspaceUser` | Change a user's access right on a workspace. | Empty (HTTP 200). |
| `deleteWorkspaceUser` | Remove a user from a workspace by `emailAddress`/`identifier`. | Empty (HTTP 200). |
### Datasets (semantic models)
| Instruction | Description | Returns |
| -------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
| `listDatasets` | List datasets in a workspace (or "My workspace"). | `{ value: [{ id, name, configuredBy, isRefreshable }] }` |
| `getDataset` | Fetch one dataset by `datasetId`. | A Dataset resource `{ id, name, webUrl, … }`. |
| `deleteDataset` | Delete a dataset by `datasetId`. | Empty (HTTP 200). |
| `getDatasetSchema` | Discover the model's column schema via DAX. | `{ tables: [{ name, columns: [{ name, dataType }] }] }` |
| `getDatasetTables` | List push-API dataset tables (Push datasets only). | `{ value: [{ name, columns }] }` |
| `getDatasetDatasources` | List a dataset's datasources. | `{ value: [{ datasourceType, connectionDetails, … }] }` |
| `updateDatasetDatasources` | Remap datasources via `updateDetails`. | Empty (HTTP 200). |
| `getDatasetParameters` | List the dataset's M parameters. | `{ value: [{ name, type, currentValue }] }` |
| `updateDatasetParameters` | Set parameter values via `updateDetails`. | Empty (HTTP 200). |
| `takeOverDataset` | Take over a dataset (bind it to the calling user). | Empty (HTTP 200). |
| `bindDatasetToGateway` | Bind a dataset to a gateway by `gatewayObjectId`. | Empty (HTTP 200). |
### DAX query
| Instruction | Description | Returns |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `executeQueries` | Run a DAX query (`daxQuery`, or a raw `queries` body) against `datasetId`; `impersonatedUserName` for RLS. | `{ results: [{ tables: [{ rows: [ {…} ] }] }] }` |
### Refreshes
| Instruction | Description | Returns |
| ----------------------- | ------------------------------------------------------------------------ | --------------------------------------------------------- |
| `refreshDataset` | Trigger a refresh of `datasetId`; `notifyOption` controls notifications. | Empty (HTTP 202) with a refresh request id header. |
| `getRefreshHistory` | List recent refreshes; `top` caps the count. | `{ value: [{ requestId, status, startTime, endTime }] }` |
| `getRefreshSchedule` | Read the scheduled-refresh configuration. | `{ days, times, enabled, localTimeZoneId, notifyOption }` |
| `updateRefreshSchedule` | Update the refresh schedule via `value`. | Empty (HTTP 200). |
| `cancelRefresh` | Cancel an in-progress refresh by `refreshId`. | Empty (HTTP 200). |
### Reports
| Instruction | Description | Returns |
| ---------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `listReports` | List reports in a workspace. | `{ value: [{ id, name, datasetId, webUrl, embedUrl }] }` |
| `getReport` | Fetch one report by `reportId`. | A Report resource `{ id, name, datasetId, embedUrl }`. |
| `deleteReport` | Delete a report by `reportId`. | Empty (HTTP 200). |
| `cloneReport` | Clone a report into `targetWorkspaceId` / `targetModelId` with a new `name`. | The cloned Report `{ id, name }`. |
| `rebindReport` | Rebind a report to another dataset (`datasetId`). | Empty (HTTP 200). |
| `getReportPages` / `getReportPage` | List a report's pages / get one by `pageName`. | `{ value: [{ name, displayName, order }] }` / a Page resource. |
| `exportReport` | Start an async export to `format` (PDF/PPTX/PNG). | `{ id, status }` (poll for completion). |
| `getReportExportStatus` | Poll an export by `exportId`. | `{ id, status, percentComplete, resourceLocation }` |
| `getReportExportFile` | Download the finished export by `exportId`. | The exported file bytes. |
| `updateReportContent` | Overwrite a report's content from a source report. | Empty (HTTP 200). |
| `generateReportToken` | Generate an embed token; `accessLevel`, optional `identities` for RLS. | `{ token, tokenId, expiration }` |
### Dashboards & tiles
| Instruction | Description | Returns |
| ---------------------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------- |
| `listDashboards` | List dashboards in a workspace. | `{ value: [{ id, displayName, embedUrl }] }` |
| `getDashboard` | Fetch one dashboard by `dashboardId`. | A Dashboard resource `{ id, displayName, embedUrl }`. |
| `createDashboard` | Create a dashboard by `name`. | The created Dashboard `{ id, displayName }`. |
| `getDashboardTiles` / `getDashboardTile` | List a dashboard's tiles / get one by `tileId`. | `{ value: [{ id, title, embedUrl }] }` / a Tile resource. |
| `cloneDashboardTile` | Clone a tile into `targetDashboardId` (optionally rebinding report/model). | The cloned Tile `{ id, title }`. |
| `generateDashboardToken` | Generate an embed token for a dashboard; `accessLevel`. | `{ token, tokenId, expiration }` |
### Dataflows
| Instruction | Description | Returns |
| ------------------------- | --------------------------------------------------------- | ---------------------------------------------------- |
| `listDataflows` | List dataflows in a workspace. | `{ value: [{ objectId, name, description }] }` |
| `getDataflow` | Fetch a dataflow's `model.json` by `dataflowId`. | The dataflow model JSON. |
| `deleteDataflow` | Delete a dataflow by `dataflowId`. | Empty (HTTP 200). |
| `refreshDataflow` | Trigger a dataflow refresh; `processType`/`notifyOption`. | Empty (HTTP 200). |
| `getDataflowTransactions` | List a dataflow's refresh transactions. | `{ value: [{ id, status, startTime, endTime }] }` |
| `getDataflowDatasources` | List a dataflow's datasources. | `{ value: [{ datasourceType, connectionDetails }] }` |
### Gateways
| Instruction | Description | Returns |
| ---------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `listGateways` | List the on-premises data gateways. | `{ value: [{ id, name, type, gatewayStatus }] }` |
| `getGateway` | Fetch one gateway by `gatewayId`. | A Gateway resource `{ id, name, publicKey }`. |
| `getGatewayDatasources` | List a gateway's datasources. | `{ value: [{ id, datasourceType, datasourceName }] }` |
| `createGatewayDatasource` | Create a datasource: `dataSourceType`, `connectionDetails`, `credentialDetails`, `datasourceName`. | The created datasource `{ id }`. |
| `deleteGatewayDatasource` | Delete a datasource by `datasourceId`. | Empty (HTTP 200). |
| `getGatewayDatasourceStatus` | Check a datasource's connectivity status. | `{ status }` (or an error object). |
### Imports
| Instruction | Description | Returns |
| ---------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| `listImports` | List imports in a workspace. | `{ value: [{ id, importState, reports, datasets }] }` |
| `getImport` | Fetch one import by `importId`. | An Import resource `{ id, importState, reports, datasets }`. |
| `createImportUploadLocation` | Create a temporary upload URL to publish a PBIX. | `{ url }` (time-limited upload location). |
### Capacities
| Instruction | Description | Returns |
| ------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ |
| `listCapacities` | List the Premium / Fabric capacities the user can see. | `{ value: [{ id, displayName, sku, state }] }` |
| `getCapacityWorkloads` | List a capacity's workloads by `capacityId`. | `{ value: [{ name, state, maxMemoryPercentageSetByUser }] }` |
| `getCapacityRefreshables` | List refreshables on a capacity; `top`/`expand`. | `{ value: [{ id, refreshCount, refreshFailures, … }] }` |
### Admin (tenant)
| Instruction | Description | Returns |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `adminListGroups` | List all workspaces in the tenant; `filter`/`top`/`skip`. | `{ value: [{ id, name, type, state }] }` |
| `adminGetGroupUsers` | List a workspace's users (admin) by `groupId`. | `{ value: [{ identifier, principalType, groupUserAccessRight }] }` |
| `adminListDatasets` / `adminListReports` / `adminListDashboards` / `adminListDataflows` | Tenant-wide listing of each resource. | `{ value: [ … ] }` |
| `adminGetActivityEvents` | Query the activity log between `startDateTime`/`endDateTime` (same UTC day). | `{ activityEventEntities: [...], continuationToken }` |
| `adminListCapacities` | List all capacities in the tenant. | `{ value: [{ id, displayName, sku, state }] }` |
| `adminGetModifiedWorkspaces` | List workspaces modified since `modifiedSince`. | `{ value: [{ id }] }` |
| `adminScanWorkspaces` | Start a metadata scan over `workspaces[]` (`lineage`, `datasourceDetails`, `datasetSchema`, `datasetExpressions`). | `{ id, status }` (scan id). |
| `adminGetScanStatus` / `adminGetScanResult` | Poll a scan by `scanId` / fetch the scan result. | `{ id, status }` / the full metadata scan result. |
`Returns` shows the shape of the operation output (the underlying Power BI API resource). `groupId` is the workspace id and is optional on data operations — omit it to target "My workspace". All `admin*` instructions require the connected user to be a Fabric / Power BI administrator.
## DSUL Examples
**List datasets in a workspace, then run a DAX query:**
```yaml theme={null}
- Power BI.listDatasets:
groupId: '{{workspaceId}}'
output: datasets
- Power BI.executeQueries:
groupId: '{{workspaceId}}'
datasetId: '{{datasets.value[0].id}}'
daxQuery: "EVALUATE TOPN(10, 'Sales', 'Sales'[Amount], DESC)"
output: rows
```
**Trigger a refresh and check its history:**
```yaml theme={null}
- Power BI.refreshDataset:
groupId: '{{workspaceId}}'
datasetId: '{{datasetId}}'
notifyOption: MailOnFailure
- Power BI.getRefreshHistory:
groupId: '{{workspaceId}}'
datasetId: '{{datasetId}}'
top: 5
output: history
```
**Export a report to PDF (async — start, poll, download):**
```yaml theme={null}
- Power BI.exportReport:
groupId: '{{workspaceId}}'
reportId: '{{reportId}}'
format: PDF
output: export
- Power BI.getReportExportStatus:
groupId: '{{workspaceId}}'
reportId: '{{reportId}}'
exportId: '{{export.id}}'
output: status
- Power BI.getReportExportFile:
groupId: '{{workspaceId}}'
reportId: '{{reportId}}'
exportId: '{{export.id}}'
output: file
```
**Discover a model's structure with DAX (works on import/DirectQuery models):**
```yaml theme={null}
- Power BI.executeQueries:
groupId: '{{workspaceId}}'
datasetId: '{{datasetId}}'
daxQuery: "EVALUATE INFO.VIEW.TABLES()"
output: tables
```
***
## Error Handling
| HTTP code | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad request — invalid parameters, malformed body or DAX syntax error. |
| `401` | Unauthorized — the Power BI access token is missing, expired or revoked. The user must reconnect. |
| `403` | Forbidden — insufficient OAuth scope, the account lacks access to the resource, or an `admin` action by a non-admin user. |
| `404` | Not found — the workspace, dataset, report, dashboard or other id does not exist or is not visible to the account. |
| `409` | Conflict — e.g. a refresh is already in progress, or a name collision when creating a resource. |
| `429` | Rate limit / capacity throttling — back off and retry. |
| `500` / `503` | Power BI service error — transient; retry shortly, no reconnection needed. |
### Common Issues
**"This agent is not authorized to use this connector"** — The calling agent is not in the allowlist. Open the configuration app → **Authorized agents** → tick this agent (or enable **Allow all agents**) and Save.
**"The calling agent could not be identified"** — The MCP capability *Scope* does not declare `agent_id`, so Agent Factory never injects the agent identity. Set the Scope to `context_id,agent_id,user_id` on the capability, then allow the agent in the config app.
**"Power BI is not connected for this user"** — No per-user OAuth token. Open the configuration app and click **Connexion**, or use the agent's connect flow.
**"Power BI token refresh failed … must reconnect"** — The stored refresh token was revoked or expired (Microsoft Entra ID invalidated it). The connection is dropped automatically; the user must reconnect from the config app.
**"Power BI OAuth is not configured"** — The Microsoft Entra ID client ID/secret/tenant is missing. Open the configuration app and enter the OAuth credentials (or ask the platform admin to register the central application).
**`getTables` fails with "not Push API dataset"** — `getTables` only works on Push-API datasets. To inspect a normal import / DirectQuery semantic model, use the `datasets` `getSchema` action, or run a DAX query such as `EVALUATE INFO.VIEW.TABLES()` / `EVALUATE INFO.VIEW.COLUMNS()` via the `query` tool.
## External Resources
Official reference for the Microsoft Power BI REST API (v1.0).
Learn how Agent Factory agents consume MCP tools in Prisme.ai.