Dashboard API migration: from Insights API to NerdGraph

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

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.

{
    actor {
      entitySearch(queryBuilder: {type: DASHBOARD}) {
        results {
          entities {
            ... on DashboardEntityOutline {
              guid
              name
              accountId
            }
          }
        }
      }
    }
  }

{
    actor {
      entitySearch(queryBuilder: {name: "My dashboard"}) {
        results {
          entities {
            ... on DashboardEntityOutline {
              guid
              name
              accountId
            }
          }
        }
      }
    }
  }

{
    actor {
      entitySearch(queryBuilder: {type: DASHBOARD, tags: {key: "createdBy", value: "email@domain.com"}}) {
        results {
          entities {
            ... on DashboardEntityOutline {
              guid
              name
              accountId
            }
          }
        }
      }
    }
  }

{
    actor {
      entitySearch(query: "type ='DASHBOARD' and ownerId = '2357322'") {
        results {
          entities {
            ... on DashboardEntityOutline {
              guid
              name
              accountId
            }
          }
        }
      }
    }
  }

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.

{
    actor {
      entity(guid: "MY_DASHBOARD_GUID") {
        ... on DashboardEntity {
          guid
          accountId
          name
          createdAt
          updatedAt
          permissions
          description
          owner { email userId }
          pages {
            guid
            name
            createdAt
            updatedAt
            description
            owner { email userId }
            widgets {
              id
              visualization { id }
              title
              layout { row column height width }
              rawConfiguration
              linkedEntities { guid }
            }
          }
        }
      }
    }
  }

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.

mutation {
    dashboardCreate(accountId: 1, dashboard: {
      name: "My awesome dashboard",
      permissions: PUBLIC_READ_WRITE,
      pages: [{
        name: "My first page",
        widgets: [{
          visualization: { id: "viz.markdown" },
          title: "My markdown widget",
          layout: {
            row: 1,
            column: 1,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            text: "#My markdown"
          }
        }, {
          visualization: { id: "viz.line" },
          title: "My line widget",
          layout: {
            row: 1,
            column: 5,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            nrqlQueries: [{
              accountId: 1,
              query: "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
            }]
          }
        }]
      }, {
        name: "My second page",
        widgets: [{
          visualization: { id: "viz.billboard" },
          title: "My billboard widget with thresholds",
          layout: {
            row: 1,
            column: 1,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            nrqlQueries: [{
              accountId: 1,
              query: "SELECT count(*) FROM Transaction"
            }],
            thresholds: [{
              alertSeverity: WARNING,
              value: 650
            }, {
              alertSeverity: CRITICAL,
              value: 1500
            }]
          }
        }, {
          visualization: { id: "viz.table" },
          title: "My table widget",
          layout: {
            row: 1,
            column: 5,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            nrqlQueries: [{
              query: "SELECT * FROM Transaction",
              accountId: 1
            }]
          }
        }]
      }]
    }) {
      errors {
        description
        type
      }
      entityResult {
        guid
        accountId
        name
        createdAt
        updatedAt
        permissions
        description
        owner { email userId }
        pages {
          guid
          name
          createdAt
          updatedAt
          description
          owner { email userId }
          widgets {
            id
            visualization { id }
            title
            layout { row column height width }
            rawConfiguration
            linkedEntities { guid }
          }
        }
      }
    }
  }

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.

mutation {
    dashboardUpdate(guid: "MY_DASHBOARD_GUID" dashboard: {
      name: "My awesome dashboard",
      permissions: PUBLIC_READ_WRITE,
      pages: [{
        name: "My first page",
        widgets: [{
          visualization: { id: "viz.line" },
          title: "My line widget",
          layout: {
            row: 1,
            column: 1,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            nrqlQueries: [{
              accountId: 1,
              query: "SELECT count(*) FROM Transaction FACET appName TIMESERIES"
            }]
          }
        }]
      }, {
        name: "My second page",
        widgets: [{
          visualization: { id: "viz.table" },
          title: "My table widget",
          layout: {
            row: 1,
            column: 1,
            width: 4,
            height: 3
          },
          rawConfiguration: {
            nrqlQueries: [{
              query: "SELECT * FROM Transaction",
              accountId: 1
            }]
          }
        }]
      }]
    }) {
      errors {
        description
        type
      }
      entityResult {
        guid
        accountId
        name
        createdAt
        updatedAt
        permissions
        description
        owner { email userId }
        pages {
          guid
          name
          createdAt
          updatedAt
          description
          owner { email userId }
          widgets {
            id
            visualization { id }
            title
            layout { row column height width }
            rawConfiguration
            linkedEntities { guid }
          }
        }
      }
    }
  }

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.

Dashboard API migration: from Insights API to NerdGraph

Why a new dashboards API?

Get started with NerdGraph

Operations mapping table

Dashboard properties mapping table

Widget properties mapping table

Tip

Visualizations mapping table

Examples: from REST endpoints to GraphQL queries/mutations

List (GET) -> entitySearch query

List all dashboard entities you have access to

List all dashboards by name

List all dashboards by creator’s email

List all dashboards by creator’s user id

Show (GET) -> entity query

Get dashboard info given its entity guid

Create (POST) -> dashboardCreate mutation

Create dashboard with two pages and two widgets per page

Update (PUT) -> dashboardUpdate mutation

Update previously created dashboard to 1 page and 1 widget per page

Delete (DELETE) -> dashboardDelete mutation

Delete previously created dashboard