Power BI API: A Comprehensive Guide for Developers and Data Professionals

The Power BI REST API is a key component in expanding upon the capabilities of Microsoft Power BI.

It allows developers and organizations to provide programmatic access to reports, dashboards, datasets, and workspaces, rather than just providing a fixed GUI.

This capability is vital in modern BI solutions where automation, integration, and embedding are central to business processes.

In this guide, I'll provide an introduction to the Power BI REST API, a simple step-by-step guide on how to use it, some examples of how it can be used, and share some of the advanced features it provides

The Power BI API Ecosystem

The Power BI API ecosystem is designed to scale across enterprises, offering robust capabilities for developers.

It allows organizations to treat Power BI as a service layer that integrates seamlessly into workflows and applications.

Here are the basic components of the ecosystem:

1. REST API: The foundation of the ecosystem, exposing endpoints for datasets, reports, dashboards, workspaces, and users.
2. SDKs: Microsoft offers SDKs in .NET, Python, and JavaScript, each tailored to common developer workflows:
3. CLI: A command-line interface for managing workspaces, pushing datasets, and deploying content.
4. PowerShell: A preferred tool for administrators to script and automate routine tasks like user provisioning or audit logging.

Purpose and capabilities

The API provides end-to-end management of Power BI assets for the following use cases:

• Automation: Trigger dataset refreshes, move reports between environments, and update permissions without manual work.
• Governance: Extract metadata for compliance, track usage patterns, and enforce policies.
• Integration: Connect Power BI with other enterprise systems (CRM, ERP, HR, ETL tools) to provide real-time reporting.
• Embedding: Deliver secure, interactive dashboards and reports in web or mobile applications.

These capabilities extend Power BI beyond its GUI, enabling organizations to operate at scale.

RESTful Architecture

The API follows REST principles, which makes it accessible to developers.

Here are some components of the architecture:

• HTTP Methods: GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal.
• JSON Payloads: Easy to parse and integrate with modern applications.
• Interoperability: Works seamlessly with libraries like Python requests, Node.js axios, or .NET HttpClient.

The API also supports programmatic content management.

This means you can perform the following functions:

• Creation of new datasets and their schemas.
• Exporting reports for version control and migration.
• Cloning reports and dashboards to new environments.
• Rebinding reports to different datasets, simplifying deployment pipelines.

Power BI API Authentication and Security

Authentication is fundamental for secure communication. The Power BI API relies on Azure Active Directory to authenticate applications and users.

1. Authentication process

To enable access:

1. Register an App: In Azure AD, create an app registration.
2. Gather Credentials: Collect Tenant ID, Client ID, and Client Secret.
3. Choose Access Model: Use delegated access (user context) or service principal (application-only).

Service principals are recommended for automation since they are not tied to individual users.

2. OAuth 2.0 flow

Power BI supports standard OAuth 2.0 flows:

• Client Credentials Flow: Ideal for server-to-server apps, runs without user interaction.
• Authorization Code Flow: Requires user login, used for interactive applications. Tokens issued by Azure AD include claims defining user or app privileges.

3. Bearer token approach

Tokens are attached to requests:

Authorization: Bearer {access_token}

Tokens expire after a short time (usually one hour), so applications must refresh them programmatically.

Core Power BI API Operations

The Power BI API is divided into categories covering all aspects of Power BI content and user management.

Here are its core operations and functions:

1. Endpoint categories
2. Dataset management
3. Report and dashboard management
4. Workspace and embedding management
5. User and permission management

How to Use the Power BI REST API: Step-by-Step Process

The Power BI REST API lets you automate tasks (like refreshing datasets), manage users and workspaces, or embed reports in apps.

To use it, follow these steps:

Step 1: Register an app for Power BI

Before your code can talk to Power BI, you must register an app in Azure Active Directory (Azure AD).

1. Go to the Azure Portal.
2. Navigate to Microsoft Entra ID → App registrations → New registration.
3. Enter:
• Name: PowerBI-API-Test
• Supported account types: Single tenant (good enough for testing).
• Redirect URI: https://oauth.pstmn.io/v1/callback (this is Postman’s redirect URL).
4. After registering, copy the Application (Client) ID and Directory (Tenant) ID.
5. Under Certificates & secrets, create a client secret and copy it down.

