NerdGraph tutorial: Create and manage dashboards

You can use our NerdGraph API to create and manage .

Overview

For an introduction to our custom dashboards feature, see the dashboards docs.

When using NerdGraph to configure dashboards, it helps to understand that our dashboards are considered entities, which have their own entity IDs, similar to other things we consider entities, like monitored apps, hosts, and services.

For how to add and configure widgets and charts in a dashboard, see Configure charts and other widgets.

Dashboard CRUD operations

This document explains how to use our NerdGraph API to create, read, update, and delete dashboards (CRUD). These operations modify the entire dashboard.

Create a dashboard

A dashboard requires at least one page. You can create a dashboard with one or more pages, and each page can have one or more widgets.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to create a new dashboard and its configuration.
Ensure to include all required fields, such as name, permissions, and at least one page.

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "My New Dashboard"
      description: "This is my new dashboard created via NerdGraph"
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: "This is the first page"
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Total Transaction Count"
              rawConfiguration: {
                nrqlQueries: [
                  { accountIds: [1], query: "SELECT count(*) FROM Transaction" }
                ]
              }
            }
          ]
        }
      ]
      variables: [
        {
          name: "nrql_variable"
          title: "countries"
          type: NRQL
          nrqlQuery: {
            accountIds: [1]
            query: "SELECT uniqueCount(countryCode) FROM PageView"
          }
          replacementStrategy: STRING
        }
      ]
    }
  ) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

We recommend using variables to make it easier to update your queries. Here’s the same mutation as above, but using variables:

