Embed a report

Tip

Try embedding a report or experiment with our client APIs in the Explore our APIs section of the Power BI Embedded Analytics Playground.

This article covers the steps for embedding a Power BI report in your application. Learn more about reports in Reports in Power BI.

How to embed a report

When you embed Power BI content in an app, you use a configuration object to define the content that you're embedding and to specify the content's settings. Then you pass that object to the API. See Configure report settings for more information.

Embed an existing report

When you embed a report that already exists, use a configuration object of type IReportLoadConfiguration.

interface IReportLoadConfiguration {
    accessToken: string;
    bookmark?: models.IApplyBookmarkRequest;
    contrastMode?: models.ContrastMode;
    datasetBinding?: models.IDatasetBinding;
    embedUrl?: string;
    filters?: models.ReportLevelFilters[];
    id: string;
    pageName?: string;
    permissions?: models.Permissions;
    settings?: models.IEmbedSettings;
    slicers?: models.ISlicer[];
    theme?: models.IReportTheme;
    tokenType?: models.TokenType;
    type: string;
    viewMode?: models.ViewMode;
}

This interface includes these properties:

• accessToken - The token that gives you access to the Power BI data that you're embedding. See Understand the different embedding solutions to learn more about access tokens.

• datasetBinding - The dataset that defines the data schema that the embedded report uses. See Bind datasets dynamically to a report for more information on datasets.

• embedUrl - The URL of the report that you're embedding. This URL becomes the source of the HTML iframe element that contains the embedded report. Specifically, the API assigns the URL to the src attribute of the iframe. You can use a Report API to obtain this URL. Two examples are:

  • Reports - Get Report In Group
  • Reports - Get Reports In Group

• id - The ID of the Power BI report that you're embedding.

• permissions - Operations that you grant to users for the embedded report. These values are available:

  • Read - Users can view the report.
  • ReadWrite - Users can view, edit, and save the report.
  • Copy - Users can save a copy of the report by using Save As.
  • Create - Users can create a new report.
  • All - Users can create, view, edit, save, and save a copy of the report.

• tokenType - The kind of token that gives you access to the Power BI data that you're embedding.

  • Use models.TokenType.Aad if you're embedding for your organization (the user owns the data).
  • Use models.TokenType.Embed if you're embedding for your customers (the app owns the data).

  See Understand the different embedding solutions for more information.

• type - The kind of content that you're embedding. Use 'report' for a Power BI report.

The IReportLoadConfiguration interface also contains other properties. See Configure report settings for information on these properties:

• bookmark
• contrastMode
• filters
• pageName
• settings
• slicers
• theme
• viewMode

Embed a new report

When you embed a new report that you create from a dataset, use a configuration object of type IReportCreateConfiguration.

interface IReportCreateConfiguration {
    accessToken: string;
    datasetId: string;
    embedUrl?: string;
    settings?: models.IEmbedSettings;
    theme?: IReportTheme;
    tokenType?: models.TokenType;
    type: string;
}

The properties in this interface are similar to the properties in the IReportLoadConfiguration interface, with the following exceptions:

• datasetId - The ID of the dataset that defines the data schema that the new report uses.

• embedUrl - The URL of the dataset that defines the data schema that the new report uses. This URL becomes the source of the HTML iframe element that contains the embedded report. Specifically, the API assigns the URL to the src attribute of the iframe. You can use a Datasets API to obtain this URL. Two examples are:

  • Datasets - Get Dataset In Group
  • Datasets - Get Datasets In Group

See Create, edit, and save an embedded report for information on editing and creating reports.

Example

The following example shows how to embed a report:

// Set up the configuration object that determines what to embed and how to embed it.
let embedConfiguration = {
    accessToken: anAccessToken,
    embedUrl: anEmbedUrl,
    id: aReportId,
    permissions: somePermissions,
    tokenType: aTokenType,
    type: 'report'
};
 
// Get a reference to the HTML element that contains the embedded report.
let embedContainer = $('#embedContainer')[0];
 
// Embed the report.
let report = powerbi.embed(embedContainer, embedConfiguration);

Next steps

Embed a report visual

Embed a paginated report

Configure report settings

Create, edit, and save a report

Use bootstrap for better performance