Do not use the Insights Dashboards API. Instead, use the New Relic One Dashboards API with NerdGraph, our GraphQL API.
End of life notice
The Insights Dashboard API reaches end of life in 2021.
- As of July 28, 2021, the
CREATE
andUPDATE
endpoints are not available. - As of August 30, 2021, the
GET
andDELETE
endpoints are not available.
To make the transition from the Insights Dashboard API to the New Relic One Dashboards API, see our migration guide. For more information, see the NerdGraph dashboards tutorial and Explorers Hub post.
Requirements
If your account hosts data in the EU data center, ensure you're using the proper API endpoints for EU region accounts.
Overview
The Insights Dashboard API allows you to list, create, read, update, and delete new or existing dashboards. New Relic's API Explorer includes the cURL request format, available parameters, response status codes, and JSON response structure for available API calls.
Example use cases
The Insights Dashboard API is a flexible solution for many different use cases. Here are a few examples of how you can leverage the Dashboard API to solve problems:
- Automatically create dashboards for new teams or services pre-populated with standard organization metrics and charts.
- Use the API to view dashboard schemas, and save them in a central repository for source control and backups.
- Create widget and dashboard templates to allow teams to self-service.
Account and data security
The Dashboard API includes safeguards to help ensure account and data security.
Requirements | Comments |
---|---|
User key and permissions | Required: This API requires a user key. You cannot use your account-level REST API key to manage dashboards. |
Cross-account widgets | You can view cross-account widgets on a dashboard by using the Insights or New Relic One dashboards UI. However, the ability to view cross-account widgets when using the Dashboard API has these restrictions:
|
Use the API Explorer
To view the Dashboard API options in the API Explorer:
- Log in to your New Relic account.
- Go to rpm.newrelic.com/api/explore.
- From the API Explorer's Select an account and key dropdown, select a user key.
- Select Dashboards, then select the API function.
- To use API functions with existing dashboards, include the dashboard
id
. To find the dashboardid
, select theLIST
endpoint, and apply filtering options.
View Dashboard API video
Follow along with this step-by-step tutorial to learn how to find your API keys, create new dashboards, view and update existing dashboards via the REST API.
For a step-by-step guide to using the New Relic API Explorer to manage Insights dashboards, watch this video (approximately 6 minutes). Or, go directly to the full online course about New Relic APIs.
Use API endpoints
The API supports the following functions for Insights dashboards only. The API does not support these functions for data apps (collections of linked dashboards).
API endpoints | Comments |
---|---|
| Create a new dashboard. The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to POST more than 300 widgets will produce an error. To add more widgets to the dashboard, use the Insights UI. |
| Update an existing dashboard for the dashboard The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to PUT more than 300 widgets will produce an error. To add more or edit existing widgets on the dashboard, use the Insights UI. |
| View an existing dashboard and all accessible widgets for the dashboard To help ensure data security, the |
| View a paginated list of dashboards. The list shows filterable dashboard metadata only; no widgets will appear in the list. Search options include:
|
| Delete an existing dashboard indicated by the dashboard |
Dashboard API schema
JSON is the only supported format. When using API functions, be sure to add .json
to the end of the request URL, as shown in the API Explorer.
Important
Widgets have a size limit of 3x3 (height
and width
may not exceed 3).
Caution
The Dashboard API 3-column restriction also applies to the dashboards you upload to New Relic One dashboards. If you update a dashboard with a different layout using the API, the uploaded dashboard will revert to the 3-column configuration.
Dashboard data definitions
For examples of these data elements being used in a JSON call, see the Dashboard API schema.
Dashboard data element | Description |
---|---|
Object | Specifies the version of the dashboard schema. The version must be 1. |
String | Name of an icon from the Insights icon library. |
Integer | Specifies the number of columns in the grid layout. |
String | User-supplied title of the dashboard. |
Object | Specifies configuration of the smart filter on the dashboard. |
String | Specifies who can view the dashboard in the Insights UI and the API. |
String | Specifies who can edit the dashboard in the Insights UI and the API. |
Array | Array of widget data element objects. |
Widget data definitions
For examples of these data elements being used in a JSON call, see the Dashboard API schema.
Widget data element | Description |
---|---|
String | What sort of visualization to place in the widget; for example, billboard, line_chart, area chart, etc. |
Array | Array of objects with chart-specific information needed to query necessary data. Currently only one data object is supported. |
Long | Source account to fetch data from, if not the current account. |
Object | Object with chart title and notes, plus chart-specific customization. |
Object | Object with column, row, width, and height to determine chart layout in the dashboard. |
Supported visualizations
The Dashboard API supports:
event_tableline_chartfacet_tablefacet_bar_chartfacet_pie_chartbillboardfaceted_area_chartfaceted_line_chartevent_tablecomparison_line_chartheatmaphistogrambillboard_comparisonattribute_sheetfunnelgaugejsonlist
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's and and documentation.