• /
  • Log in

NerdGraph tutorial: View entity data

With NerdGraph, you can query details about your monitored entities.


To work with an entity's golden metrics and tags, see the golden metrics API tutorial.

Entity definition

Entities are an important New Relic concept. Basically, an entity is anything we monitor, including but not limited to:

Learn more about how we define "entity."

To view entity details in the UI, you can use the Explorer.

When working with entities in NerdGraph, it can help to understand some important traits they have:

  • A unique entity GUID identifies an entity.
  • An entity exists over a span of time, even if it's a short period.
  • An entity provides a useful entry point for exploring data about specific metrics and events, or for contextualizing data related to other entities.


You need a user key.

Search for entities

New Relic searches for entities by their attributes, primarily their name, but also by type of entity and other values. The search returns basic data about entities matching the search criteria. Then, from the basic query results, you can query a specific entity by its GUID.

You can craft a query in one of two ways:

  • Use the queryBuilder argument to help you craft a query.


  • Use the freeform query argument to provide your own search.

To use NerdGraph to query one or more entities, you can search by attribute or GUID.

In addition to these examples, we highly recommend exploring the API using the NerdGraph GraphiQL explorer and searching its inline documentation.

Search by attribute

  1. Go to the NerdGraph GraphiQL explorer.

  2. Run a basic query to find entities that match your search criteria. For example:

    query($query: String!) {
      actor {
        entitySearch(query: $query) {
          results {
            entities {
  3. Add the following variables to the Query variables section in NerdGraph:

    {"query": "name LIKE 'nerd-graph' AND type IN ('APPLICATION')"}

Search by entity GUID

  1. Use a specific entity's GUID to query deeper into its related data. For example:

    query($guids: EntityGuid!) {
      actor {
        entities(guids: $guids) {
  2. Add the following variables to the Query variables section:

    {"guids": "entity-guid-here"}

Example queries

Queries are requests that are intended to only fetch data (no side effects). NerdGraph queries 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.

Entities in NerdGraph rely on GraphQL interfaces, a concept that allows objects to share common fields. Interfaces are used to provide data for specific entity types, as you will see in many of these NerdGraph query examples.

Delete entities

You can manually delete any entity in your account by using the NerdGraph API. To do so, run this query with the entity's GUID in the NerdGraph GraphiQL explorer:

mutation {
entityDelete(guids: ["EntityGuid"]) {

Note that a deleted entity may appear again in your UI if a New Relic agent reindexes it again.

For more help

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

Create issueEdit page
Copyright © 2021 New Relic Inc.