Skip to main content
Speckle’s connection to Power BI consists of two parts.
  • The Power BI connector loads your model from Speckle into Power BI tables.
  • The Speckle 3D visual lets you view and color your models in 3D inside a report.
These steps use Power BI connector release 2026.10.0 or later. If a report uses Speckle.GetByUrl, rebuild it with Get Tables: see Upgrade from 2026.8.

​
Setup

1

Install the connector

Install your Power BI connector. It installs for the current user only, into that user’s Documents folder, and also copies the Speckle 3D visual file there.
2

Open the Power BI connector

Select Get Data, search for Speckle, then select Connect to Speckle (Custom) and Connect. You should see the Speckle Model URL input.
You need to enable third-party data sources.
  1. Go to File > Options and settings > Options > Security.
  2. Under Data Extensions, select Allow any extension to load without validation or warning.
If your organization restricts Power BI security setting changes, your IT department can add the Speckle connector’s thumbprint to the Windows registry instead.Thumbprint: CDC489B709A709E3283568A9B75D75180B1355BEFor detailed instructions, see Microsoft’s Docs.

​
Load a model

1

Connect to Speckle

Select Get Data. Search for Speckle, then select Connect to Speckle (Custom) and Connect. You should see the Speckle Model URL input.
2

Paste a Speckle URL

Paste a model, version, federated, or project URL from the web app and select OK. Sign in when prompted. You should see Objects, Properties, and Relations in Navigator.
3

Load Objects

Select Transform Data to open Power Query, and enable load for Objects. You should see one row per object, with Object Key, Application ID, and Model Info.
4

Choose properties and related fields

Select the Properties function, pick the properties the report needs in the Properties list, then select OK and Invoke to create a new query. Do the same with Relations for fields such as levels or rooms. Enable load for the resulting tables, and leave the function queries with load disabled.
5

Relate the tables

After Close & Apply, create one-to-one relationships from the invoked tables to Objects using Object Key. You should see your properties next to each object in a table visual.
Power Query with the Properties function selected and its Properties list open, showing property paths with checkboxes

Pick properties from the list, then select OK and Invoke.

The default Simplified layout gives you three Navigator entries:
  • Objects has one row per object. Its standard columns are Object Key, Application ID, and Model Info. Federated loads also include Source Model.
  • Properties is a function. Pick the properties the report needs, then load a table with Object Key and those property columns.
  • Relations is a function. Choose outgoing relations such as ON_LEVEL or IN_ROOM, then load a table with Object Key and those relation columns.
The Properties function names columns with the shortest unique end of each property path. Set Use full paths to true to use full dotted paths. If two names still collide at full depth, the connector adds numeric suffixes such as .1 and .2. Instance values use unprefixed column names. Type values use the Type_ prefix.
The All tables layout also shows Property Values, Property Paths, Object Types, Type Properties, the raw Relations table, Relation Types, and Nodes, for building your own relationships. Nodes includes Elevation, which can sort level names. Set Table layout under Advanced options in the connect dialog.

​
View the model in 3D

The Speckle 3D visual streams geometry from Speckle, not through the Power BI dataset. It becomes interactive after the first geometry arrives, and keeps loading in the background.
The 3D visual streams geometry over a WebSocket (WSS). If your network uses a proxy or firewall, allow WebSocket connections to your Speckle server. See API endpoints.
1

Import the visual

In the Visualizations pane, select Import a visual from a file. Browse to Documents/Power BI Desktop/Custom Visuals, select Speckle Power BI 3D Visual.pbiviz, and Open. You should see the imported visual in the pane.
2

Add the model fields

Add the visual to your report. Drag Objects[Model Info] into Model Info and Objects[Object Key] into Object Keys. You should see the first geometry arrive, then the rest stream in.
3

Add tooltips and colors

