Insights Dashboard API

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

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
Admin user API key

Required: To properly assign ownership to dashboards, the Dashboard API requires your Admin user API 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 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:

  1. Log in to your New Relic account.
  2. Go to rpm.newrelic.com/api/explore.
  3. From the API Explorer's Select an account and key dropdown, select your Admin user API key.
  4. Select Dashboards, then select the API function.
  5. 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, and create a Data App using the dashboards you created via the REST API.


[video link] For a step-by-step guide to using the New Relic API Explorer to manage Insights dashboards, watch this video (approximately 8 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[owner_email] 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.

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

Example dashboard schema
{
  "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",
    "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
        }
      },
      {
        "visualization": "application_breakdown|scope_breakdown|browser_breakdown|background_breakdown|solr_breakdown|gc_runs_breakdown",
        "account_id": 12345,
        "data": [
          {
            "duration": 1800000,
            "end_time": null,
            "entity_ids": [
              238575
            ]
          }
        ],
        "presentation": {
          "title": "Breakdown Metric Chart",
          "notes": null
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 2,
          "column": 3
        }
      },
      {
        "visualization": "inventory",
        "account_id": 12345,
        "data": [
          {
            "sources": [
              "applications/apm"
            ],
            "filters": {}
          }
        ],
        "presentation": {
          "title": "Inventory",
          "notes": null
        },
        "layout": {
          "width": 2,
          "height": 1,
          "row": 3,
          "column": 1
        }
      },
      {
        "visualization": "traffic_light",
        "account_id": 12345,
        "data": [
          {
            "nrql": "SELECT * from InfrastructureEvent"
          }
        ],
        "presentation": {
          "title": "Traffic Light",
          "notes": null,
          "traffic_lights": [
            {
              "id": "12345",
              "title": "Cat",
              "subtitle": "Cat Status",
              "states": [
                {
                  "type": "wrong",
                  "min": 0,
                  "max": 3
                },
                {
                  "type": "warning",
                  "min": 3,
                  "max": 7
                },
                {
                  "type": "ok",
                  "min": 7,
                  "max": 10
                }
              ]
            }
          ]
        },
        "layout": {
          "width": 1,
          "height": 1,
          "row": 3,
          "column": 3
        }
      }
    ]
  }
}

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.

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.

Widget data definitions

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

Recommendations for learning more: