---
title: Add your custom visualization to a dashboard
source: https://docs.newrelic.com/docs/new-relic-solutions/build-nr-ui/custom-visualizations/add-to-dashboard-nerdgraph
---

Add your custom visualization to a new or existing dashboard, programmatically, with New Relic's GraphQL API, [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/).

## Before you begin

If you haven't already:

-   Sign up for a [New Relic account](https://newrelic.com/signup?utm_source=developer-site)
-   Install [Node.js](https://nodejs.org/en/download/)
-   Complete the first four steps in the [`nr1` quick start](https://one.newrelic.com/launcher/developer-center.launcher?pane=eyJuZXJkbGV0SWQiOiJkZXZlbG9wZXItY2VudGVyLmRldmVsb3Blci1jZW50ZXIifQ==) to install and configure the CLI

## Create and publish your Nerdpack

Create a Nerdpack with a visualization. You'll add this visualization to a dashboard using NerdGraph.

> #### 💡 FURTHER READING
>
> Because this guide is about using visualizations, not creating and publishing them, it breezes over these topics. If you're unfamiliar with visualizations or would like a thorough explanation of dealing with visualization Nerdpacks, check out the following resources:
>
> -   [Introduction to custom visualizations](https://docs.newrelic.com/docs/new-relic-solutions/build-nr-ui/custom-visualizations/configuration-options)
> -   [Build your first custom visualization](https://docs.newrelic.com/docs/new-relic-solutions/build-nr-ui/custom-visualizations/build-visualization)

If you already have a visualization you'd like to add to a dashboard, you can skip this section. But don't forget to make the necessary code adjustments to reference your visualization instead of the one this guide uses, called `my-awesome-visualization`.

1.  Update your `nr1` CLI:
    ````sh
    nr1 update
    ```

    Now, you've the latest version.

    ````
2.  Create a visualization called `my-awesome-visualization` in a Nerdpack called `my-awesome-nerdpack`:
    ````bash
    nr1 create -t visualization -n my-awesome-visualization
    [output] {success}✔ {plain}You're trying to create a visualization outside of a Nerdpack.  We'll create a Nerdpack for you—what do you want to name it? … my-awesome-nerdpack
    [output]
    [output] {success}✔ {plain}nerdpack created successfully!
    [output] {purple}nerdpack {blue}my-awesome-nerdpack {plain}is available at "./my-awesome-nerdpack"
    [output]
    [output] {success}✔ {plain}visualization created successfully!
    [output] {purple}visualization {blue}my-awesome-visualization {plain}is available at "./my-awesome-nerdpack/visualizations/my-awesome-visualization"
    ```

    When you build a visualization with `nr1 create`, you get a default visualization. You'll use this default visualization throughout this course.

    ````
3.  Navigate to your new Nerdpack:
    ````sh
    cd my-awesome-nerdpack
    ```

    From here, you can run `nr1 nerdpack` commands.

    ````
4.  Publish and subscribe to your Nerdpack:
    ````sh
    nr1 nerdpack:publish
    nr1 nerdpack:subscribe
    ```

    Now, that your account is subscribed to your visualization, you can describe your app configurations with JSON and add it to a dashboard with NerdGraph.

    ````

## Describe your visualization options with JSON

Whether you're adding your visualization to a new dashboard or an existing one, you need to send your configuration to NerdGraph.

Your custom visualization JSON object represents a dashboard widget and consists of the following fields:

| Field              | Type   | Description                         |
| ------------------ | ------ | ----------------------------------- |
| `title`            | String | Title for your dashboard widget     |
| `visualization`    | JSON   | The metadata for your visualization |
| `visualization.id` | String | Your visualization's ID             |
| `rawConfiguration` | JSON   | A full configuration of your widget |

> #### 💡 TIP
>
> You can also add other types of widgets to dashboards with the steps in this guide, but the fields described here are specific to custom visualization widgets. For other widget types, you need to supply different data.
>
> Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql).

1.  Start with a JSON template based on the fields you need to describe your custom visualization:
    ````json
    {
    	title: "",
    	visualization: {
    	  id: ""
    	},
    	rawConfiguration: {}
    }
    ```

    ````
2.  Give your visualization widget a title:
    ````json lineHighlight=2
    {
    	title: "My Awesome Visualization",
    	visualization: {
    	  id: ""
    	},
    	rawConfiguration: {}
    }
    ```

    ````
3.  Look up your Nerdpack ID from `my-awesome-nerdpack/nr1.json`:
    ````json fileName=my-awesome-nerdpack/nr1.json lineHighlight=3
    {
        "schemaType": "NERDPACK",
        "id": "ab123c45-678d-9012-efg3-45hi6jkl7890",
        "displayName": "MyAwesomeNerdpack",
        "description": "Nerdpack my-awesome-nerdpack"
    }
    ```

    Then, look up your visualization ID from `my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json`:

    ```json fileName=my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json lineHighlight=3
    {
        "schemaType": "VISUALIZATION",
        "id": "my-awesome-visualization",
        "displayName": "MyAwesomeVisualization",
        "description": "",
        "configuration": [
            {
                "name": "nrqlQueries",
                "title": "NRQL Queries",
                "type": "collection",
                "items": [
                    {
                        "name": "accountId",
                        "title": "Account ID",
                        "description": "Account ID to be associated with the query",
                        "type": "account-id"
                    },
                    {
                        "name": "query",
                        "title": "Query",
                        "description": "NRQL query for visualization",
                        "type": "nrql"
                    }
                ]
            },
            {
                "name": "fill",
                "title": "Fill color",
                "description": "A fill color to override the default fill color",
                "type": "string"
            },
            {
                "name": "stroke",
                "title": "Stroke color",
                "description": "A stroke color to override the default stroke color",
                "type": "string"
            }
        ]
    }
    ```

    Set your visualization widget's `visualization.id` to the form `{NERDPACK-ID}.{VISUALIZATION-ID}`:

    ```json lineHighlight=4
    {
    	title: "My Awesome Visualization",
    	visualization: {
    	  id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
    	},
    	rawConfiguration: {}
    }
    ```

    ````
4.  In `my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json`, review your configuration options:
    ````json fileName=my-awesome-nerdpack/visualizations/my-awesome-visualization/nr1.json lineHighlight=6-38
    {
        "schemaType": "VISUALIZATION",
        "id": "my-awesome-visualization",
        "displayName": "MyAwesomeVisualization",
        "description": "",
        "configuration": [
            {
                "name": "nrqlQueries",
                "title": "NRQL Queries",
                "type": "collection",
                "items": [
                    {
                        "name": "accountId",
                        "title": "Account ID",
                        "description": "Account ID to be associated with the query",
                        "type": "account-id"
                    },
                    {
                        "name": "query",
                        "title": "Query",
                        "description": "NRQL query for visualization",
                        "type": "nrql"
                    }
                ]
            },
            {
                "name": "fill",
                "title": "Fill color",
                "description": "A fill color to override the default fill color",
                "type": "string"
            },
            {
                "name": "stroke",
                "title": "Stroke color",
                "description": "A stroke color to override the default stroke color",
                "type": "string"
            }
        ]
    }
    ```

    The `name` fields in `configuration` are important for describing your visualization widget.

    ````
5.  Using the `name` field for every configuration object in your visualization's `nr1.json` file, build a `rawConfiguration` for your widget:
    ````json lineHighlight=6-15
    {
    	title: "My Awesome Visualization",
    	visualization: {
    	  id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
    	},
    	rawConfiguration: {
    		nrqlQueries: [
    			{
    				accountId: 1234567,
    				query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
    			}
    		],
    		fill: "pink",
    		stroke: "green"
    	}
    }
    ```

    Here, you've created a `rawConfiguration` by supplying values for each configuration option in `nr1.json`. Note that `nrqlQueries` is an array because its type is `collection`. The other values are strings. Learn more about these configuration options in [Configure your custom visualization](/docs/new-relic-solutions/build-nr-ui/custom-visualizations/configuration-options).

    Now that you've described your visualization widget in JSON, you can add your configured visualization to a dashboard. In the next section, you'll learn how to create a new dashboard with your visualization. If you already have one ready, skip ahead to [add your visualization to your existing dashboard](#add-your-visualization-to-an-existing-dashboard).

    ````

## Create a new dashboard with your visualization

If you want to create a new dashboard for your visualization widget, use NerdGraph's `dashboardCreate()` mutation.

The NerdGraph `dashboardCreate()` mutation takes the following fields:

| Field                       | Type                                                     | Description                                                        |
| --------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
| `accountId`                 | Integer                                                  | The ID for the account for which you want to create your dashboard |
| `dashboard`                 | JSON                                                     | The details of the dashboard you're creating                       |
| `dashboard.name`            | String                                                   | The name of your dashboard                                         |
| `dashboard.permissions`     | Enum: `PRIVATE`, `PUBLIC_READ_ONLY`, `PUBLIC_READ_WRITE` | The access control of your dashboard                               |
| `dashboard.pages`           | Array: JSON                                              | The details of your dashboard's pages                              |
| `dashboard.pages[].name`    | String                                                   | The name of the dashboard page                                     |
| `dashboard.pages[].widgets` | Array: JSON                                              | The widgets to add to the dashboard page                           |

> #### 💡 TIP
>
> You can also pass more fields to `dashboardCreate()` to add details, widgets, and more. Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql).

In this guide, you create a dashboard with a single page that contains a single widget. The visualization widget you described in the [last section](#describe-your-visualization-options-with-json).

1.  Build out a GraphQL mutation template based on the fields you need to describe your dashboard in `dashboardCreate()`:
    ````graphql
    mutation {
    	dashboardCreate(
    		accountId: 0,
    		dashboard: {
    			name: "",
    			pages: [
    				{
    					name: "",
    					widgets: []
    				},
    			],
    			permissions: PRIVATE
    		}
    	)
    }
    ```

    Here, you've defined the template for a private dashboard. Now, it's time to fill in the details.

    ````
2.  [Look up your account ID](https://docs.newrelic.com/docs/accounts/accounts-billing/account-structure/account-id/) and enter it for your `accountId`:
    ````graphql lineHighlight=3
    mutation {
    	dashboardCreate(
    		accountId: 1234567,
    		dashboard: {
    			name: "",
    			pages: [
    				{
    					name: "",
    					widgets: []
    				},
    			],
    			permissions: PRIVATE
    		}
    	)
    }
    ```

    ````
3.  Select a name for your dashboard and its page:
    ````graphql lineHighlight=5,8
    mutation {
    	dashboardCreate(
    		accountId: 1234567,
    		dashboard: {
    			name: "My Awesome Dashboard",
    			pages: [
    				{
    					name: "One Page to Rule Them All",
    					widgets: []
    				},
    			],
    			permissions: PRIVATE
    		}
    	)
    }
    ```

    ````
4.  In `widgets`, place the widget object you created in the last section:
    ````graphql lineHighlight=9-26
    mutation {
      dashboardCreate(
        accountId: 1234567
        dashboard: {
          name: "My Awesome Dashboard"
          pages: [
            {
              name: "One Page to Rule Them All"
              widgets: [
                {
                  title: "My Awesome Visualization"
                  visualization: {
                    id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
                  }
                  rawConfiguration: {
                    nrqlQueries: [
                      {
                        accountId: 1234567
                        query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
                      }
                    ]
                    fill: "pink"
                    stroke: "green"
                  }
                }
              ]
            }
          ]
          permissions: PRIVATE
        }
      )
    }
    ```

    ````
5.  Finally, add the return fields to your mutation:
    ````graphql lineHighlight=31-35
    mutation {
      dashboardCreate(
        accountId: 1234567
        dashboard: {
          name: "My Awesome Dashboard"
          pages: [
            {
              name: "One Page to Rule Them All"
              widgets: [
                {
                  title: "My Awesome Visualization"
                  visualization: {
                    id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
                  }
                  rawConfiguration: {
                    nrqlQueries: [
                      {
                        accountId: 1234567
                        query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
                      }
                    ]
                    fill: "pink"
                    stroke: "green"
                  }
                }
              ]
            }
          ]
          permissions: PRIVATE
        }
      ) {
        entityResult {
          guid
        }
      }
    }
    ```

    <Callout variant="important">
      Make sure you replace the IDs in your mutation query with ones that match your account, Nerdpack, and visualization.
    </Callout>

    Now, you've a mutation ready to send to NerdGraph to create single-page dashboard with a widget for your custom visualization. As a result, you'll see the new dashboard's entity GUID.

    In the next section, you'll learn how to add your visualization to an existing dashboard. If that's not relevant to your goals, skip ahead to [send your request to NerdGraph](#send-your-request-to-nerdgraph).

    ````

## Add your visualization to an existing dashboard

To add your visualization widget to an existing dashboard, use NerdGraph's `dashboardAddWidgetsToPage()` mutation.

The NerdGraph `dashboardAddWidgetsToPage()` mutation takes the following fields:

| Field     | Type        | Description                                                           |
| --------- | ----------- | --------------------------------------------------------------------- |
| `guid`    | String      | The entity GUID for the dashboard to which you're adding your widgets |
| `widgets` | Array: JSON | The widgets to add to the dashboard page                              |

> #### 💡 TIP
>
> You can also pass more fields to `dashboardAddWidgetsToPage()` to add details, widgets, and more. Explore the API on your own with our [NerdGraph explorer](https://api.newrelic.com/graphiql).

1.  Build out a GraphQL mutation template based on the fields you need to describe your dashboard in `dashboardAddWidgetsToPage()`:
    ````graphql
    mutation {
      dashboardAddWidgetsToPage(
        guid: "", 
        widgets: []
      ) {
        errors {
          description
        }
      }
    }
    ```

    ````
2.  [Look up your dashboard's GUID](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#find) and enter it for `guid`:
    ````graphql lineHighlight=3
    mutation {
      dashboardAddWidgetsToPage(
        guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI"
        widgets: []
      ) {
        errors {
          description
        }
      }
    }
    ```

    ````
3.  In widgets, place the widget object you created in [Describe your visualization options with JSON](#describe-your-visualization-options-with-json):
    ````graphql
    mutation {
      dashboardAddWidgetsToPage(
        guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI"
        widgets: [
          {
            visualization: {
              id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
            }
            rawConfiguration: {
              nrqlQueries: [
                {
                  accountId: 1234567
                  query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
                }
              ]
              fill: "pink"
              stroke: "green"
            }
          }
        ]
      )
    }
    ```

    ````
4.  Finally, add the return fields to your mutation:
    ````graphql
    mutation {
      dashboardAddWidgetsToPage(
        guid: "AbCdEFghIJkLMNo1PQRSTUVWXYZAbCD2Ef34GHI"
        widgets: [
          {
            visualization: {
              id: "ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization"
            }
            rawConfiguration: {
              nrqlQueries: [
                {
                  accountId: 1234567
                  query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
                }
              ]
              fill: "pink"
              stroke: "green"
            }
          }
        ]
      ) {
        errors {
          description
        }
      }
    }
    ```

    Now, you've a mutation ready to send to NerdGraph to add your custom visualization to an existing dashboard. As a result, you'll see descriptions of any thrown errors to help you debug issues.

    The last thing you need to do is actually send your request to NerdGraph.

    ````

## Send your request to NerdGraph

Send an HTTP request to NerdGraph with the payload you built in previous sections for the mutation that best suits your needs. There are many tools you can use to send an HTTP request, but in this guide, you learn how to communicate with NerdGraph using three specific tools:

-   [NerdGraph API explorer](https://api.newrelic.com/graphiql)
-   [cURL](https://curl.se/)
-   [New Relic CLI](https://docs.newrelic.com/docs/new-relic-solutions/tutorials/new-relic-cli/)

If you use another, you can adapt these methods for your favorite development tool.

### NerdGraph API explorer

The [NerdGraph API explorer](https://api.newrelic.com/graphiql) is an implementation of [GraphiQL](https://github.com/graphql/graphiql) that lets you explore the NerdGraph APIs.

1.  Go to the [NerdGraph API explorer](https://api.newrelic.com/graphiql).
2.  Select or create a new API key:
    ![Select API key](https://docs.newrelic.com/images/nerdgraph_screenshot-crop_api-key.webp "Select API key")
3.  In the center console, paste your mutation query:
    ![Paste your mutation](https://docs.newrelic.com/images/nerdgraph_screenshot-crop_create-dashboard-with-viz.webp "Paste your mutation")
    > #### ⚠️ IMPORTANT
    >
    > Make sure you replace the IDs in your mutation query with ones that match your account, Nerdpack, and visualization.
4.  Press **Execute Query** and see the results in the right pane:
    ![Execute your query](https://docs.newrelic.com/images/nerdgraph_screenshot-crop_successful-dashboard-creation.webp "Execute your query")
    If you successfully created a new dashboard, your response has an entity GUID. If you don't have an entity GUID, the response contains error messages to help you debug your query.
    If you added your visualization to an existing dashboard, you won't see errors in the response. If you do see error messages, use them to debug your query.
    > #### 💡 EXPLORE
    >
    > The NerdGraph API explorer lets you see other fields and change your query without typing everything manually. Use the left pane to explore NerdGraph.

### cURL

cURL is a command line utility for making HTTP requests.

1.  Select or create a New Relic [user key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key). Copy this key, because you use it in the next step.
2.  Make a request to NerdGraph, using `cURL`:
    ````sh
    curl https://api.newrelic.com/graphql \
      -H 'Content-Type: application/json' \
      -H 'API-Key: <YOUR-USER-KEY>' \
      --data-binary '{"query": "mutation {dashboardCreate(dashboard: {name: \"My Awesome Dashboard\", pages: [{name: \"One Page to Rule Them All\", widgets: [{title: \"My Awesome Visualization\", visualization: {id: \"ab123c45-678d-9012-efg3-45hi6jkl7890.my-awesome-visualization\"}, rawConfiguration: {nrqlQueries: [{accountId: 3014918, query: \"FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago\"}], fill: \"pink\", stroke: \"green\"}}]}], permissions: PRIVATE}, accountId: <YOUR-ACCOUNT-ID>) { entityResult { guid }}}", "variables": ""}'
    ```

    <Callout variant="important">
      Make sure you replace the IDs in your mutation query with ones that match your account, Nerdpack, and visualization.
    </Callout>

    Here, you send a request to NerdGraph that has two headers, `Content-Type` and `API-Key`, and a binary message body containing one of the mutation queries you built in previous sections.

    If you prefer to use a UI-based client, like [Postman](https://www.postman.com/), you can adapt this method to a format that your client supports.

    ````

### New Relic CLI

The [`newrelic`](https://github.com/newrelic/newrelic-cli/blob/main/docs/cli/newrelic.md) is a command line interface for reading and writing New Relic data.

1.  If you haven't already, install `newrelic` by following the steps of our [Get started with the New Relic CLI](https://docs.newrelic.com/docs/new-relic-solutions/tutorials/new-relic-cli/) guide.
    Once you've done that, you will have `newrelic` installed and configured for making NerdGraph requests.
2.  Make a NerdGraph request using `newrelic nerdgraph query`:
    ````sh
    newrelic nerdgraph query 'mutation {
        dashboardCreate(
            accountId: 1234567,
            dashboard: {
                name: "My Awesome Dashboard",
                pages: [
                    {
                        name: "One Page to Rule Them All",
                        widgets: [
                            {
                                title: "My Awesome Visualization",
                                visualization: {
                                    id: "de0b4768-1504-4818-a898-da7cd14f0bfb.my-awesome-visualization"
                                },
                                rawConfiguration: {
                                    nrqlQueries: [
                                        {
                                            accountId: <YOUR-ACCOUNT-ID>,
                                            query: "FROM NrUsage SELECT sum(usage) FACET metric SINCE 1 week ago"
                                        }
                                    ],
                                    fill: "pink",
                                    stroke: "green"
                                }
                            }
                        ]
                    },
                ],
                permissions: PRIVATE
            }
        )   {
            entityResult {
                guid
            }
        }
    }'
    ```

    <Callout variant="important">
      Make sure you replace the IDs in your mutation query with ones that match your account, Nerdpack, and visualization.
    </Callout>

    ````

## View your new dashboard

Now that you've built a dashboard with NerdGraph, it's time to check your work!

1.  Go to **[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Dashboards** and select your dashboard.

2.  The dashboard you created has the `name` you passed in your mutation, "My Awesome Dashboard". It also has the configuration you sent in `rawConfiguration`, from the NRQL data query to the fill and stroke colors.

## Summary

Congratulations! In this guide, you used NerdGraph, New Relic's GraphQL API, to add your custom visualization to a dashboard.