---
title: NerdGraph API explorer tutorial
source: https://docs.newrelic.com/docs/apis/nerdgraph/get-started/nerdgraph-explorer
---

NerdGraph is our GraphQL API you can use to query data and make configuration changes in New Relic features. You can send GraphQL to the NerdGraph API in a variety of ways: from your code, with curl or CLI requests, and in the NerdGraph API explorer. The explorer is a GUI GraphQL tool (based on GraphiQL) where you can experiment with queries and mutations (changes) in NerdGraph.

If you're new to GraphQL, get acquainted with the GraphQL API via the NerdGraph API explorer. If you need an overview of the API before starting this tutorial, check out [Meet NerdGraph: our GraphQL API](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph).

## Set up the NerdGraph API explorer [#set-up]

1.  Open the NerdGraph API explorer. The URL depends on the data center region that hosts your account:
    -   US (default region): [one.newrelic.com/nerdgraph-graphiql](https://one.newrelic.com/nerdgraph-graphiql)
    -   EU: [one.eu.newrelic.com/nerdgraph-graphiql](https://one.eu.newrelic.com/nerdgraph-graphiql)
    -   JP: [one.jp.newrelic.com/nerdgraph-graphiql](https://one.jp.newrelic.com/nerdgraph-graphiql)
2.  In the **User key** field, enter an [API user key](https://docs.newrelic.com/docs/apis/intro-apis/new-relic-api-keys/#user-key) and click **Submit**. You will need to copy a key from the [API Key UI](https://one.newrelic.com/api-keys).

    ![Screenshot of how to set API key in Nerdgraph](https://docs.newrelic.com/images/apis_screenshot-crop_Screenshot-API-key-in-NerdGraph.webp "Screenshot of how to set API key in Nerdgraph")

## Build a query to retrieve your name [#build-query]

Let's start with a simple NerdGraph query to search for your name in the GraphQL API.

If you don't see the default query below, erase everything in the query editor, and select these fields in the query explorer in this order: `actor`, `user`, `name`:

````graphql
{
  actor {
    user {
      name
    }
  }
}
```

With this query, you're asking NerdGraph to retrieve the `name` field, which is nested within the `user` field. The `user` field refers to the owner of the [user key](/docs/apis/get-started/intro-apis/types-new-relic-api-keys#user-api-key), and `user` is nested within `actor` (the top-level entry into all data that is scoped to the API user's access level).

````

## Execute the query [#click-play]

Click the red **Execute query** button. Note that the results have almost the same shape as the request. All the fields in the query builder make up the GraphQL schema, which describes all the available data types and their attributes. To learn more about each field, click the magnifying glass icon next to the field.

![Screenshot showing a basic query](https://docs.newrelic.com/images/apis-and-data_screenshot-crop_NerdGraph-internal-docs.webp "Screenshot showing a basic query")

## Add more fields to your query [#add-fields]

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 to put the attributes in the query. In the example, add the following fields:

-   Account `id` (You can find the value for this by clicking on your name in the lower-left corner and then clicking **API Keys**)
-   `email`

    When you run the query, it 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.

    ```graphql
    {
      actor {
        user {
          name
          email
        }
        account(id: INSERT_YOUR_OWN_ACCOUNT_ID )
      }
    }
    ```

## Experiment with mutations [#mutations]

In GraphQL, [mutations](https://graphql.org/learn/queries/#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?

1.  Erase what's in the editor.
2.  Scroll down the query builder and expand `mutation`.
3.  Scroll down to `tagging` and select `taggingAddTagsToEntity`.
4.  Select the following fields:

    -   `guid!:` (You can find this by opening **All entities**, clicking the **...** icon in your entity record, and the clicking **See metadata & tags**)
    -   `tags!:`
        -   `key!:`
        -   `values:`
    -   `errors`
        -   `message`
        -   `type`

    ![Mutation example](https://docs.newrelic.com/images/apis-and-data_screenshot-full_NerdGraph-mutation-example.webp "Mutation example")

    When you add a custom tag to an entity, you must select the `errors` field. Otherwise, the editor displays an error.

    > #### 💡 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.

## Try your NerdGraph query in the terminal [#query-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:

1.  Select the **Tools** menu.
2.  Copy the query as a curl call or as a [New Relic CLI](https://docs.newrelic.com/docs/new-relic-solutions/build-nr-ui/newrelic-cli) command.

    ![NerdGraph tools menu](https://docs.newrelic.com/images/apis-and-data_screenshot-crop_NerdGraph-tools-menu.webp "NerdGraph tools menu")

    ```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 [#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](https://graphql-code-generator.com/) 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](https://support.newrelic.com/s/hubtopic/Topic__c/Default?c__tags=%5B%7B%22id%22%3A%22a9P8W0000004KSqUAM%22%2C%22isCustomImage%22%3Afalse%2C%22sObjectType%22%3A%22Tag__c%22%2C%22subtitle%22%3A%22%22%2C%22title%22%3A%22nerdgraph%22%2C%22titleFormatted%22%3A%22%3Cstrong%3Enerdgra%3C%2Fstrong%3Eph%22%2C%22subtitleFormatted%22%3A%22%22%2C%22icon%22%3A%22standard%3Adefault%22%7D%5D).

## Other example requests [#more-examples]

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

**Query accounts 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:

````graphql
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.

```json
{
  "data": {
    "actor": {
      "account": {
        "name": "Data Nerd"
      }
    }
  }
}
```

````

**Query user, account, and NRQL in one 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.

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

````