Insights Dashboard API

Important

As of April 12, 2021, we are upgrading Insights to an improved web and mobile experience! All of your Insights URLs will be redirected automatically to the corresponding dashboards in New Relic One. For more details about this migration and how you can easily plan for this transition, see our Explorers Hub post.

The New Relic Insights Dashboard API allows you to list, create, read, update, and delete new or existing Insights dashboards or New Relic One dashboards. New Relic's API Explorer includes the cURL request format, available parameters, response status codes, and JSON response structure for available API calls.

Tip

If your account hosts data in the EU data center, ensure you are using the proper API endpoints for EU region accounts.

Example use cases

The Dashboard API is a flexible solution for many different use cases. Here are a few examples of how you can leverage the Dashboard API to solve problems:

Automatically create dashboards for new teams or services pre-populated with standard organization metrics and charts.
Use the API to view dashboard schemas, and save them in a central repository for source control and backups.
Create widget and dashboard templates to allow teams to self-service.

For detailed examples and use cases, see this New Relic blog post.

Account and data security

The Dashboard API includes safeguards to help ensure account and data security.

Requirements	Comments
User key and permissions	Required: This API requires a user key. You cannot use your account-level REST API key to manage dashboards.
Cross-account widgets	You can view cross-account widgets on a dashboard by using the Insights or New Relic One dashboards UI. However, the ability to view cross-account widgets when using the Dashboard API has these restrictions: To view the list of widgets on a specific dashboard with the Dashboard API, you must use the `SHOW` endpoint. To view a widget in the API payload, the widget's account ID must be the same as the account ID for the payload. If the account ID is not the same, the widget's details will not be listed. Instead, the widget's payload will show: `"visualization": "inaccessible"`

Requirements

Comments

User key and permissions

Required: This API requires a user key. You cannot use your account-level REST API key to manage dashboards.

Cross-account widgets

You can view cross-account widgets on a dashboard by using the Insights or New Relic One dashboards UI. However, the ability to view cross-account widgets when using the Dashboard API has these restrictions:

To view the list of widgets on a specific dashboard with the Dashboard API, you must use the SHOW endpoint.
To view a widget in the API payload, the widget's account ID must be the same as the account ID for the payload.
If the account ID is not the same, the widget's details will not be listed. Instead, the widget's payload will show:
```
"visualization": "inaccessible"
```

Use the API Explorer

To view the Dashboard API options in the API Explorer:

Log in to your New Relic account.
Go to rpm.newrelic.com/api/explore.
From the API Explorer's Select an account and key dropdown, select a user key.
Select Dashboards, then select the API function.
To use API functions with existing dashboards, include the dashboard id. To find the dashboard id, select the LIST endpoint, and apply filtering options.

View Dashboard API video

Follow along with this step-by-step tutorial to learn how to find your API keys, create new dashboards, view and update existing dashboards via the REST API.

For a step-by-step guide to using the New Relic API Explorer to manage Insights dashboards, watch this video (approximately 6 minutes). Or, go directly to the full online course about New Relic APIs.

Use API endpoints

The API supports the following functions for Insights dashboards only. The API does not support these functions for data apps (collections of linked dashboards).

API endpoints	Comments
`CREATE` `POST /v2/dashboards`	Create a new dashboard. The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to POST more than 300 widgets will produce an error. To add more widgets to the dashboard, use the Insights UI.
`UPDATE` `PUT /v2/dashboards/:id:`	Update an existing dashboard for the dashboard `id`. The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to PUT more than 300 widgets will produce an error. To add more or edit existing widgets on the dashboard, use the Insights UI.
`SHOW` `GET /v2/dashboards/:id:`	View an existing dashboard and all accessible widgets for the dashboard `id`. To help ensure data security, the `SHOW` function returns only the dashboard widgets that the user has permission to view. If a dashboard includes widgets that the user is not authorized to view, the API will provide a placeholder with the `visualization` field set to `inaccessible`.
`LIST` `GET /v2/dashboards?page=:page:&per_page=:count:`	View a paginated list of dashboards. The list shows filterable dashboard metadata only; no widgets will appear in the list. Search options include: `filter[title]` as substring search `filter[category] (all / favorites / mine}` `filter[created_after] as ISO date` `filter[created_before] as ISO date` `filter[updated_after] as ISO date` `filter[updated_before] as ISO date` Sort options include: `name` `recently_viewed` `last_edited` If no sort option is provided, results will be ordered by `id`. Pagination options include the `page` and `per_page` fields. The `per_page` field controls the number of results per page with a default and maximum of 100 results. The response will include a pagination Link header, which provides next page and last page links.
`DELETE` `DELETE /v2/dashboards/:id:`	Delete an existing dashboard indicated by the dashboard `id`.

