NerdGraph: New Relic's GraphQL API

NerdGraph is New Relic's GraphQL-format API for querying New Relic data and performing platform configurations. It provides a single API interface that returns data from New Relic's various APIs and microservices. Because it is built on GraphQL, an open source API format, each request returns exactly the data specified: no over-fetching or under-fetching.

NerdGraph is not used for data ingest. Sending telemetry into New Relic uses the dedicated data ingest APIs.

What is NerdGraph?

NerdGraph is the API New Relic recommends for querying observability data and performing specific configurations. It provides a single interface for returning data from New Relic's various APIs and microservices, replacing the need to stitch together multiple REST endpoints. Over time, additional configuration capabilities are added to NerdGraph.

What are the requirements?

A New Relic account with a User API key, which must be included with all queries and mutations
User type and assigned roles affect NerdGraph permissions

What is the endpoint?

The endpoint depends on the account's data center region:

US region (default): https://api.newrelic.com/graphql
EU region: https://api.eu.newrelic.com/graphql
JP region: https://api.jp.newrelic.com/graphql

Example request (curl)

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 } }" }'

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 } }" }'

What if I get a 401 unauthorized error?

A 401 error means the API-Key header is missing or invalid. NerdGraph requires a User API key (not a License key or Browser key) sent in the API-Key header on every request. Generate or find your User API key at one.newrelic.com under API Keys.

What can NerdGraph do?

NerdGraph functionality falls into two categories:

Querying data. Fetch New Relic data for programmatic workflows or for building custom New Relic apps and visualizations.

Configuring features. Perform configurations such as adding tags, configuring workloads, and customizing golden metrics, with more capabilities added over time.

Commonly used NerdGraph operations:

Getting data about monitored entities, including entity relationships and dependencies used to build service maps
Running NRQL queries, including cross-account queries and asynchronous longer-running queries
Creating and managing dashboards, including exporting dashboards to other accounts or as files
Account and user management: managing accounts, users, user groups, roles, and API keys
Alerts configuration, including topology for alert event correlation
APM agent configuration and browser monitoring configuration
Cloud integrations for AWS, Azure, and GCP
Data management: converting event data to metric data, data retention, streaming data export, and dropping data
Distributed tracing queries and Infinite Tracing configuration
Log management: data partitions, parsing rules, and obfuscation rules
Mobile monitoring: creating mobile apps and retrieving application tokens
Synthetic monitoring, service levels, workloads, tags, Teams, Scorecards, secrets management, and RAG data indexing

What GraphQL terminology applies to NerdGraph?

Term	Definition
Queries and mutations	Queries fetch data only and are dynamic — you specify exactly what fields to return. Mutations perform actions such as creating a resource or changing configuration, and require the `mutation` keyword plus the mutation name.
Type	Data in GraphQL is organized into types, either scalars (strings, numbers, booleans) or object types made up of fields.
Field	A piece of information on an object type that can be queried. Fields can be scalars, lists, or objects.
Interface	An abstract type representing a collection of common fields that other object types can implement.