Use the NerdGraph explorer

NerdGraph is our main API for querying data and making configurations to New Relic features. One popular way to use NerdGraph and make API requests is with our NerdGraph explorer.

Find the explorer

To find the NerdGraph explorer:

In the EU: If your New Relic account uses an EU data center, go to api.eu.newrelic.com/graphiql.
Outside the EU: If your account is outside the EU, use api.newrelic.com/graphiql.

What is the NerdGraph explorer?

Our NerdGraph API is built using GraphQL, a third-party query language. Our NerdGraph explorer is built using GraphiQL, which is an open source graphical interface for forming and making GraphQL requests.

You can use the NerdGraph explorer to explore our data schema, to read built-in object definitions, and to build and execute queries.

To watch a short video showing how to use the explorer, see Introduction to NerdGraph.

Before you begin

Before you do the lessons here, be sure you've reviewed Introduction to NerdGraph.

Go to the explorer and log in using your New Relic user ID and password.

Make sure you have a valid New Relic user key. You can create one from the NerdGraph explorer or view and create them in the API keys UI.

Next we'll walk you through some steps that will help you learn to use the explorer.

Step 1. Build a query to retrieve your name

Let's start with a simple NerdGraph query. Search for your name in the New Relic database:

Erase everything in the query editor.
Select the following fields in the query explorer in this order: actor, user, name.

This GraphQL snippet appears in the editor.

{
  actor {
    user {
      name
    }
  }
}

Step 2. Click the play button to see the result

With this query, you're telling NerdGraph to retrieve your name. You're asking for the name field, which is nested within the user field. This refers to the user who owns the API key, which in turn is nested within actor.

Click the Play button to see the result: It has almost the same shape as the request. All the fields in the query builder make up what's called the GraphQL schema, which describes all the available data types and their attributes. To learn more about each field, click the Docs button, or hover over a field in the editor.

Step 3. Add more fields to your query

Now you can try adding more fields to your query. The simplest way is clicking the fields in the query builder: The explorer knows where the attributes should go in the query. In the example, you add the account id and email fields.

Running the query returns only the data you need, without over-fetching or under-fetching data. Notice that the id field has an argument: passing arguments is a powerful way of customizing your NerdGraph queries. Every field and object can contain arguments, so instead of running multiple queries, you just compose the one that you need.

{
  actor {
    user {
      name
      email
    }
    account(id: 12345678)
  }
}

Step 4. Experiment with mutations

In GraphQL, mutations are a way to execute queries with side effects that can alter the data by creating, updating, or deleting objects (in REST APIs, these are commonly referred to as CRUD operations).

Ready for your first mutation?

Erase what's in the editor.
Scroll down the query builder and expand mutation.
Select the fields in the following screenshot:

In this case, you're trying to add a custom tag to an entity. Notice that the editor complains if you don't select errors: mutations must have a way of telling you how the operation performed in the backend (failed requests result in null responses).

Tip

Unlike REST, GraphQL APIs like NerdGraph can return partial responses. For example, if you try adding tags to multiple entities, some mutations can fail and others succeed; all is logged in the GraphQL response you get.

Step 5. Try your NerdGraph query in the terminal

Let's say that you've built a NerdGraph query you're happy with and you want to test it elsewhere. To capture code-ready queries and mutations:

Select the Tools menu.
Copy the query as a curl call or as a New Relic CLI command.

bash

$# curl version
$curl https://api.newrelic.com/graphql \
>  -H 'Content-Type: application/json' \
>  -H 'API-Key: API_KEY_REDACTED' \
>  --data-binary '{"query":"{\n  actor {\n    user {\n      name\n      email\n    }\n    account(id: 12345678)\n  }\n}\n", "variables":""}'
$
$# New Relic CLI version
$newrelic nerdgraph query '{
$  actor {
$    user {
$      name
$      email
$    }
$    account(id: 12345678)
$  }
$}
$'

Next steps

Now you know the basics of composing and testing NerdGraph queries, but how do you turn them into client or server code? Solutions such as the GraphQL Code Generator can help you turn the NerdGraph queries into code for your implementation.

Try creating more complex queries by clicking fields and expanding objects in the query builder (be careful with mutations though, as they could result in changes to your account). Check out some of the example requests in the section below.

For more information on NerdGraph and explore other projects from the developer community, check out Explorer's Hub posts.

Other example requests

Here are some other examples of NerdGraph requests that may be helpful:

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

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