Step 2: Authorize the user or service principal

For our next step for authorization, there are two common approaches:

• Delegated (user) flow: User logs in and grants permission.
• Service principal (app-only) flow: Admin consents to permissions, and the app acts independently.

In this example, we'll be using the delegated flow method.

1. Under API permissions → Add a permission → Power BI Service → Delegated permissions, add:
• Dashboard.Read.All
• Report.Read.All
• Dataset.Read.All
2. Click Grant admin consent if prompted.

Step 3: Get API access token

Every API call requires an OAuth token. Without this, the API won’t know who you are or what permissions you have.

We'll be using Postman to get the API token.

1. Open Postman → New → Request.
2. In the Authorization tab, choose:
• Type: OAuth 2.0
• Grant Type: Authorization Code
• Callback URL: https://oauth.pstmn.io/v1/callback
• Auth URL: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/authorize
• Access Token URL: https://login.microsoftonline.com/<tenant_id>/oauth2/v2.0/token
• Client ID: Your Application (Client) ID
• Client Secret: Your secret
• Scope:  openid profile offline_access https://analysis.windows.net/powerbi/api/Dashboard.Read.All https://analysis.windows.net/powerbi/api/Report.Read.All https://analysis.windows.net/powerbi/api/Dataset.Read.All
3. Click Get New Access Token.
4. Sign in with your Microsoft account.
5. If successful, Postman shows an access token. Click Use Token.

You can also get an access token from Microsoft Azure using the following Python script using the requests library.

import requests

payload = {
    'grant_type': 'client_credentials',
    'client_id': CLIENT_ID,
    'client_secret': CLIENT_SECRET,
    'scope': 'https://analysis.windows.net/powerbi/api/.default'
}

response = requests.post(TOKEN_URL, data=payload)
access_token = response.json()["access_token"]

This token is short-lived; refresh it automatically in production.

Step 4: Make API calls

Once you’ve obtained an access token (from Step 3), you can finally start talking to the Power BI REST API.

Think of the token as your “entry ticket.” Without it, every request will be rejected.

All Power BI REST API calls start with a URL:

https://api.powerbi.com/v1.0/myorg

Here's what each part of the string means:

• v1.0 → API version.
• myorg → refers to your tenant.

You’ll append resource paths like /groups, /reports, /datasets.

Every request must include your access token in the Authorization header:

Authorization: Bearer <access_token>

And for POST requests, add:

Content-Type: application/json