Drag tooltip fields into Object Data (Tooltip) and a category field into Color By. You should see the model colored by that field.
Model Info and Object Keys are required. Application ID also works as the object binding, but large models then need an extra lookup that can add tens of megabytes to the load.
The 3D visual requires WebGPU. There is no fallback: if WebGPU is missing, the visual shows an error.
The 3D visual does not render in Power BI Service reports opened in Firefox on macOS. Use a Chromium-based browser or Power BI Desktop instead.
The visual’s Edit page supports per-category color overrides and a diagnostics mode. Color overrides stay fixed when the report theme changes. Diagnostics show streaming statistics and recent events. The toolbar at the bottom center has Zoom Extents and Camera. Camera includes orthographic projection, Move camera on filter, and Top, Front, Left, Back, and Right views.
The visual reads Power BI data in 30,000-row windows. With a filter active, it can process up to one million rows for exact isolation. Above 30,000 filtered rows, it keeps the viewport responsive but turns off tooltips and click selection for that selection. Chart-click highlights on very large models are sampled; use a slicer when exact isolation matters.
The visual uses your existing Speckle sign-in and receives a limited-scope token for each load. Your account’s main token does not enter the report.
The 3D visual needs a Speckle server that serves 2026.9 models. On a self-hosted server running a release before 2026.9, the visual cannot load models.

​
Share reports

You can share your Power BI reports with Speckle models in two ways:
  • Share the Power BI file directly: People can view the populated report, including its 3D visual, without signing in to Speckle. The visual uses the restricted share token stored with the report data and stops loading if that token is revoked or expires. Refreshing the source query is a separate connector operation and requires a Speckle account with access to the source project.
  • Publish to Power BI Service: You can publish your report to Power BI web, making it accessible to others through the online platform where they can view the published report and interact with the 3D visual. If a data gateway has been configured, the Speckle connector and 3D visual support scheduled refresh, ensuring your reports reflect up-to-date data.

​
Set up a data gateway

For production reports that need scheduled refresh, you’ll need to set up a data gateway. This allows your Power BI reports to automatically update with the latest Speckle data without manual intervention. Set up Data Gateway →
Data gateways are only needed for scheduled refresh in Power BI Service. For basic connector usage and 3D visualization, you don’t need a gateway.

​
Functions

Properties and Relations are bound to the loaded model. They are not global M functions. useFullPaths is a logical value: false uses the shortest unique suffix, and true uses the full dotted path. Speckle.AddProperties and Speckle.AddAllProperties take the navigation table returned by Speckle.GetTables as source. For example, Speckle.AddProperties(Source, {"path.one", "path.two"}) returns Objects with those two property columns.

​
Speckle.Project.Issues

Fetch issues from a given project, model, or version.
Returns a table with the following columns: Id, Title, Description, Status, Priority, Assignee, Due Date, Created, Updated, Labels, Replies, and URL. Optionally, set getReplies to true to extract replies.
  • Fetch issues from a project: Speckle.Project.Issues("https://app.speckle.systems/projects/PROJECT_ID/")
  • Fetch issues from a model: Speckle.Project.Issues("https://app.speckle.systems/projects/PROJECT_ID/models/MODEL_ID/")
  • Fetch issues from a version: Speckle.Project.Issues("https://app.speckle.systems/projects/PROJECT_ID/models/MODEL_ID@VERSION_ID/")
  • Fetch issues with replies: Speckle.Project.Issues("https://app.speckle.systems/projects/PROJECT_ID/", true)

​
Upgrade from 2026.8

Speckle.GetByUrl and the earlier 3D visual are no longer supported. If a report uses them, rebuild its queries with Connect to Speckle (Custom) and add the new 3D visual. There is no automatic conversion, and renaming the function in the Advanced Editor is not enough. Your data is kept: versions published before 2026.9 stay in your models.

​
Why GetByUrl reports fail

A GetByUrl report that points to a model URL fails on its next refresh once the model gets a version from a 2026.9 connector, a file upload, or a cloud sync. Those versions contain only artifact bundles, which GetByUrl cannot read, so the refresh fails with JsonRepresentationUnavailable. Rebuild the report before that happens. If a report has already failed and you need it working before you can rebuild, change the model URL in the GetByUrl query to .../models/MODEL_ID@VERSION_ID, using the last version published before 4.0. This is unsupported and temporary: the report stops following new publishes. It does not work for a model with no pre-4.0 version, such as a new IFC upload. Rebuild with Get Tables as soon as you can.

