Introduction to New Relic NerdGraph, our GraphQL API

NerdGraph is our GraphQL-format API that lets you query New Relic data and configure some New Relic features. After you sign up for a free New Relic account and install any of our monitoring services, you can get started with NerdGraph.

What is NerdGraph?

New Relic has several APIs. NerdGraph is the API we recommend for querying New Relic data and for performing some specific configurations (learn more about features). NerdGraph provides a single API interface for returning data from New Relic's various APIs and microservices. Over time, other configuration capabilities will be added to NerdGraph.

Important

NerdGraph isn't used for data ingest. For that, you'd use our data ingest APIs.

NerdGraph is built using GraphQL, which is an open source API format that allows you to request exactly the data needed, with no over-fetching or under-fetching.

Here's a short video with an introduction to using NerdGraph with the NerdGraph explorer.

Want to watch more video tutorials? Go to the New Relic University's Intro to NerdGraph. Or see the online course on New Relic APIs.

Requirements and endpoints

Notes on NerdGraph requirements:

NerdGraph requires a New Relic user key: this can be generated and accessed from the GraphiQL explorer.
User type and assigned roles can affect your NerdGraph permissions. For more details, see Factors affecting access.

The NerdGraph endpoints are:

Main endpoint: https://api.newrelic.com/graphql
Endpoint for accounts using EU data center: https://api.eu.newrelic.com/graphql

To access the endpoint, use the following cURL command:

curl -X POST https://api.newrelic.com/graphql \
-H 'Content-Type: application/json' \
-H 'API-Key: YOUR_NEW_RELIC_USER_KEY' \
-d '{ "query":  "{ requestContext { userId apiKey } }" } '

Use the GraphiQL explorer

To get started using GraphQL, we recommend playing around with the NerdGraph explorer. For how to find and use the explorer, see our NerdGraph explorer tutorial.

NerdGraph functionality

NerdGraph functionality can be broken down into two main categories:

Querying data. You can fetch data for a variety of purposes, including using it in a programmatic workflow, or building a New Relic app for custom data visualizations.
Configuring features. There are a variety of configurations available and more will be added over time. You can do things like add tags, configure workloads, or customize "golden metrics."

You can use NerdGraph to return and configure a wide range of data. One way to see what NerdGraph can do is to start building queries and exploring the schema using the NerdGraph explorer.

These are some of the most commonly used NerdGraph features:

Get data about your monitored entities
Query your data using NRQL (our query language)
Create dashboards

Here are all our available NerdGraph docs:

Topic	Tutorials
Account management	Manage accounts Manage user groups and access grants Create and manage API keys (data ingest keys, and user keys)
Alerts	For New Relic alerts: see all alert-related tutorials For applied intelligence: Configuring topology for incident correlation
APM agents	APM agent configuration
Charts and dashboards	Query your data using NRQL (our query language) Create dashboards Export dashboards to other accounts Export dashboards as files Manage externally shared dashboards
Cloud integrations (AWS, Azure, GCP)	Configure cloud integrations
Data management	Convert event data to metric data Data retention Drop data
Distributed tracing	Query distributed tracing data Configure Infinite Tracing
Entities	Get data about monitored entities Understand entity relationships and dependencies (used to build service maps) Query and configure "golden metrics" (important entity metrics)
Log management	Manage data partitions Manage log parsing rules Manage obfuscation expressions and rules
New Relic apps	Build a New Relic app
Partners and resellers	Manage subscriptions (only for partners using original pricing model)
Service levels	Configure and manage service levels
Synthetic monitoring	Manage your monitors
Tags	Add and manage tags
Workloads	View and configure workloads

NerdGraph terminology

The following are terms that originate with GraphQL, the API format NerdGraph uses.

Term	Definition
Queries and mutations	There are two classes of GraphQL operations: Queries are basic requests used only to fetch data. These queries are not static, meaning that you can ask for more data or less data, depending on your needs. For each query, you can specify exactly what data you want to retrieve, as long as it is supported by the schema. Mutations are requests that perform an action, such as creating a resource or changing configuration. Mutations require the keyword `mutation`, as well as the `name` of the mutation.
Type	Data in GraphQL is organized into types. Types can be scalars (like strings, numbers, or booleans) or object types. An object type is a custom type made up of a collection of fields. For example, an object type called `User` may represent a user in a system.
Field	A field represents a piece of information on an object type that can be queried. Fields can be scalars, lists, or objects. For example, a `User` object type could have a string field called `name`.
Interface	An interface is an abstract type that represents a collection of common fields that other object types can `implement`.