API endpoints

Comments

CREATE

POST /v2/dashboards

Create a new dashboard.

The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to POST more than 300 widgets will produce an error.

To add more widgets to the dashboard, use the Insights UI.

UPDATE

PUT /v2/dashboards/:id:

Update an existing dashboard for the dashboard id.

The API permits a maximum of 300 widgets when creating or updating a dashboard. Attempting to PUT more than 300 widgets will produce an error.

To add more or edit existing widgets on the dashboard, use the Insights UI.

SHOW

GET /v2/dashboards/:id:

View an existing dashboard and all accessible widgets for the dashboard id.

To help ensure data security, the SHOW function returns only the dashboard widgets that the user has permission to view. If a dashboard includes widgets that the user is not authorized to view, the API will provide a placeholder with the visualization field set to inaccessible.

LIST

GET /v2/dashboards?page=:page:&per_page=:count:

View a paginated list of dashboards. The list shows filterable dashboard metadata only; no widgets will appear in the list.

Search options include:

filter[title] as substring search
filter[category] (all / favorites / mine}
filter[created_after] as ISO date
filter[created_before] as ISO date
filter[updated_after] as ISO date
filter[updated_before] as ISO date
Sort options include:
name
recently_viewed
last_edited
If no sort option is provided, results will be ordered by id.
Pagination options include the page and per_page fields. The per_page field controls the number of results per page with a default and maximum of 100 results. The response will include a pagination Link header, which provides next page and last page links.

DELETE

DELETE /v2/dashboards/:id:

Delete an existing dashboard indicated by the dashboard id.

Dashboard API schema

JSON is the only supported format. When using API functions, be sure to add .json to the end of the request URL, as shown in the API Explorer.

Important

Widgets have a size limit of 3x3 (height and width may not exceed 3).

Caution

The Dashboard API 3-column restriction also applies to the dashboards you upload to New Relic One dashboards. If you update a dashboard with a different layout using the API, the uploaded dashboard will revert to the 3-column configuration.