​
Rebuild the queries

Use the existing model URL, and follow Load a model from Connect to Speckle. Do not rename GetByUrl to GetTables in the Advanced Editor. Then update every chart, measure, and slicer that references the old table. Check column names: shortened property paths, numeric collision suffixes, and the Type_ prefix may change table references and calculations.

​
Add the new 3D visual

Use connector release 2026.10.0 or later. From 2026.10.0, the new visual has a separate identity and leaves the earlier visual in place on import. Releases 2026.9.0 through 2026.9.2 shared the earlier identity and could replace it on import.
1

Import the new visual

In the Visualizations pane, select Import a visual from a file. Import Speckle Power BI 3D Visual.pbiviz from Documents/Power BI Desktop/Custom Visuals. The new visual appears in the pane alongside the earlier one.
2

Add the new visual and fields

Add the imported visual to your report and check that its fields include Object Keys. The earlier visual has Object IDs. Bind the fields as in View the model in 3D, and recreate any color rules on the new Edit page.
3

Check the report before removing the earlier visual

Refresh the report and test its filters, charts, and tooltips. Confirm that the new visual shows the expected objects before deleting the earlier visual from that page.
Delete the GetByUrl queries after no visual, measure, or relationship references them.

​
Superseded GetByUrl functions

These functions belong to the GetByUrl workflow, which is no longer supported. They read JSON versions only and expect the Speckle.GetByUrl table shape, so they do not accept the tables returned by Speckle.GetTables. Replace them when you rebuild the report.

​
FAQ

​
Loading data

Invoke the Properties function: pick the properties you report on, select OK, then Invoke. The result has one row per object, with Object Key and one column per property. For the 3D visual, also load Objects and relate it on Object Key, because Model Info lives there. To get it all in one table in M, use Speckle.AddProperties.
No. Models with many property sets can have hundreds of paths, and every selected path adds a column and refresh time. Start with the properties the report uses. To add more later, edit the invoked query’s step or invoke Properties again.
Type part of its name in the list’s search box, for example a property set name. The list shows full dotted paths such as properties.Quantities.Qto_SpaceBaseQuantities.NetFloorArea. The resulting column uses the shortest unique end of the path, such as NetFloorArea, unless you set Use full paths to true.
The All tables layout is on. Most reports need only the default Simplified layout: set Table layout to Simplified under Advanced options, or remove [TableLayout = "All tables"] from the Speckle.GetTables call.
Select Connect to Speckle (Custom). Power Query calls this function Speckle - Get Tables, but Get Data uses a different label.
Federate the models in the web app, copy the federated model URL, and paste it into Connect to Speckle (Custom). Objects then includes a Source Model column.
Select Refresh in the Power BI ribbon to load the latest version. If your model URL contains an @ symbol, you loaded a specific version, and the connector loads only that version.
GetTables reads artifact bundles. This version was published before 2026.9 and has not been converted to the 2026.9 format yet, so it contains only JSON. The error message suggests GetByUrl, which is no longer supported. Publish a new version from an updated connector and load that, or contact Speckle support if you need this version as it is.

​
3D visual

No. The installer copies the visual file to your Documents folder. Import that file into your report yourself; there is no automatic update through AppSource.
Power BI Desktop’s embedded WebView2 and Chromium-based browsers viewing Power BI Service both support the visual. Firefox on macOS does not: it supports WebGPU, but allows only eight GPU storage buffer bindings, and the visual needs nine.
Not yet. Filtered-out objects are hidden outright instead of shown dimmed. Section box, view modes, edges, and named scene views are also unavailable.
This is a known rendering issue in the viewer, not specific to Power BI. It shows up most often with objects far from the model origin or in models with very large bounds. The fix ships in the web viewer first, then in the next Power BI visual release.
On the Enterprise plan, select the arrow next to the logo to hide Speckle branding. Other plans can’t hide the Speckle logo.