mutation CreateDashboard($accountId: Int!, $dashboard: DashboardInput!) {
  dashboardCreate(accountId: $accountId, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

And here are the variables to use with this mutation:

{
  "accountId": 1,
  "dashboard": {
    "name": "My New Dashboard",
    "description": "This is my new dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "name": "Page 1",
        "description": "This is the first page",
        "widgets": [
          {
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Total Transaction Count",
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

Read a dashboard

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use actor > entity() to find the dashboard by its entity GUID.
Use NerdGraph's dashboard API to read the existing dashboard and its configuration.

In this example, replace DASHBOARD_GUID with the actual GUID of the dashboard you want to read:

query GetDashboardEntityQuery {
  actor {
    entity(guid: "DASHBOARD_GUID") {
      ... on DashboardEntity {
        guid
        name
        description
        createdAt
        updatedAt
        owner {
          email
          userId
        }
        permissions
        pages {
          guid
          name
          description
          createdAt
          updatedAt
          widgets {
            id
            visualization {
              id
            }
            layout {
              column
              row
              height
              width
            }
            title
            linkedEntities {
              guid
            }
            rawConfiguration
          }
        }
        variables {
          name
          items {
            title
            value
          }
          defaultValues {
            value {
              string
            }
          }
          nrqlQuery {
            accountIds
            query
          }
          options {
            excluded
            ignoreTimeRange
            showApplyAction
          }
          title
          type
          isMultiSelection
          replacementStrategy
        }
      }
    }
  }
}

Depends on the information you want to retrieve, you can modify the fields in the query.

Update a dashboard

To update a dashboard, you need to provide the complete configuration of the dashboard, including all its pages and widgets, even if you're only updating one element. The update operation is a full replacement of the dashboard's content.

Important

When updating a dashboard, if the page guid or widget id are not provided, the existing pages or widgets will be removed from the dashboard and replaced with the new ones specified in the mutation.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to get the existing dashboard configuration using reading the dashboard by its entity GUID, as shown in the Read a dashboard section.
Modify the fields you want to update in the dashboard configuration.
Use NerdGraph's dashboard API to update the existing dashboard with the modified configuration.

Important

If you are using Facet Linking in your widgets, when reading the dashboard the field is linkedEntities { guid } but when updating the dashboard you need to use linkedEntityGuids: [ "GUID" ].

mutation UpdateDashboard(
  $guid: EntityGuid!
  $dashboard: DashboardUpdateInput!
) {
  dashboardUpdate(guid: $guid, dashboard: $dashboard) {
    entityResult {
      guid
      name
      description
      createdAt
      updatedAt
      owner {
        email
        userId
      }
      permissions
      pages {
        guid
        name
        description
        createdAt
        updatedAt
        widgets {
          id
          visualization {
            id
          }
          layout {
            column
            row
            height
            width
          }
          title
          linkedEntities {
            guid
          }
          rawConfiguration
        }
      }
      variables {
        name
        items {
          title
          value
        }
        defaultValues {
          value {
            string
          }
        }
        nrqlQuery {
          accountIds
          query
        }
        options {
          excluded
          ignoreTimeRange
          showApplyAction
        }
        title
        type
        isMultiSelection
        replacementStrategy
      }
    }
    errors {
      type
      description
    }
  }
}

And here are the variables to use with this mutation:

{
  "guid": "DASHBOARD_GUID",
  "dashboard": {
    "name": "My Updated Dashboard",
    "description": "This is my updated dashboard created via NerdGraph",
    "permissions": "PUBLIC_READ_WRITE",
    "pages": [
      {
        "guid": "PAGE_GUID",
        "name": "Updated Page 1",
        "description": "This is the updated first page",
        "widgets": [
          {
            "id": "WIDGET_ID",
            "visualization": { "id": "viz.billboard" },
            "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
            "title": "Updated Total Transaction Count",
            "linkedEntityGuids": [],
            "rawConfiguration": {
              "nrqlQueries": [
                {
                  "accountIds": [1],
                  "query": "SELECT count(*) FROM Transaction"
                }
              ]
            }
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "nrql_variable",
        "title": "countries",
        "type": "NRQL",
        "nrqlQuery": {
          "accountIds": [1],
          "query": "SELECT uniqueCount(countryCode) FROM PageView"
        },
        "replacementStrategy": "STRING"
      }
    ]
  }
}

Delete a dashboard

To delete a dashboard, you need to provide the entity GUID of the dashboard you want to delete. This operation executes a logical delete that lets you recover your dashboard.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to delete the dashboard by its entity GUID.
Confirm the deletion by checking the status and the errors.

Undelete a dashboard

You can recover a previously deleted dashboard given a dashboard entity GUID. Custom tags cannot be recovered.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to undelete the dashboard by its entity GUID.
Confirm the undeletion by checking errors if any.

Dashboard page operations

This operations modify a specific page of a dashboard.

Update a dashboard page

You can update one page of an existing dashboard given a dashboard page entity GUID. You need to specify the complete, updated dashboard page elements, from metadata to widget configuration.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to get the existing dashboard configuration using reading the dashboard by its entity GUID, as shown in the Read a dashboard section.
Identify and extract the page you want to update from the dashboard.
Modify the fields you want to update in the page.
Use dashboardUpdatePage() to modify the page.
Check errors if any.

Important

When updating a page, if widget ids are not provided, the existing widgets will be removed from the dashboard and replaced with the new ones specified in the mutation.

Tip

You can add new widgets to a page by including them in the widgets array without an id field.
You can remove widgets from a page by omitting them from the widgets array.

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

And here are the variables to use with this mutation:

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      }
    ]
  }
}

mutation UpdateDashboardPage(
  $pageGuid: EntityGuid!
  $page: DashboardUpdatePageInput!
) {
  dashboardUpdatePage(guid: $pageGuid, page: $page) {
    errors {
      type
      description
    }
  }
}

And here are the variables to use with this mutation:

{
  "guid": "PAGE_GUID",
  "page": {
    "name": "Updated Page 1",
    "description": "This is the updated first page",
    "widgets": [
      {
        "id": "WIDGET_ID",
        "visualization": { "id": "viz.billboard" },
        "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
        "title": "Updated Total Transaction Count",
        "linkedEntityGuids": [],
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM Transaction"
            }
          ]
        }
      },
      {
        "visualization": { "id": "viz.line" },
        "layout": { "column": 5, "row": 1, "height": 3, "width": 4 },
        "title": "New Line Chart",
        "rawConfiguration": {
          "nrqlQueries": [
            {
              "accountIds": [1],
              "query": "SELECT count(*) FROM PageView TIMESERIES"
            }
          ]
        }
      }
    ]
  }
}

Updates widgets in a page

You can update a set of existing widgets of a dashboard page given a dashboard page entity GUID. You need to specify the set of widgets to be updated and their complete configuration.

Important

This operations doesn't allow to add or remove widgets from a page. To add or remove widgets, use the Update a dashboard page operation.

Go to the NerdGraph GraphiQL explorer at api.newrelic.com/graphiql.
Use NerdGraph's dashboard API to get the existing dashboard configuration using reading the dashboard by its entity GUID, as shown in the Read a dashboard section.
Identify and extract the widgets in the page you want to update from the dashboard.
Modify the fields you want to update in the widgets.
Use dashboardUpdateWidgetsInPage() to modify the widgets.
Check errors if any.

mutation UpdateWidgetsInPage(
  $pageGuid: EntityGuid!
  $widgets: [DashboardUpdateWidgetInput!]!
) {
  dashboardUpdateWidgetsInPage(guid: $pageGuid, widgets: $widgets) {
    errors {
      type
      description
    }
  }
}

And here are the variables to use with this mutation:

{
  "guid": "PAGE_GUID",
  "widgets": [
    {
      "id": "WIDGET_ID",
      "visualization": { "id": "viz.billboard" },
      "layout": { "column": 1, "row": 1, "height": 3, "width": 4 },
      "title": "Updated Total Transaction Count",
      "linkedEntityGuids": [],
      "rawConfiguration": {
        "nrqlQueries": [
          {
            "accountIds": [1],
            "query": "SELECT count(*) FROM Transaction"
          }
        ]
      }
    }
  ]
}

Other operations

Operation	GraphQL operation type	Notes
`dashboardCreateSnapshotUrl()`	mutation	Create dashboard page snapshot operation. You can create a public URL for a given dashboard page entity GUID. The dashboard page can then be accessed in the form of a static snapshot in the resulting public URL. The resulting URL will be deprecated three months after creation. See Manage dashboard snapshots via API for more information.
`actor > dashboard > liveUrls()`	query	List all live URLs operation. You can get the complete list of live URLs you have access to. A live URL is a mechanism that allows you to share dashboard pages and widgets publicly with up-to-date or live data. See Manage live chart URLs via API for more information.
`dashboardWidgetRevokeLiveUrl()`	mutation	Revoke widget live URL operation. You can revoke a previously created live URL of a widget. As a result, the live URL will become unavailable to the public. See Manage live chart URLs via API for more information.
`dashboardCreateLiveUrl()`	mutation	Create publicly accessible live dashboard URL. See Create, update, and revoke public sharing dashboard URLs for more information.
`dashboardUpdateLiveUrl()`	mutation	Update the expiration date of a publicly accessible live dashboard URL. See Create, update, and revoke public sharing dashboard URLs for more information.
`dashboardRevokeLiveUrl()`	mutation	Revoke publicly accessible live dashboard URL. See Create, update, and revoke public sharing dashboard URLs for more information.
`dashboardUpdateLiveUrlCreationPolicies()`	mutation	Only an Authentication Domain Manager can use this mutation to enable or disable the Live URL Creation policy for accounts. Users can create live URLs for dashboards in accounts where this policy is enabled.

Cross-account dashboards

With NerdGraph, you can create queries of data from more than one New Relic account. You can also create a dashboard using data from across multiple accounts by adding account IDs to the accountIds array.

Here's an example of creating a cross-account dashboard:

mutation {
  dashboardCreate(
    accountId: 1
    dashboard: {
      name: "Cross account queries - NerdGraph API - Cross Account Test1"
      description: null
      permissions: PUBLIC_READ_WRITE
      pages: [
        {
          name: "Page 1"
          description: null
          widgets: [
            {
              visualization: { id: "viz.billboard" }
              layout: { column: 1, row: 1, height: 3, width: 4 }
              title: "Cross Account Total Transaction Count"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.pie" }
              layout: { column: 5, row: 1, height: 3, width: 4 }
              title: "Cross Account Pie"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId()"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
            {
              visualization: { id: "viz.line" }
              layout: { column: 9, row: 1, height: 3, width: 4 }
              title: "Cross Account Line"
              rawConfiguration: {
                legend: { enabled: true }
                nrqlQueries: [
                  {
                    accountIds: [1, 1606862, 2212585]
                    query: "SELECT count(*) FROM Transaction FACET accountId() TIMESERIES"
                  }
                ]
                yAxisLeft: { zero: true }
              }
              linkedEntityGuids: null
            }
          ]
        }
      ]
    }
  ) {
    errors {
      description
      type
    }
  }
}

Limits

We have limited the values you can set to some of the dashboard properties. This allows us to keep dashboards in good shape while boosting their usability.

Dashboard limits

Limit	Value
Maximum number of pages in a dashboard	25
Maximum length of a dashboard name	255
Maximum length of a dashboard description	1024

Dashboard page limits

Limit	Value
Maximum number of widgets in a dashboard page	150
Maximum length of a dashboard page name	255
Maximum length of a dashboard page description	1024

Limit	Value
Maximum length of a widget title	255
Maximum number of entities linked to a widget	1
Maximum number of queries in a widget	20
Maximum layout column of a widget	12
Minimum layout column of a widget	1
Minimum layout row of a widget	1
Maximum layout width of a widget	12
Minimum layout width of a widget	1
Maximum layout height of a widget	32
Minimum layout height of a widget	1

Errors as first class citizens

All dashboard mutations offer a way to ask for errors when being executed. This means that you can perform your dashboard mutations and check the response in order to detect expected potential issues. Every error has a type and a description to help you identify what’s the source of the problem.

Keep in mind that these are expected errors that we are aware of in advance. You should also check for unexpected errors that will be returned in the standard GraphQL errors field.

NerdGraph tutorial: Create and manage dashboards

Overview

Dashboard CRUD operations

Create a dashboard

Dashboard with one page, one widget and one variable

Create dashboard using GraphQL variables

Read a dashboard

Update a dashboard

Important

Important

Update dashboard using GraphQL variables

Delete a dashboard

Delete a dashboard

Undelete a dashboard

Undelete a dashboard

Dashboard page operations

Update a dashboard page

Important

Tip

Update a page

Update a page adding new widgets

Updates widgets in a page

Important

Other operations

Cross-account dashboards

Dashboard with cross-account query

Limits

Dashboard limits

Dashboard page limits

Widget limits

Errors as first class citizens

Errors as part of every mutation response

NerdGraph tutorial: Create and manage dashboards

Overview .css-21sua1{background:none;border:none;width:0;padding:0;}

Dashboard CRUD operations

Create a dashboard

Create dashboard using GraphQL variables

Read a dashboard

Update a dashboard

Important

Important

Update dashboard using GraphQL variables

Delete a dashboard

Delete a dashboard

Undelete a dashboard

Undelete a dashboard

Dashboard page operations

Update a dashboard page

Important

Tip

Update a page

Update a page adding new widgets

Updates widgets in a page

Important

Other operations

Cross-account dashboards

Dashboard with cross-account query

Limits

Dashboard limits

Dashboard page limits

Widget limits

Errors as first class citizens

Errors as part of every mutation response

Overview