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
| Parameter | Type | Required | Description |
|---|---|---|---|
apiKey | string | Yes | Your organization's embed API key |
apiSecret | string | Yes | Your organization's embed API secret |
embedOptions | object | No | Filters, settings and row-level security, below |
embedOptions
| Field | Type | Description |
|---|---|---|
filters | object | Values for the dashboard filters, below |
variables | object | Values for a Raw SQL element's variables, keyed by variable name. Only for single element embeds |
configuration | object | Header, exports, drill downs and appearance, below |
rlsGroup | string | Name of a row-level security group. See Row-level Security |
attributes | object | Attribute values for the RLS group's rules, such as { "accountId": 42 } |
filters
An object keyed by dashboard filter ID. Each filter takes:
| Field | Type | Description |
|---|---|---|
operator | string | The filter operator, such as "in" or "between" |
value | any | The filter value, such as ["France"] |
hidden | boolean | true hides the filter from viewers. Its value still applies |
hideOperator | boolean | true 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
| Field | Type | Description |
|---|---|---|
hideHeader | boolean | Hides the dashboard's name. Dashboard embeds only |
showExport | boolean | CSV export from individual elements |
showExportPdf | boolean | PDF export of the dashboard. Dashboard embeds only |
showExportExcel | boolean | Excel export of the dashboard. Dashboard embeds only |
drillDownFields | object | Fields viewers can group by, keyed by element ID, such as { "ELEMENT_ID": ["ShipCountry"] } |
viewData | string[] | IDs of the elements where viewers can use View data |
drillThrough | string[] | IDs of the elements where viewers can use custom drill downs |
backgroundColor | string | Page background color. Also decides the light or dark theme. Dashboard embeds only |
cardBackgroundColor | string | Background color of element cards |
appearance | object | Fonts and custom CSS: fontFamilyUrl, fontFamilyName and customCss. See Appearance |
timezone | string | Time 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.
| Error | Cause |
|---|---|
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 failed | The 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 URL | Something else went wrong. Try again |