​
Sign-in and access

  1. Select Get Data from the Home ribbon.
  2. Select Connect to Speckle (Custom).
  3. Paste your model URL in the text box.
  4. If not already signed in, an authentication dialog will appear.
  5. Click Sign in and sign in to your Speckle account from the browser window that opened.
  6. Power BI stores your credentials, so you won’t need to sign in again the next time you load a model.
This is a browser-related issue. To fix it:
  1. Go to File > Options and settings > Options > Security
  2. Under Authentication Browser, clear Use my default web browser
This authentication error can be resolved by adjusting Power BI’s browser settings:
  1. Go to File > Options and settings > Options
  2. Select the Security tab
  3. Under Authentication Browser, clear Use my default web browser
  4. Try loading your model again
If you are trying to load from a different server, you don’t need to do anything. Just load the model from the new server. If you want to switch to a different account in the same server, you’ll need to clear Power BI’s cached authentication data by following these steps:
  1. Close Power BI Desktop completely.
  2. Where do I find my Power BI installation folder?
    • Desktop version (.exe): Navigate to %LocalAppData%\Microsoft\Power BI Desktop (typically C:\Users[your-username]\AppData\Local\Microsoft\Power BI Desktop)
    • Microsoft Store version: Navigate to C:\Users[your-username]\Microsoft\Power BI Desktop Store App
  3. Delete following items:
    • CEF folder
    • WebView2 folder
    • Cache folder
    • User.zip file
  4. Restart Power BI Desktop.
This process will clear all cached data for Power BI Desktop, not just Speckle authentication. You may need to re-authenticate with other data sources as well.
If loading fails, refresh your Speckle credentials and local cache:
  1. Go to File > Options and settings > Data source settings
  2. Select https://app.speckle.systems/ or your server URL
  3. Select Clear Permissions
  4. Restart Power BI and authenticate again
This is usually a network, proxy, or authentication issue rather than a local service dependency. Confirm your server URL, sign in again, and verify your machine can reach your Speckle server.
This error usually means you don’t have the required permissions to load the model.Steps to fix it:
  1. Verify that you have been granted access to the model.
    • If not, contact the project owner and request the necessary permissions.
  2. If you are already added but still see the error, try re-authenticating:
    • In Power BI, go to Data source settings.
    • Select Global permissions, then double-click on app.speckle.systems.
    • Click Edit, choose Speckle Account, and sign in again.
After signing in, reload the URL to check if the error is resolved.If you’re already signed in but can’t sign in with your other account, see How can I switch to a different account in Power BI?
Yes. Both the Power BI connector and 3D visual support private projects.
Viewing and loading a model require different permissions. To load a model in a connector, contact the project owner to change your project role.
No. The Power BI connector has not needed Speckle Desktop Services since version 3.5.0. If your connector asks for it, update the connector.

​
Upgrading reports

No, not any longer. Speckle.GetByUrl and the earlier visual are no longer supported, and a report that follows a model fails once that model gets a version published from 2026.9. If a query calls GetByUrl, rebuild it with Connect to Speckle (Custom) and add the new visual: see Upgrade from 2026.8. Your data is kept, and older versions stay in your models.
The version contains only artifact bundles, which GetByUrl cannot read. The temporary recovery step works only with a version published before 4.0 that still has JSON data. See Why GetByUrl reports fail, then rebuild the query with Connect to Speckle (Custom) as soon as you can.
If the error’s RootObjectId starts with bundle., the version contains only artifact bundles. Some connector releases report this as DirectDownloadFailed instead of JsonRepresentationUnavailable. The fix is the same: rebuild the query with Speckle.GetTables.
The downstream query steps still expect the old flat table and will fail. Rebuild the query from Connect to Speckle (Custom), load Objects, and invoke Properties and Relations.
With 2026.10.0 or later, importing the new file leaves the earlier visual in place. The new visual needs GetTables output before it can display a model; a GetByUrl table cannot supply its required fields. Keep the earlier visual until you have loaded the new tables and checked the report.
Last modified on October 19, 2026