New Relic Dashboards: Build with NerdGraph API (2026)

NerdGraph is New Relic’s GraphQL API, and it’s the bedrock for programmatically interacting with your New Relic data, including building and managing dashboards.

Here’s a dashboard being created using NerdGraph:

mutation CreateDashboard($name: String!, $description: String) {
  dashboardCreate(dashboard: {
    name: $name,
    description: $description,
    permissions: PUBLIC,
    icon: GEARS,
    ownerType: ACCOUNT
  }) {
    entityResult {
      guid
      name
      id
    }
    errors {
      message
      type
    }
  }
}

With variables:

{
  "name": "My Programmatic Dashboard",
  "description": "This dashboard was created using NerdGraph!"
}

This mutation, when executed, creates a new dashboard within your New Relic account. The entityResult block will contain the guid, name, and id of the newly created dashboard, which you’ll use for subsequent operations like adding widgets. The errors block will tell you if anything went wrong.

The real power of NerdGraph lies in its ability to not just create, but also to define the content of your dashboards. You can add visualizations, configure their data sources (NRQL queries), and arrange them on the dashboard canvas.

Consider adding a simple line chart widget to the dashboard we just created. First, you’d need the guid of the dashboard. Let’s assume it’s aBcDeFgHiJkLmNoP.

mutation AddLineChartWidget($dashboardId: EntityGuid!, $nrql: String!, $title: String!) {
  dashboardWidgetCreate(dashboardWidget: {
    dashboardId: $dashboardId,
    visualization: {
      type: LINE,
      nrql: $nrql
    },
    title: $title
  }) {
    entityResult {
      guid
      name
    }
    errors {
      message
      type
    }
  }
}

With variables:

{
  "dashboardId": "aBcDeFgHiJkLmNoP",
  "nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago",
  "title": "Transaction Count (Last Hour)"
}

This dashboardWidgetCreate mutation takes the dashboardId (the GUID of the dashboard you want to modify), a nrql query to fetch the data, and a title for the widget. The visualization object specifies the type as LINE. This allows you to dynamically build complex dashboards with multiple widgets, each tailored to specific monitoring needs, entirely through code.

The mental model for interacting with dashboards via NerdGraph is a hierarchical one:

1. Account/User: The top level where dashboards reside.
2. Dashboard: A container for widgets, with its own metadata (name, description, permissions, etc.).
3. Widget: The individual visualization (chart, table, etc.) on a dashboard. Each widget is powered by an NRQL query and has its own configuration.

You can query for existing dashboards, update their properties, delete them, and similarly manage their widgets – create, update, delete, and reorder. This programmatic control is invaluable for GitOps workflows, automated onboarding of new services, and ensuring consistent monitoring across your infrastructure.

The dashboardUpdate mutation is particularly flexible. It allows you to change not just the name or description, but also the layout and permissions of an existing dashboard. You can also update individual widgets using dashboardWidgetUpdate, which takes the widget’s GUID.

When defining NRQL queries for widgets, remember that NerdGraph accepts the same NRQL syntax you’d use in the New Relic UI. This means you can leverage all of New Relic’s powerful data querying capabilities directly within your API-driven dashboard creation.

The dashboardWidgetUpdate mutation accepts a new nrql string, allowing you to change the data displayed by a widget without recreating it. This is crucial for adapting dashboards to evolving monitoring requirements.

The most surprising thing about NerdGraph’s dashboard API is how granularly you can control the visual layout. You don’t just add widgets; you can specify their x and y coordinates, their width, and height within the dashboard’s grid system. This means you can programmatically design the exact pixel-perfect arrangement of your dashboard elements, ensuring a consistent and professional look every time.

The next step after building dashboards is often automating the creation of alerts based on the data displayed within those dashboards.