{
  "dashboard": {
    "metadata": { "version": 1 },
    "title": "API Widget Sample",
    "icon":"none|archive|bar-chart|line-chart|bullseye|user|usd|money|thumbs-up|thumbs-down|cloud|bell|bullhorn|comments-o|envelope|globe|shopping-cart|sitemap|clock-o|crosshairs|rocket|users|mobile|tablet|adjust|dashboard|flag|flask|road|bolt|cog|leaf|magic|puzzle-piece|bug|fire|legal|trophy|pie-chart|sliders|paper-plane|life-ring|heart",
    "grid_column_count": 3|12,
    "visibility": "owner|all",
    "editable": "read_only|editable_by_owner|editable_by_all",
    "filter": {
      "event_types": [
        "Transaction"
      ],
      "attributes": [
        "appName"
      ]
    },
    "widgets": [
      {
        "visualization": "billboard|gauge|billboard_comparison",
        "account_id": 12345,
        "data": [
          {
            "nrql": "SELECT count(*) from Transaction since 5 minutes ago"
          }
        ],
        "presentation": {
          "title": "Threshold Event Chart",
          "notes": null,
          "threshold": {
            "red": 18000000,
            "yellow": 8000000
          }
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 1,
          "column": 1
        }
      },
      {
        "visualization": "facet_bar_chart|faceted_line_chart|facet_pie_chart|facet_table|faceted_area_chart|heatmap",
        "account_id": 12345,
        "data": [
          {
            "nrql": "SELECT count(*) from Transaction since 5 minutes ago facet appName"
          }
        ],
        "presentation": {
          "title": "Facet Chart",
          "notes": null,
          "drilldown_dashboard_id": 64
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 1,
          "column": 2
        }
      },
      {
        "visualization": "attribute_sheet|single_event|histogram|funnel|raw_json|event_feed|event_table|uniques_list|line_chart|comparison_line_chart",
        "account_id": 12345,
        "data": [
          {
            "nrql": "SELECT latest(appName), latest(duration) from Transaction since 5 minutes ago"
          }
        ],
        "presentation": {
          "title": "Simple Event Chart",
          "notes": null
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 1,
          "column": 3
        }
      },
      {
        "visualization": "markdown",
        "account_id": 12345,
        "data": [
          {
            "source": "# Dashboard Note\n\n[link goes here](https://www.newrelic.com)"
          }
        ],
        "presentation": {
          "title": "",
          "notes": null
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 2,
          "column": 1
        }
      },
      {
        "visualization": "metric_line_chart",
        "account_id": 12345,
        "data": [
          {
            "duration": 1800000,
            "end_time": null,
            "entity_ids": [
              238575
            ],
            "metrics": [
              {
                "name": "Apdex",
                "units": null,
                "scope": "",
                "values": [
                  "score"
                ]
              }
            ],
            "order_by": "score",
            "limit": 10
          }
        ],
        "presentation": {
          "title": "Metric Line Chart",
          "notes": null
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 2,
          "column": 2
        }
      },
    ]
  }
}

Dashboard data definitions

For examples of these data elements being used in a JSON call, see the Dashboard API schema.

Dashboard data element	Description
`metadata` Object	Specifies the version of the dashboard schema. The version must be 1.
`icon` String	Name of an icon from the Insights icon library.
`grid_column_count` Integer	Specifies the number of columns in the grid layout.
`title` String	User-supplied title of the dashboard.
`filter` Object	Specifies configuration of the smart filter on the dashboard.
`visibility` String	Specifies who can view the dashboard in the Insights UI and the API.
`editable` String	Specifies who can edit the dashboard in the Insights UI and the API.
`widgets` Array	Array of widget data element objects.

For examples of these data elements being used in a JSON call, see the Dashboard API schema.

Widget data element	Description
`visualization` String	What sort of visualization to place in the widget; for example, billboard, line_chart, area chart, etc.
`data` Array	Array of objects with chart-specific information needed to query necessary data. Currently only one data object is supported.
`account_id` Long	Source account to fetch data from, if not the current account.
`presentation` Object	Object with chart title and notes, plus chart-specific customization.
`layout` Object	Object with column, row, width, and height to determine chart layout in the dashboard.

Supported visualizations

The Dashboard API supports:

event_table
line_chart
facet_table
facet_bar_chart
facet_pie_chart
billboard
faceted_area_chart
faceted_line_chart
event_table
comparison_line_chart
heatmap
histogram
billboard_comparison
attribute_sheet
funnel
gauge
json
list

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 data security and licenses documentation.

Important

Tip

Example use cases

Account and data security

Use the API Explorer

View Dashboard API video

Use API endpoints

Dashboard API schema

Important

Caution

Example dashboard schema

Dashboard data definitions

Widget data definitions

Supported visualizations

For more help

Insights Dashboard API

Important

Tip

Example use cases

Account and data security

Use the API Explorer

View Dashboard API video

Use API endpoints

Dashboard API schema

Important

Caution

Dashboard data definitions

Widget data definitions

Supported visualizations

.css-1bvd50p{width:1rem;height:1rem;fill:none;stroke:currentColor;stroke-width:2;stroke-linecap:round;stroke-linejoin:round;}For more help

For more help