If you forget these headers, you’ll get a 401 Unauthorized error`.

To start, let’s try listing all workspaces (groups).

headers = {
    "Authorization": f"Bearer {access_token}"
}

groups_url = "https://api.powerbi.com/v1.0/myorg/groups"
groups_response = requests.get(groups_url , headers=headers)

The above GET request shows all workspaces your user has access to.

Example response:

{
  "value": [
    {
      "id": "1234-abcd-5678-efgh",
      "name": "Marketing Analytics"
    },
    {
      "id": "7890-ijkl-1234-mnop",
      "name": "Sales Reporting"
    }
  ]
}

Handling authentication and common issues

If you encounter any errors, here are some possible issues and what they mean.

• 401 Unauthorized: Expired or missing token.
• 403 Forbidden: Insufficient permissions.
• Invalid Scope: Ensure the requested scope matches the API endpoint. Debugging with Postman or PowerShell cmdlets helps isolate permission issues.

Power BI REST API Examples

Let’s take a look at some examples of the Power BI API in action. 

Example 1: Get datasets

This call retrieves all datasets within a workspace.

headers = {
    "Authorization": f"Bearer {access_token}"
}
# Example: List datasets in the default workspace
datasets_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/datasets"
datasets_response = requests.get(datasets_url, headers=headers)
for dataset in datasets_response.json()['value']:
    print(dataset['id'], dataset['name'])

Sample response:

{
  "value": [
    {
      "id": "1234abcd-5678-efgh-9101-ijklmnop",
      "name": "SalesDataset",
      "configuredBy": "user@contoso.com",
      "addRowsAPIEnabled": false,
      "isRefreshable": true
    },
    {
      "id": "9876wxyz-5432-ponm-1112-abcd1234",
      "name": "MarketingDataset",
      "configuredBy": "admin@contoso.com",
      "addRowsAPIEnabled": true,
      "isRefreshable": false
    }
  ]
}

Example 2: Refresh dataset

You can automate dataset refreshes instead of relying only on scheduled refreshes in the Power BI Service. This example triggers a dataset refresh, commonly used in ETL pipelines.

headers = {
    "Authorization": f"Bearer {access_token}"
}
datasets_refreshes_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/datasets/{datasetId}/refreshes"
refresh_response = requests.post(datasets_refreshes_url , headers=headers)

print("Refresh Status:", refresh_response .status_code)

Response:

• If successful, you’ll receive: HTTP 202 Accepted message. This means the refresh has been queued.

Example 3: List reports and dashboards

In this next example, let’s look at a script that fetches reports in a workspace, useful for inventory or migration scripts.

List reports

Here’s a script to list reports:

headers = {
    "Authorization": f"Bearer {access_token}"
}
reports_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/reports"
reports = requests.get(reports_url , headers=headers).json()['value']

for report in reports:
    print(report['id'], report['name'])

Response:

{
  "value": [
    {
      "id": "a1b2c3d4",
      "name": "Executive Sales Report",
      "embedUrl": "https://app.powerbi.com/reportEmbed?reportId=a1b2c3d4",
      "datasetId": "1234abcd-5678-efgh-9101-ijklmnop"
    }
  ]
}

List dashboards

We can also list out the names of dashboards we have in our Power BI workspace.

Here’s a script to list dashboards:

headers = {
    "Authorization": f"Bearer {access_token}"
}
dashboards_url = "https://api.powerbi.com/v1.0/myorg/groups/{workspaceId}/dashboards"
dashboards = requests.get(dashboards_url  , headers=headers).json()['value']

for dashboard in dashboards :
    print(dashboard ['id'], dashboard ['name'])

Response:

{
  "value": [
    {
      "id": "z9y8x7w6",
      "displayName": "Sales Performance Dashboard",
      "embedUrl": "https://app.powerbi.com/dashboardEmbed?dashboardId=z9y8x7w6"
    }
  ]
}

Power BI API Embedding and Integration 

Embedding Power BI extends analytics into external apps and portals beyond just sharing on the Power BI service. This is a good option for organizations that want to create dashboards for customer-facing applications.

Source: Microsoft Power BI

1. Embedding architecture

Embedding Power BI content involves rendering reports, dashboards, or visuals inside custom applications using the Power BI REST API and JavaScript SDK.

The architecture typically consists of:

• Application frontend: A web or mobile client that hosts the embedded report using the Power BI JavaScript library.
• Application backend: A secure service that authenticates with Azure AD, generates embed tokens, and passes them to the frontend.
• Power BI Service: The core platform hosting the datasets, reports, and models that provide the analytics.

2. Embed scenarios

There are two primary scenarios for embedding Power BI content, each with different licensing and security models:

• For your organization: Authenticated users within the same tenant.
• For your customers: External users authenticated through embed tokens, backed by Power BI Embedded capacity.

The image below shows how the embed works.

Source: Microsoft

3. Technical implementation

To implement Power BI embedded, you'll need both backend authentication and frontend rendering.

Here are some general steps:

• Step 1: Register the app in Azure AD and configure the appropriate API permissions
• Step 2: Generate embed tokens by calling the Power BI REST API to grant time-limited access
• Step 3: Use the Power BI JavaScript SDK to load the report into an iframe container.
• Step 4: Secure the workflow by ensuring tokens are generated server-side only and implementing HTTPS-only communication, short-lived tokens, and token refresh mechanisms.

Power BI API Performance Optimization

Efficient use of the Power BI API is essential for ensuring scalability, reliability, and responsiveness.

Since all APIs operate under rate limits and throttling rules, you'll need to design applications that handle these limits while maintaining high performance.

Here are some measures I found to be useful:

1. Rate limiting constraints and throttling

Power BI enforces API rate limits to maintain service stability and fair resource distribution across tenants. Each tenant has request quotas, and exceeding limits triggers the 429 Too Many Requests error.

2. Optimization strategies

Several techniques can minimize API calls, maximize throughput, and reduce load on Power BI services:

• Batching: Send multiple requests in one batch.
• Caching: Avoid repeated API calls.
• Asynchronous Calls: Handle refreshes or long tasks in the background.

3. Monitoring and logging

Visibility into API usage is key to managing quotas and troubleshooting performance issues.

Source: Microsoft Azure Monitor

Here are some methods for API monitoring:

• Track all API calls with timestamps and results.
• Use Azure Monitor for system-level monitoring.

Power BI API Security Considerations

Security and governance are foundational pillars for any enterprise that intends to implement Power BI and its API ecosystem.

Here are some measures:

1. Credential management

• Use secure storage mechanisms: Store credentials in secure locations such as Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault.
• Rotate secrets regularly: Implement automated policies for rotating client secrets, certificates, and tokens to minimize risk from compromised credentials.
• Monitoring and alerts: Track unusual authentication failures or repeated token requests to detect potential breaches.

Use Azure Key Vault for secrets.

• Rotate secrets frequently.
• Never hardcode credentials in source code.

2. Access control

Access control ensures that only authorized users can view or manipulate datasets, reports, and dashboards.

1. Row-Level Security (RLS):
• Restrict access at the data row level by applying DAX filters.
• Example: Regional managers only see sales data for their assigned region.
• RLS roles can be tested in Power BI Desktop and enforced in the service.
2. Object-Level Security (OLS):
• Limit access to specific tables or columns within a dataset.
• Use cases: Hiding salary information, sensitive customer identifiers, or confidential financial metrics.

3. Data protection

To ensure data is well kept, here are some data protection strategies you can adopt:

• Encryption at rest
• Encryption in transit
• Audit logging
• Data classification

4. Data privacy and compliance

Enterprises often operate in multiple regions, making compliance a critical factor.

Some aspects you should consider:

• Alignment with GDPR, HIPAA, or industry-specific regulations.
• Regional endpoints to maintain compliance.

Power BI API Development Tools and SDK Ecosystem

1. .NET SDK

The Power BI .NET SDK provides a strongly typed interface that integrates seamlessly with the Microsoft stack. It is especially suited for enterprise developers who are already using Azure, C#, or ASP.NET applications.

Use cases: Automating report publishing, embedding dashboards in enterprise portals, and managing workspace assets.

Advantages: Type safety, robust error handling, and native support for Azure Active Directory authentication flows.

2. Python SDK

The Python SDK (and REST client libraries) is popular among data scientists and analysts who prefer scripting environments.

Use cases: Automating dataset refreshes, exporting report metadata, and integrating Power BI workflows into broader data pipelines.

Advantages: Rapid prototyping, rich ecosystem of data libraries (pandas, Polars, NumPy), and ease of integration with Jupyter notebooks.

3. JavaScript SDK

The JavaScript SDK is essential for embedding Power BI content directly into web applications.

Use cases: Embedding reports into customer portals, SaaS products, or internal dashboards. Developers can also customize user interactions such as filtering, exporting, and drill-through directly from client-side code.

Advantages: Real-time interactivity, browser compatibility, and support for Single Page Applications (SPAs) with frameworks like React, Angular, or Vue.

Power BI API Development Considerations

1. Configuration management

When creating a development environment for running your API calls, you'll need to take note of these considerations:

• Store secrets like client IDs, client secrets, and tenant IDs in environment variables or secure vaults (e.g., Azure Key Vault).
• Avoid hardcoding sensitive values in source code.
• Validate permissions before deploying to production.

2. Permission validation

Before deploying to production, ensure that the app registration in Azure AD has the correct API scopes and delegated or application permissions.

Run pre-deployment scripts or checks to confirm tokens grant the expected level of access.

3. Versioning and compatibility

SDKs tend to evolve alongside Power BI APIs.

You should track version updates to avoid breaking changes, especially if using preview features. Maintain pinned versions in requirements.txt (Python) or package.json (JavaScript).

Testing Methodologies

To check if your API calls are running smoothly, you can do some tests afterward.

1. Postman for endpoint exploration

To do endpoint testing, use Postman to interactively test REST API endpoints. You can import Power BI API collections, authenticate via OAuth 2.0, and experiment with different request/response payloads before coding.

2. Automated tests

Implement unit tests for authentication flows and integration tests for end-to-end workflows.

Here are some testing frameworks:

• Python: pytest + mock APIs
• .NET: MSTest, NUnit, or xUnit
• JavaScript: Jest or Mocha with nock (for API mocking)

Troubleshooting and Common Implementation Challenges

If you’re having difficulties getting set up with the Power BI API, you can check out the errors and solutions below:

1. Common errors

401 Unauthorized: Check token validity and scopes. 

How to fix: Verify that the access token has not expired and that it was generated with the correct API permissions. 

403 Forbidden: Permissions missing or denied.

How to fix: Confirm that the caller has the right role assignments (e.g., Contributor, Power BI Admin, or custom roles with the required permissions). 

429 Too Many Requests: Throttling applied; retry after delay.

How to fix: Implement exponential backoff or retry logic in your code. Monitor API call volume and distribute requests over time.

2. Connector visibility and data source issues

On-premises or VNet data gateways are required for certain data sources. If the gateway is not installed, misconfigured, or offline, the API cannot refresh or access the dataset.

To prevent these issues, confirm the gateway is up to date, running, and properly mapped to the data source in the Power BI Service.

Dataset refreshes or API calls may fail if data source credentials have expired or changed.

To prevent this, regularly update credentials in the Power BI Service or configure credential rotation policies. You can also use managed identities or key vaults for more secure, automated management.

Advanced Features of the Power BI API

As Power BI matures into a central analytics platform, its advanced features and automation capabilities are critical for scaling analytics across the enterprise.

Next, let's look at some advanced features Power BI has to offer.

1. Deployment pipelines

Deployment pipelines provide a structured way to manage the lifecycle of Power BI content across development, test, and production environments.

They help enforce change control, reduce risk, and ensure consistent deployment practices.

With these pipelines, developers can publish datasets and reports to the development stage. Using the REST API, content can then be promoted to test and production stages.

2. Refresh and user management automation

Automation around refreshes and user permissions is central to keeping data current and access compliant.

Here are some ways automated refreshes can be used:

• Dataset refresh automation: Using the Power BI REST API or PowerShell cmdlets, admins can trigger dataset refreshes programmatically.
• User management automation: APIs allow programmatic addition, removal, and updating of workspace or dataset permissions. For example, automatically granting report access to new hires when they join a specific Azure AD group.

3. Developing and publishing custom visuals

Custom visuals can be created to expand the capabilities of Power BI and allow organizations to build tailored data experiences.

Here's a simple guide:

• Step 1: Set up the development environment
• Install Node.js and the Power BI visuals tools (pbiviz).
• Run pbiviz new <visualName> to scaffold a new project.
• Step 2: Develop the visual
• Use TypeScript, HTML, and CSS to define the rendering logic.
• Bind to Power BI’s data model APIs to read fields, measures, and filters.
• Test iteratively in Power BI Desktop using Developer Mode, which allows sideloading visuals.
• Step 3: Debug and optimize
• Use browser dev tools to debug rendering logic.
• Optimize performance for large datasets by limiting DOM operations and handling updates efficiently.
• Step 4: Package the visual
• Build and package with pbiviz package. This generates a .pbiviz file.
• The file can be distributed internally or uploaded to the organization’s AppSource tenant.

Final Thoughts

Integrating the Power BI API into business intelligence workflows delivers powerful automation and scalability. It enables you to work beyond just delivering dashboards using the built-in GUI. 

If you’re interested in learning more about Power BI, I can recommend our Introduction to Power BI course and Power BI Fundamentals track. For more reading resources, check out our Power BI Dashboard Tutorial or Deploying and Maintaining Assets in Power BI tutorial.