# Connect Aphex to Power BI
{% hint style="info" %}
**Things to know before you get started:**
* You will need the [Desktop Power BI application downloaded](https://powerbi.microsoft.com/en-au/) onto your device.
* You must be a Project Admin to set up the integration.
{% endhint %}
In addition to our built in reporting app, Aphex Insight we also provide an integration with Power BI so that teams can customise their reports and hunt for insight.
In this guide we will go through the key steps to start analysing your data in Power BI. Where necessary we will include links to more advanced features throughout.
## Enable Integration
***
The Power BI Integration is enabled at a project level so that every team has control over who can access their data. To start, head to your project in Aphex Planner and locate the Integrations page.
#### To enable the data source:
* Open your project
* Click your project title in the top left and select `Integrations` from the menu
* Locate the Power BI section and toggle `Enable Source`
## Generate a Token
***
Once you've enabled the Power BI source, you’ll be able to copy your project's unique URL endpoint.
To keep your data secure, the endpoint won’t return any data unless the request includes a valid token. The token is shown once only, so be sure to copy it before closing the window. If it expires or you forget to save it, you can generate a new one at any time.
#### To generate a token:
* On the Integrations page, click `+ Generate New Token`
* Give your token a name so that people know what it's being used for
* Click `Generate Token`
* Select `Copy Token`
* Click `Done` to close the window
How Tokens Work
**Authentication**\
Power BI connects using two parts: a **project-specific URL** and a **bearer token**.\
The token acts like a secure key - it proves that the request is allowed to access the data behind the URL.
**Expiry**\
Tokens expire automatically after **90 days**, or can be manually revoked at any time from the project’s Integration settings.
**Multiple tokens supported**\
You can create as many tokens as you need - useful if you’re connecting different tools or templates.
**Naming tokens**\
Each token must be given a name when created. This helps you track where it’s being used (e.g. “PPC Dashboard” or “Client Reporting Suite”).
**Usage tracking**\
You’ll be able to see the **timestamp of last use** and the **token creator** for each token so you know what’s active and what can be cleaned up.
## Download a Template
***
Next up: pick a template.\
We’ve created a set of ready-to-use Power BI dashboards so you don’t have to build your own from scratch. Choose one that fits your reporting needs, then you’ll be ready to connect your project data.
#### To download a template:
* Visit [Aphex's Resource Hub](https://www.aphex.co/resources)
* Pick a Template
* Enter in your details & email
* Open the email and click the download link
* A PBIT file will download to your device
Download a Template or build your own using the API Reference Doc
## Load Data into Power BI
***
Next step: open your template\
Before the template can show anything, it needs to connect to your project. This is where you plug in the values you saved earlier and let Power BI load your project data into the report.
#### To connect the template to your Aphex Project:
* Open the PBIT file in Power BI Desktop
* You’ll be prompted to enter three values:
* `Project API URL`
* `Token`
* `Project Name` (this is just for display inside the report)
* Click `Load`
* Power BI will securely request your project data and load it into the report
With your data loaded, the dashboard is ready to use. If you’re familiar with Power BI, you can tweak visuals, add filters, or expand the reports to fit your project’s workflow.
Common Errors
* If you receive a warning about installing the latest version of Power BI Desktop you can most likely continue on without issue (although updating your software is usually a good idea!)
* Ensure your token is valid, and that you've copied the Project API URL correctly
**Access Web Content Prompt**\
When Power BI prompts you with the Access Web Content window, it’s asking how to authenticate your connection to the API.
Since authentication is handled through the bearer token you already entered, no additional credentials are required here:
* Select “`Anonymous`” as the authentication method, then click `Connect`.
This tells Power BI not to apply any other login method. Using other options like “Windows” or “Organizational Account” may block the request or cause errors.
{% hint style="info" %}
Got a great report template? Why not give back to the Aphex Community and share it with us
{% endhint %}
## Common Connection Issues
***
Most connection issues come down to one of a few predictable causes. This section walks through the ones we see most often and how to fix them.
### Access Web Content: Use Anonymous Authentication
When Power BI prompts you with the Access Web Content window, make sure `Anonymous` is selected.\
This is important because the API uses your token for authentication - selecting any other method (like Windows or Organizational Account) will block the connection.
#### To use Anonymous Authentication:
* In the Access Web Content window, select `Anonymous`
* Make sure no other method is selected, and that no other information has been entered into the window (like Web API Key, or Organizational Account)
* You may also need to ensure the `Privacy Level` is set to `None` or `Public` to avoid errors when refreshing
#### To prompt the Access Web Content window:
* Open the template
* Click `Transform Data`
* Select `Data Source Settings`
* Click `Edit Permissions` at the bottom of the window
* Make sure that Credentials match:
* Type: `Anonymous`
* Privacy Level: `None`
* If needed, select `Edit` to open the Access Web Content window
Example Errors
**`“The 'Authorization' header is only supported when connecting anonymously.”`**\
\&#xNAN;*`These headers can be used with all authentication types: Accept, Accept-Charset, Accept-Encoding, etc.`*
* This means Power BI tried to connect using an authentication method that doesn’t support your bearer token (such as Windows or Organizational Account).
*`“We couldn’t authenticate with the credentials provided.”`*
* This suggests Power BI could be using the wrong method (e.g. "Organizational Account") instead of Anonymous.
*`“The remote server returned an error: (401) Unauthorized.”`*
* This means the API blocked the request - often because Power BI tried to use Windows or Organizational credentials instead of the token.
### Response Size Limit (32mb)
By default, your request will return data from the 5 most recent Published Versions. If your project’s dataset is too large, the connection may fail to load. Unless you're on an Enterprise plan, the API response must be under 32MB. \
You can reduce the amount of data being returned by using query parameters to limit the response size.
Read more about query parameters in our API Reference DocExample Error Messages
*`“The response payload size exceeds the limit.”`*
* A clear sign the API returned more than Power BI is allowed to process.
*`“DataFormat.Error: We reached the end of the buffer.”`*
* This usually means the dataset was too large for Power BI to handle in one response.
*`“Unable to connect to the data source. The connection was closed before the data could be retrieved.”`*
* This can sometimes be triggered when the response is too large and times out during transfer.
Ways to reduce data size
You can use the following parameters individually or in combination:
* **Limit the number of versions**\
Append `?limit=3` or `?limit=2` to your API URL\
→ Example: `https://app.aphex.co/au/power-bi...?limit=3`
* **Exclude resource data**\
Append `?resource=false` to your API URL\
→ Useful if you don’t need labour or plant or material reporting.
* **Exclude delay status data**\
Append `?status=false` to your API URL\
→ Useful if you do not need to report on delay reasons.
* **Exclude blocker data**\
Append `?blockers=false` to your API URL\
→ Useful if you do not need to report on blockers.
You can combine parameters like:\
`?limit=3&resource=false&status=false`
### Replace Expired Credentials
Bearer tokens used for the Power BI integration are valid for 90 days. After that, the connection will stop working until you generate a new token.
If your token has expired, simply return to the project’s Integrations page, revoke the old token, and generate a new one. You’ll need to re-enter the new token into your report to restore the connection.
#### To replace an expired Token:
* Generate a new Token from inside your Aphex Project
* Open your template in Power BI
* Click `Transform Data` then `Edit Parameters`
* Select `Edit Token`
* Delete your old token and add your new one, then select `Save`
* You may need to `Reload Data`
Example Errors
*`“The remote server returned an error: (401) Unauthorized.”`*
* This usually means the token is missing, expired, or no longer valid.
## Set up Automatic Refresh
***
Once your report is connected, you can configure scheduled refresh in Power BI to keep your data up to date automatically.
We suggest setting the refresh to run a few hours (or the day after) your team typically creates the weekly Published Version in Aphex. That way, your dashboard will always reflect the latest plan, without any manual updates.
#### To set up Scheduled Refresh inside Power BI:
* **Publish your report to Power BI Service**
* In Power BI Desktop, go to `File` → `Publish` → `My Workspace` (or your team’s shared workspace).
* **Open dataset settings**
* In Power BI Service, go to your `workspace` → `Datasets` tab.
* Find the dataset linked to your Aphex report and click the `More Options (⋯)` → `Settings`
* **Set authentication method to Anonymous**
* Under `Data source credentials`, confirm that the method is set to `Anonymous`.
* Also check that `Privacy Level` is set to `None` or `Public`, if prompted.
* **Enable “Skip test connection”**
* To avoid false errors during refresh setup, make sure to enable “`Skip test connection`”.
* This setting tells Power BI not to validate the connection in advance, which is fine, because the bearer token is already embedded in the query.
* **Set up scheduled refresh**
* Expand the `Scheduled refresh` section and turn it on:
* Choose `daily` or `weekly` refresh
* **Save your changes**
* Your dashboard will now stay in sync with the latest Published Plan - no manual exports or updates needed.
Visit the Microsoft Documentation to learn more about [Scheduled Refresh in Power BI](https://learn.microsoft.com/en-us/power-bi/connect-data/refresh-scheduled-refresh)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://help.aphex.co/docs/integrations-and-api/power-bi/getting-started-with-power-bi-reporting.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
`Enable Source`
## Generate a Token
***
Once you've enabled the Power BI source, you’ll be able to copy your project's unique URL endpoint.
To keep your data secure, the endpoint won’t return any data unless the request includes a valid token. The token is shown once only, so be sure to copy it before closing the window. If it expires or you forget to save it, you can generate a new one at any time.
