Power BI REST API: what it does and how to start safely
Power BI REST API is a set of web endpoints that lets software do what people do by hand in the Power BI service. Code can list workspaces, start a refresh, manage content and embed reports in another application. So routine admin work becomes a script. Here is what the API covers, how a first call works and where teams need care.
- Automate admin work
- Two ways to sign in
- Plan for throttling
Last updated
What is the Power BI REST API?
It is Microsoft's programming interface for the Power BI service. Microsoft Learn describes endpoints for embedding, administration, governance and user resources. In short, a program sends a web request and the service answers with data or performs an action.
That matters because manual work does not scale. For example, an administrator may need a list of every workspace and who can reach it. Clicking through the portal takes hours, while a script collects the same facts in one run. Also, a deployment tool can start a refresh once new data lands.
One naming point saves confusion. Some endpoints use the word groups where the portal says workspaces. They mean the same thing, so a call to a groups endpoint works on a workspace.
Main operation groups the API reference lists
Microsoft organizes the reference by operation group. These are the ones business teams meet first.
| Operation group | What it works on | A common use |
|---|---|---|
| Datasets | Semantic models and their refreshes | Start a refresh after a nightly load |
| Reports | Reports in a workspace | List reports for an inventory |
| Groups | Workspaces and their users | Add a team to a new workspace |
| Admin | Tenant-wide information for administrators | Review content across the organization |
| Embed Token | Tokens for embedded content | Show a report inside your own application |
| Imports | Files uploaded to a workspace | Publish a report file from a script |
| Pipelines | Deployment pipelines | Move content from test to production |
| Gateways | Gateways and their data sources | Check which sources a gateway serves |
How does a first Power BI REST API call work?
Every call follows the same pattern, so learn it once and reuse it.
Register an application
First, register an application in Microsoft Entra ID. The registration gives your code an identity that the service can recognize.
Choose who the code acts as
Then decide between a signed-in user and a service principal. A user needs delegated permissions, while a service principal relies on admin settings instead.
Request an access token
Next, your code asks Microsoft Entra ID for a token. After that, it sends the token with each request it makes.
Call an endpoint and read the reply
Finally, send the request and check the response. Start with a harmless call, such as listing workspaces, before you change anything.
Which permissions does an API call need in Power BI?
There are two routes. With a user identity, the app needs delegated permissions, which Microsoft also calls scopes. You add them in the app registration under API permissions, by choosing Add a permission, then Power BI Service, then Delegated permissions.
A service principal works differently. Microsoft Learn states that scopes do not apply there. Instead, a Power BI administrator controls its access through the admin portal, and the principal also needs a role in each workspace it touches.
Either way, the code can do no more than its identity allows. So give each script the smallest access that gets its job done. A refresh script, for example, has no reason to hold tenant-wide admin rights. For the identity that scripts should sign in with, see Power BI service principal, and for ongoing tenant care, see Power BI administration services.
What limits should Power BI REST API users plan for?
Throttling comes first. The service limits how many calls a user can make in a period of time. When code goes over, the reply carries status 429 and a Retry-After header. Therefore a good script waits for that interval and tries again.
Refresh calls deserve the same care. Microsoft advises retry logic when you start a refresh through the API, because a request can fail for passing reasons. Also, log every call so someone can trace a failure later.
Secrets are the other risk. An app secret or certificate opens the same doors as a password. So keep it in a secure store, never in a script file, and replace it on a schedule your security team sets.
Questions business teams ask about calling Power BI from code
Do we need a developer to use the Power BI REST API?
Some coding skill helps, but the bar is modest. Anyone who can write a short script can call an endpoint and read the reply. However, registering the app and setting permissions takes care, since mistakes there affect security. Many teams therefore ask IT to own the app registration, while analysts write the scripts that use it.
Can the Power BI REST API start a data refresh?
Yes. The Datasets operation group includes calls that start a refresh and read its history. So a data pipeline can refresh a semantic model as soon as its load finishes, instead of waiting for a fixed schedule. Microsoft recommends adding retry logic, because a request may fail for temporary reasons. License and capacity limits on refresh still apply, so check Microsoft's documentation.
Why does a REST call to Power BI return status 429?
That status means throttling. The service caps the number of calls one user can make within a time window. The response includes a Retry-After header that says how long to wait. So build a pause into the script and try again after that interval. Spacing calls out, and asking only for what you need, also lowers the chance of hitting the cap.
What is the difference between a user token and a service principal?
A user token acts as a person and carries that person's rights. It needs delegated permissions on the app registration. A service principal acts as the application itself, with no person signed in. An administrator allows it through tenant settings, and it needs a workspace role. Unattended jobs usually suit a service principal, while tools a person runs suit a user token.
Can you build this kind of automation for us?
Yes. Power BI Agency scripts inventories, refresh triggers and deployments for teams that need them. We are a small team within Sataware Technologies, and independent of Microsoft. The work happens online inside your own tenant, with a written fixed scope and weekly demos. Start with a free 30-minute assessment, or call (480) 485-7373.
Let's build your first dashboard together.
Tell us what you report on today. A consultant replies within 2 hours with next steps.
Trusted partners
Microsoft Solutions Partner · AWS Partner
Cloud & AI Platforms
Azure SQL, Microsoft Fabric and the data pipelines behind your reports.
AI Business Solutions
Power BI reporting on your Dynamics 365, Business Central and Power Platform data.
Security
Row-level security and Entra ID sign-in on every report and workspace.
Amazon Web Services
Power BI on your AWS data, with connectors for Redshift, Athena and S3.