---
source_url: https://www.pubnub.com/docs/analytics/decisions/embed-single-chart
title: Embed a single Illuminate chart with runtime filters
description: Embed one Illuminate Dashboard chart in your portal with an iframe, and filter it at load time by dimension values.
updated_at: 2026-11-20T09:51:54.000Z
---

# Embed a single Illuminate chart with runtime filters

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

This guide shows you how to embed one Illuminate chart in your portal and filter it for a specific context. Complete [Embed the Illuminate UI in your portal](https://www.pubnub.com/docs/analytics/decisions/embed-ui-in-partner-sites.md) first, so you have an access token.

Embed a single chart when you want to show one metric visualization in your app without the full Dashboards UI. For example, show a Dashboard chart filtered to a specific channel or customer.

To embed a chart, use the `charts/<chart-id>` resource path:

```html
<iframe src="https://oem.pubnub.com/embed/charts/<chart-id>?embed=true&token=<token>" width="100%" height="600" style="border: 0" loading="lazy"></iframe>
```

## Find the chart and dimension IDs

A dimension is a text field from a Business Object that a metric groups or filters by, such as a channel name. You need the chart ID to embed the chart and the dimension IDs to filter it.

Retrieve the Dashboard that contains the chart with the [List dashboards](https://www.pubnub.com/docs/admin-api/list-dashboards.md) endpoint. This call requires an Admin API key with read permission for Illuminate. To create one, see the [Admin API introduction](https://www.pubnub.com/docs/admin-api.md).

In the response:

* Use `charts[].id` as `<chart-id>`.
* Use `charts[].name` to confirm you selected the correct chart.
* Use `charts[].dimensionIds` for the dimensions currently configured on that chart.
* Use `charts[].metric.dimensionIds` and `charts[].metric.dimensions[]` (each with `id` and `name`) to find valid dimension IDs and their display names.

Example response shape:

```json
{
  "id": "8f1d3a48-2b5d-49eb-a792-9531c59afcda",
  "name": "Customer dashboard",
  "charts": [
    {
      "id": "chart-123",
      "name": "Events by region",
      "dimensionIds": ["dimension-region"],
      "metric": {
        "id": "metric-123",
        "name": "Events",
        "dimensionIds": ["dimension-channel"],
        "dimensions": [
          { "id": "dimension-channel", "name": "channel" }
        ]
      }
    }
  ]
}
```

## Add runtime filters

Runtime filters limit the chart to specific dimension values when the iframe loads, without changing the chart configuration in the Dashboard. Pass them in the `filters` query parameter. The value is a URL-encoded JSON array of dimension ID and value pairs:

```json
[
  { "dimensionId": "dimension-channel", "dimensionValue": "web12345" }
]
```

URL-encoded, the iframe `src` looks like this:

```html
<iframe src="https://oem.pubnub.com/embed/charts/<chart-id>?embed=true&token=<token>&filters=%5B%7B%22dimensionId%22%3A%22dimension-channel%22%2C%22dimensionValue%22%3A%22web12345%22%7D%5D" width="100%" height="600" style="border: 0" loading="lazy"></iframe>
```

If you pass more than one filter, the chart applies all of them together. Omit `filters` when you don't need runtime filtering.

To hide the decisions section and the **Manage decisions** dialog in a chart embed, add `hideDecisions=true` to the query parameters. This applies only to single-chart embeds.

Last updated at: 2026-11-20T09:51:54.000Z
