The Insights Dashboard API is deprecated, but you can use NerdGraph (our GraphQL API) to create and configure dashboards.
If you're not migrating from the old Insights API, you can skip this doc and go to the new Dashboards API.
Why a new dashboards API?
Our Insights product, which was a way to query data and create charts and dashboards, has been deprecated and its set of features moved over to be a core part of the New Relic One platform. To learn more about this transition and new features, see the Insights to New Relic One migration guide.
The Insights Dashboard API will be deprecated in July of 2021. Until then, if you're using the Insights Dashboard API, you should attempt to switch over to using NerdGraph. (The Insights query API will not be deprecated but NerdGraph is preferred.) Keep reading to learn how to get started with NerdGraph and learn about equivalent operations.
Get started with NerdGraph
NerdGraph is the preferred API for making NRQL queries of your New Relic data. Every user who uses NerdGraph needs their own user key.
When using NerdGraph, it helps to understand that our dashboards are entities that report data from other entities, such as monitored apps, hosts and services.
If you're new to NerdGraph and GraphQL, you may want to first read our Introduction to NerdGraph and some of Create dashboards with NerdGraph.
The NerdGraph API explorer is located at api.newrelic.com/graphiql.
Operations mapping table
The table below maps every Insights API operation to the new dashboards API.
Insights API operation | NerdGraph API query/mutation | Notes |
---|---|---|
List (GET) | entitySearch() | View a paginated list of dashboards that match the filter. |
Show (GET) | entity() | View an existing dashboard given its entity guid. |
Create (POST) | dashboardCreate() | Create a new dashboard. |
Update (PUT) | dashboardUpdate() | Update an existing dashboard given its entity guid. |
Delete (DELETE) | dashboardDelete() | Delete an existing dashboard given its entity guid. |
Dashboard properties mapping table
For more information about all the fields in the new dashboards GraphQL schema, have a look at NerdGraph's GraphiQL explorer.
The table below maps dashboard properties from the Insights API to the new dashboards API.
Insights API dashboard property | NerdGraph API dashboard property | Notes |
---|---|---|
id | guid | ID of the New Relic entity the dashboard now represents |
createdAt | createdAt | |
updatedAt | updatedAt | |
title | name | |
editable | permissions | editable and visibility merged in the same concept |
visibility | permissions | editable and visibility merged in the same concept |
description | description | |
metadata | - | No need of versioning in GraphQL APIs |
icon | - | Not translated to New Relic One |
grid_column_count | - | 12 column dashboards by default in New Relic One |
filter | - | Not translated to New Relic One yet |
Widget properties mapping table
For more information about all the fields in the new dashboards GraphQL schema, have a look at NerdGraph's GraphiQL explorer.
The table below maps widget properties from the Insights API to the new dashboards API.
Insights API dashboard property | NerdGraph API dashboard property | Notes |
---|---|---|
id | id | |
account_id | - | Translated into widget configuration for those that require one |
visualization | visualization | |
presentation.title | title | |
presentation.drilldown_dashboard_id | linkedEntities | Used to link a widget to a dashboard for the facet linking feature |
presentation.notes | - | Not translated to New Relic One yet |
layout | layout | |
data | configuration + rawConfiguration |
Tip
To learn how to build every type of widget, see Create dashboard widgets.
Visualizations mapping table
We have simplified our widget visualizations by grouping the ones that were in fact the same but obtained through different types of queries. For instance, a line widget is plotted the same way regardless of the type of query: old line_chart
vs. comparison_line_chart
in Insights.
Insights API visualization | NerdGraph API visualization |
---|---|
uniques_list | viz.table |
single_event | viz.table |
facet_table | viz.table |
event_table | viz.table |
faceted_area_chart | viz.area |
predefined_metric_chart.application_breakdown | viz.area |
predefined_metric_chart.scope_breakdown | viz.area |
predefined_metric_chart.browser_breakdown | viz.area |
predefined_metric_chart.background_breakdown | viz.area |
predefined_metric_chart.solr_breakdown | viz.area |
predefined_metric_chart.gc_runs_breakdown | viz.area |
facet_bar_chart | viz.bar |
billboard | viz.billboard |
attribute_sheet | viz.billboard |
billboard_comparison | viz.billboard |
gauge | viz.bullet |
event_feed | viz.event-feed |
funnel | viz.funnel |
heatmap | viz.heatmap |
histogram | viz.histogram |
inventory | infra.inventory |
raw_json | viz.json |
line_chart | viz.line |
comparison_line_chart | viz.line |
faceted_line_chart | viz.line |
metric_line_chart | viz.line |
markdown | viz.markdown |
facet_pie_chart | viz.pie |
Examples: from REST endpoints to GraphQL queries/mutations
One of the main benefits of NerdGraph being a GraphQL-format API is that it provides a complete and understandable description of the APIs' data. By using the NerdGraph API explorer, you can discover GraphQL types and fields, along with a brief explanation.
We want to facilitate your migration from the Insights API to the new New Relic One dashboards API. Find below some examples that illustrate how the old REST endpoints map to the new GraphQL queries or mutations.
List (GET) -> entitySearch query
Dashboards in New Relic One embrace the concept of entity. They are now another entity in New Relic’s entity ecosystem.
Try it out using the NerdGraph GraphiQL explorer.
Show (GET) -> entity query
In order to get information on a dashboard, all you need is to provide its unique entity identifier or entity guid. Then you can access all the dashboard properties that you are interested in by adding them in the GraphQL query.
Try it out using the NerdGraph GraphiQL explorer.
Create (POST) -> dashboardCreate mutation
Operations that mutate the state of the system are mutations in GraphQL APIs. You can create a dashboard by providing the required input for the dashboardCreate
mutation. Although GraphQL APIs aim to be self-explanatory, Nerdgraph docs can help you with some information about the fields, like the doc about how to build dashboard widgets.
Try it out using the NerdGraph GraphiQL explorer.
Update (PUT) -> dashboardUpdate mutation
The dashboardUpdate
mutation allows you to update an existing dashboard by providing the existing dashboard guid and the new configuration. Similarly to creating a dashboard, the mutation tries to be self-explanatory, but you can look up the doc about how to build dashboard widgets.
Try it out using the NerdGraph GraphiQL explorer.
Delete (DELETE) -> dashboardDelete mutation
The dashboardDelete
mutation allows you to delete an existing dashboard by providing its entity guid.
Try it out using the NerdGraph GraphiQL explorer.
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.