Embed Dashboard > Generate Embed URL API

Learn how to call the Draxlr Generate Embed URL API from your backend to embed a dashboard or a single element, with filters, configuration, an example and errors.

Call this API from your backend each time a signed-in user opens the page with the embed. It returns an embed URL you pass to the frontend code.

The embed builder generates this request for you, with your API key, secret and settings filled in. Copy it from Open embed code with Use backend API on.

Endpoints

To embed a dashboard:

POST https://api.draxlr.com/api/dashboardGroup/generate-embed-url/YOUR_DASHBOARD_ID
Content-Type: application/json

To embed a single dashboard element:

POST https://api.draxlr.com/api/dashboard/generate-embed-url/YOUR_ELEMENT_ID
Content-Type: application/json

Server-side only:

The request includes your API secret. Never call this API from the browser.

Parameters

ParameterTypeRequiredDescription
apiKeystringYesYour organization's embed API key
apiSecretstringYesYour organization's embed API secret
embedOptionsobjectNoFilters, settings and row-level security, below

embedOptions

FieldTypeDescription
filtersobjectValues for the dashboard filters, below
variablesobjectValues for a Raw SQL element's variables, keyed by variable name. Only for single element embeds
configurationobjectHeader, exports, drill downs and appearance, below
rlsGroupstringName of a row-level security group. See Row-level Security
attributesobjectAttribute values for the RLS group's rules, such as { "accountId": 42 }

filters

An object keyed by dashboard filter ID. Each filter takes:

FieldTypeDescription
operatorstringThe filter operator, such as "in" or "between"
valueanyThe filter value, such as ["France"]
hiddenbooleantrue hides the filter from viewers. Its value still applies
hideOperatorbooleantrue lets viewers change only the value, not the operator
"filters": {
  "6af6c8884e05de3a0b84918c": {
    "operator": "in",
    "value": ["France"],
    "hidden": true
  }
}

The easiest way to get the filter IDs, operators and value formats is to set the filters in the builder's Dashboard filters panel and copy the request.

configuration

FieldTypeDescription
hideHeaderbooleanHides the dashboard's name. Dashboard embeds only
showExportbooleanCSV export from individual elements
showExportPdfbooleanPDF export of the dashboard. Dashboard embeds only
showExportExcelbooleanExcel export of the dashboard. Dashboard embeds only
drillDownFieldsobjectFields viewers can group by, keyed by element ID, such as { "ELEMENT_ID": ["ShipCountry"] }
viewDatastring[]IDs of the elements where viewers can use View data
drillThroughstring[]IDs of the elements where viewers can use custom drill downs
backgroundColorstringPage background color. Also decides the light or dark theme. Dashboard embeds only
cardBackgroundColorstringBackground color of element cards
appearanceobjectFonts and custom CSS: fontFamilyUrl, fontFamilyName and customCss. See Appearance
timezonestringTime zone for the dates in Table elements, such as "America/New_York"

Example

curl -X POST https://api.draxlr.com/api/dashboardGroup/generate-embed-url/YOUR_DASHBOARD_ID \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "YOUR_API_KEY",
    "apiSecret": "YOUR_API_SECRET",
    "embedOptions": {
      "filters": {
        "YOUR_FILTER_ID": { "operator": "in", "value": ["France"] }
      },
      "configuration": {
        "hideHeader": true,
        "showExport": true,
        "showExportPdf": true,
        "showExportExcel": false,
        "viewData": ["YOUR_ELEMENT_ID"],
        "backgroundColor": "#ffffff",
        "appearance": {
          "fontFamilyUrl": "https://fonts.googleapis.com/css2?family=Inter",
          "fontFamilyName": "Inter"
        }
      }
    }
  }'

Response

{
  "success": true,
  "embedUrl": "https://app.draxlr.com/embed/dashboard/YOUR_DASHBOARD_ID?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Pass embedUrl to the frontend code as data-embedUrl. Embed URLs are valid for 24 hours, so generate a new one each time the page loads.

If the dashboard has allowed domains, they're written into the embed URL, and it only loads on those domains.

Errors

Errors are returned with success: false and an error message.

ErrorCause
Dashboard not found.No dashboard has this ID
Dashboard item not found.No dashboard element has this ID
Your plan does not support Embedding, please upgrade to use this feature.Your plan doesn't include Embedding
API authentication failedThe key or secret is wrong, or belongs to another organization
rlsGroup must be the name of a row-level security group.rlsGroup is empty or not text
Your plan does not support row-level security.rlsGroup was passed, but your plan doesn't include RLS
Invalid rlsGroup. No row-level security group named "…" exists.No RLS group has that name
attributes must be an object of key-value pairs.attributes isn't an object
attributes.<key> must be a string, number, boolean, or a non-empty array of strings or numbers.An attribute value has an unsupported type
Error getting embed URLSomething else went wrong. Try again