Introduction to New Relic NerdGraph

NerdGraph is New Relic's GraphQL-format API. Our NerdGraph is an efficient and flexible query language that lets you request exactly the data you need, without over-fetching or under-fetching. While typical REST APIs require loading from multiple URLs, NerdGraph calls get all the data you need in a single request. NerdGraph also makes it easier to evolve APIs over time and enables powerful developer tools.

If your New Relic account hosts data in the EU data center, ensure you're using EU region API endpoints. To access accounts in the EU data center, use https://api.eu.newrelic.com/graphiql.

Requirements and endpoints

To use NerdGraph, you need a New Relic user key.

NerdGraph endpoints:

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 NerdGraph GraphiQL explorer

We have a GraphiQL explorer that lets you explore our schema, find definitions, and form calls. To use the explorer:

  1. You'll need a New Relic user key.
  2. Go to api.newrelic.com/graphiql (if you have New Relic data in EU, use api.eu.newrelic.com/graphiql)

NerdGraph tutorials and examples

You can use NerdGraph to:

Functionality Tutorials
Query all the entities associated with your account.

See the entities tutorial.

Query, create, and update workloads associated with your account.

See the workloads tutorial.

Create, manage, and add tags to entities.

For more information and examples, see the tagging tutorial.

Query distributed tracing data.

See the trace data tutorial.

Fetch data when building a New Relic One app.

See New Relic One app data querying and mutations.

Understand upstream and downstream relationships with your services.

See the relationships tutorial.

Configure your New Relic cloud integrations.

See cloud integration examples.

Query event data using NRQL.

See the NRQL tutorial.

Watch video tutorials about NerdGraph.

Go to the New Relic University tutorial Intro to New Relic NerdGraph. Or, go to the full online course New Relic APIs.

NerdGraph terminology

The New Relic GraphQL server explicitly defines the graph structure of NerdGraph. The following keywords are common to all GraphQL servers. Use these keywords to help build and understand your own queries. In addition:

Term Definition
Queries

Queries are basic requests that are intended to only fetch data, without any additional actions. Queries in the NerdGraph GraphiQL explorer are not static, meaning that you can ask for more 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

Mutations are requests that are intended to have additional actions, such as creating data or updating data on a server. 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.

Make queries with the explorer

You can make queries with the NerdGraph GraphiQL explorer. The explorer provides built-in schema definitions and features, including auto-complete and query validation.

In GraphQL, you ask for specific information in the graph structure of New Relic's data. You can follow the nodes of the graph to query exactly the data that you want.

New fields are added seamlessly, and old fields can be marked as deprecated, which removes them from documentation and allows an eventual, graceful shutdown of that field.

Query account a New Relic user can access

You can query for the name of an account that an actor (a New Relic authorized user) has access to:

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
      }
   }
}

The response will mirror the query structure you defined in the request, making it easy to ask for the specific data that you want.

{
  "data": {
      "actor": {
         "account": {
            "name": "Data Nerd"
         }
      }
   }
}
Query user, account, and NRQL in one NerdGraph GraphiQL request

The graph structure shows its capabilities when queries become more complex. For example, you can query for user information, account information, and make a NRQL query with one request. With REST API, this would take three different requests to three different endpoints.

query {
   actor {
      account(id: YOUR_ACCOUNT_ID) {
         name
         nrql(query: "SELECT * FROM Transaction") {
            results
         }
      }
      user {
         name
         id
      }
   }
}

For more help

If you need more help, check out these support and learning resources: