add_widget_to_dashboard
Add a widget to an existing New Relic dashboard by providing the dashboard GUID, NRQL query, and optional advanced chart display settings and grid placement.
Instructions
Add a widget to an existing dashboard (requires dashboard GUID and widget configuration).
Use the optional raw_configuration parameter to control advanced chart display settings. When provided,
it is sent as rawConfiguration to NerdGraph and takes precedence over the typed configuration.
The raw_configuration object should include nrqlQueries plus any display options.
IMPORTANT: nrqlQueries uses accountIds (array) not accountId (scalar):
"nrqlQueries": [{"accountIds": [123456], "query": "SELECT ..."}]
This is auto-populated from widget_query if omitted.
Fixed Y-Axis Range (left axis):
{"yAxisLeft": {"min": 0, "max": 500, "zero": false}}
Dual Y-Axis (second axis on right): IMPORTANT: dual y-axis requires the COMPLETE rawConfiguration (not just yAxisRight). NR automatically appends an aggregation suffix to series names: percentile() → " (99%)", average() → no suffix. The alias in the query should NOT include the suffix — NR adds it. Use the rendered name in series[].name. Example — query alias is 'My Series', NR renders it as 'My Series (99%)' for percentile():
{
"nrqlQueries": [{"accountIds": [123456], "query": "SELECT count(*) AS 'Left', percentile(duration, 99) AS 'My Series' FROM ... TIMESERIES"}],
"chartStyles": {"lineInterpolation": "linear"},
"facet": {"showOtherSeries": false},
"legend": {"enabled": true},
"markers": {"displayedTypes": {"criticalViolations": false, "deployments": true, "relatedDeployments": true, "warningViolations": false}},
"platformOptions": {"ignoreTimeRange": false},
"thresholds": {"isLabelVisible": true},
"yAxisLeft": {"zero": true},
"yAxisRight": {"zero": true, "series": [{"name": "My Series (99%)"}]}
}Hide Legend:
{"legend": {"enabled": false}}
Facet - show/hide Other series:
{"facet": {"showOtherSeries": true}}
Ignore dashboard time picker:
{"platformOptions": {"ignoreTimeRange": true}}
Threshold label visibility (shows/hides threshold labels on chart):
{"thresholds": {"isLabelVisible": true}}
Chart line style:
{"chartStyles": {"lineInterpolation": "linear"}} (or "step", "smooth")
Deployment markers:
{"markers": {"displayedTypes": {"deployments": true, "relatedDeployments": true, "criticalViolations": false, "warningViolations": false}}}
Combined example (fixed range + no legend):
{
"nrqlQueries": [{"accountIds": [123456], "query": "SELECT count(*) FROM Log TIMESERIES"}],
"yAxisLeft": {"min": 0, "max": 1000, "zero": true},
"legend": {"enabled": false}
}Note: logarithmic scale is not supported by New Relic for line/area charts.
Placement (layout): dashboards use a 12-column grid (column is 1-based; height 1 ≈ one billboard row, charts are usually 3).
Without layout, New Relic auto-places the widget full-size at the bottom — fine for one-offs, wrong for designed
dashboards. Compact KPI billboard: {"column": 1, "row": 1, "width": 2, "height": 2}; chart in a 3-across row:
{"column": 5, "row": 4, "width": 4, "height": 3}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_guid | Yes | GUID of the dashboard to add widget to | |
| widget_title | Yes | Title for the widget | |
| widget_query | Yes | NRQL query for the widget | |
| widget_type | No | Type of widget (line, area, bar, pie, table, billboard, etc.) | line |
| raw_configuration | No | Advanced chart display configuration sent as rawConfiguration to NerdGraph. Must include 'nrqlQueries' array with accountIds (array, not scalar). Supports: yAxisLeft ({min, max, zero}), yAxisRight ({zero, series:[{name}]}), legend ({enabled}), facet ({showOtherSeries}), platformOptions ({ignoreTimeRange}), thresholds ({isLabelVisible}), chartStyles ({lineInterpolation: linear/step/smooth}), markers ({displayedTypes: {deployments, relatedDeployments, criticalViolations, warningViolations}}). Note: logarithmic scale is NOT supported. Overrides the typed configuration when provided. | |
| layout | No | Widget placement on the dashboard's 12-column grid. Omit to let New Relic auto-place (full-size, bottom of page). |