---
title: NerdGraph tutorial: View entity data
source: https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-entities-api-tutorial
---

[Entities](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/what-entity-new-relic) at New Relic refer to anything we monitor that generates or contains telemetry. Entities help you find the data you want to track in New Relic, and if you understand their relationships with other entities, you can get even more insights into your data. Here are a few examples of entities:

-   Applications monitored by [APM](https://docs.newrelic.com/docs/apm/new-relic-apm/getting-started/introduction-new-relic-apm).
-   Cloud integrations, services, and hosts monitored by our [infrastructure monitoring](https://docs.newrelic.com/docs/infrastructure/new-relic-infrastructure/get-started/introduction-new-relic-infrastructure).

You can work with entities right in our UI (see [Learn about New Relic entities](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic)), or you can follow the steps here about working with entities through our NerdGraph API. If you need help getting started with NerdGraph, see our [Introduction to New Relic NerdGraph](https://docs.newrelic.com/docs/introduction-new-relic-graphql).

> #### ⚠️ IMPORTANT
>
> To work with an entity's golden metrics and tags, see the [golden metrics API tutorial](https://docs.newrelic.com/docs/apis/nerdgraph/examples/golden-metrics-entities-nerdgraph-api-tutorial).

## Before you get started [#before-you-get-started]

Before working with entities, we recommend reading [Learn about entities](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic).

When working with entities, some important things to keep in mind:

-   A unique GUID identifies an entity (`entity.guid` or `entityGuid`).
-   An entity exists in New Relic for a [specific time period](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic#expiration).
-   An entity provides a useful entry point for exploring data about specific metrics and events or for contextualizing data related to other entities.

## Search for entities [#search-entity]

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.

Besides `domainType`, other common entity attributes are:

-   `id`
-   `accountId`
-   `name`
-   `domainId`
-   `alertSeverity`
-   `reporting`

You can filter by any of the above attributes. Additionally, you can use [tags](https://docs.newrelic.com/docs/apis/nerdgraph/examples/nerdgraph-tagging-api-tutorial/#add-tags) for filtering.

> #### ⚠️ CAUTION
>
> You cannot filter by custom, root-level entity properties. Custom properties are only retrieved as part of the entity's metadata in the actual search response. To filter by a custom field, transform it into an entity tag.

You can craft a query in one of two ways:

1.  Use the [`queryBuilder`](#search-querybuilder) argument to help you craft a query.
2.  Use the freeform [`query`](#search-query) argument to build your own search.

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

> #### 💡 TIP
>
> NerdGraph sets the total number of entities that can be returned in one query to 200. If you need to retrieve all entities for a query, use cursor pagination as explained in the examples.

In addition to [the examples below](#graphql-examples), we recommend that you experiment with the API using the [NerdGraph explorer](https://api.newrelic.com/graphiql). It has inline documentation that will help you construct your queries and mutations.

### Search with `queryBuilder` [#search-querybuilder]

The `queryBuilder` argument is useful to construct simple queries. It allows you to add filters to your query from a predefined list of attributes, and their typical values. For more advanced queries, use the [`query`](#search-query) argument instead.

1.  Go to the NerdGraph [GraphiQL explorer](https://api.newrelic.com/graphiql).
2.  Run a basic query to find entities that match your search criteria. For example:

    ```graphql
    {
      actor {
        entitySearch(queryBuilder: {domain: APM, type: APPLICATION}) {
          query
          results {
            entities {
              name
              entityType
              guid
            }
          }
        }
      }
    }
    ```

### Search with freeform `query` [#search-query]

This is useful to craft more complex queries.

1.  Go to the NerdGraph [GraphiQL explorer](https://api.newrelic.com/graphiql).

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

    ```graphql
    query($query: String!) {
      actor {
        entitySearch(query: $query) {
          count
          results {
            entities {
              name
              entityType
              guid
            }
          }
        }
      }
    }
    ```

3.  Add the following [variables](https://graphql.org/learn/queries/#variables) to the **Query variables** section in NerdGraph:

    ```json
    {"query": "name LIKE 'nerd-graph' AND domainType IN ('APM-APPLICATION')"}
    ```

## Fetch entities by GUID [#fetch-by-guid]

When you know the GUID of the entity you want to fetch, you can just use the `entity` attribute:

```graphql
{
  actor {
    entity(guid: "ENTITY_GUID") {
      name
      entityType
    }
  }
}
```

This can also be written as a search query:

```graphql
{
  actor {
    entitySearch(query: "id = 'ENTITY_GUID'") {
      query
      results {
        entities {
          name
          entityType
        }
      }
    }
  }
}
```

Or, to fetch multiple entities at the same time, you can use the `entities` attribute:

```graphql
{
  actor {
    entities(guids: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
      name
      entityType
    }
  }
}
```

Otherwise, use a search query:

```graphql
{
  actor {
    entitySearch(query: "id IN ('ENTITY_GUID_1', 'ENTITY_GUID_2')") {
      query
      results {
        entities {
          name
          entityType
        }
      }
    }
  }
}
```

## Example queries [#graphql-examples]

Queries are requests that are intended to only fetch data (and don't have any other effect). 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's supported by the schema.

Entities in NerdGraph rely on [GraphQL interfaces](https://docs.newrelic.com/docs/apis/graphql-api/getting-started/introduction-new-relic-graphql-api#terminology), 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.

**Get entity data using queryBuilder**

If you aren't sure how to start crafting an entity search query, use NerdGraph to help you build one. Next, retrieve entity data and the query string that was built.

-   Request the query field in your results to see the query string built by the `queryBuilder` argument.
-   You cannot use the `query` and `queryBuilder` arguments at the same time.
-   We highly recommend exploring the API using the [NerdGraph GraphiQL explorer](https://api.newrelic.com/graphiql), and using its inline documentation to see the query options available to you.

    ```graphql
    {
      actor {
        entitySearch(queryBuilder: {domain: APM, type: APPLICATION}) {
          query
          results {
            entities {
              reporting
              ... on AlertableEntityOutline {
                alertSeverity
              }
            }
          }
        }
      }
    }
    ```

**Get data for infrastructure integration entities in search results**

There are many different types of infrastructure integration entities and they are listed separately from other entity types. Use the `infrastructureIntegrationType` input argument to explore them.

-   You cannot use the `query` and `queryBuilder` arguments at the same time.
-   Use `infrastructureIntegrationType` in place of the `type` input argument.
-   We highly recommend exploring the API using the [NerdGraph GraphiQL explorer](https://api.newrelic.com/graphiql) and using its inline documentation to see the query options available to you.

    ```graphql
    {
      actor {
        entitySearch(queryBuilder: {infrastructureIntegrationType: F5_NODE}) {
          query
          results {
            entities {
              entityType
              domain
            }
          }
        }
      }
    }
    ```

**Get alert information on alertable entities in search results**

Fetch the alert severity of any entity that can be monitored by [New Relic's alerts](https://docs.newrelic.com/docs/alerts-applied-intelligence/new-relic-alerts/get-started/introduction-alerts). This NerdGraph query will tell you if we are currently receiving data from your application (using the `reporting` field).

-   If the entity is an alertable type, results will include the alert severity of the entity.
-   If the results include entities that are not alertable, they will not include the `AlertableEntityOutline` fields.

    ```graphql
    {
      actor {
        entitySearch(query: "name like 'nerdgraph' and alertSeverity is not null") {
          results {
            entities {
              reporting
              ... on AlertableEntityOutline {
                alertSeverity
              }
            }
          }
        }
      }
    }
    ```

**Get summary data on APM entities in search results**

Different entity types have specific data associated with them. The following NerdGraph query example shows a selection of fields available for APM application entities:

-   More summary data can be requested in your query.
-   If entities of other types are returned in your search results, they will not include these fields.

    ```graphql
    {
      actor {
        entitySearch(query: "name like 'nerdgraph' and domainType = 'APM-APPLICATION'") {
          results {
            entities {
              name
              ... on ApmApplicationEntityOutline {
                apmSummary {
                  errorRate
                  apdexScore
                  webResponseTimeAverage
                  responseTimeAverage
                }
              }
            }
          }
        }
      }
    }
    ```

**Get data specific to each entity type in search results**

Different entity types have specific data associated with them. This NerdGraph query example requests the name for all entities regardless of which entity type they are, as well as the error rate for APM, browser monitoring, and mobile monitoring entities.

-   If entities of other types are returned in your search results, they will not include an error rate field.

    ```graphql
    {
      actor {
        entitySearch(query: "name like 'nerdgraph'") {
          results {
            entities {
              name
              ... on ApmApplicationEntityOutline {
                apmSummary {
                  errorRate
                }
              }
              ... on BrowserApplicationEntityOutline {
                browserSummary {
                  jsErrorRate
                }
              }
              ... on MobileApplicationEntityOutline {
                mobileSummary {
                  httpErrorRate
                }
              }
            }
          }
        }
      }
    }
    ```

**Get all tags for each entity in search results**

This NerdGraph query example fetches tags for every entity returned in the search results. For more information, see the [NerdGraph GraphiQL tagging tutorial](https://docs.newrelic.com/docs/apis/graphql-api/tutorials/graphql-tagging-api-tutorial).

````graphql
{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      results {
        entities {
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}
```

````

**Use tags to filter entity results**

This NerdGraph query example filters entities that belong to the `INFRA` domain and belong to awsRegion `us-east-1`, and returns their name in the search results.

````graphql
{
  actor {
    entitySearch(query: "domain = 'INFRA' and tags.aws.awsRegion = 'us-east-1'") {
      results {
        entities {
          name
        }
      }
    }
  }
}
```

Additionally, filtering can be done by whether a given tag is present. The following query filters entities of the domainType `BROWSER-APPLICATION` and have the tag `clusterAgentId` defined.

```graphql
{
  actor {
    entitySearch(query: "domainType = 'BROWSER-APPLICATION' and tags.clusterAgentId is not null") {
      results {
        entities {
          name
        }
      }
    }
  }
}
```

For more information, see the [NerdGraph GraphiQL tagging tutorial](/docs/apis/graphql-api/tutorials/graphql-tagging-api-tutorial).

````

**Aggregate results by an attribute or a tag**

This NerdGraph query example filters entities of domainType `APM-APPLICATION` domain that belong to awsRegion `us-east-1`, and returns their name in the search results. Then aggregates results to get the total number of entities grouped by New Relic account id.

````graphql
{
  actor {
    entitySearch(query: "domainType = 'APM-APPLICATION'") {
      facetedCounts(facets: {facetCriterion: {facet: ACCOUNT_ID}}) {
        counts {
          count
          facet
        }
      }
    }
  }
}
```

Additionally, aggregation can be done by tags too; the following query filters entities of domainType `APM-APPLICATION` domain that belong to awsRegion `us-east-1`, then aggregates results to get the total number of entities grouped by agent language.

```graphql
{
  actor {
    entitySearch(query: "domainType = 'APM-APPLICATION' and tags.aws.awsRegion = 'us-east-1'") {
      facetedCounts(facets: {facetCriterion: {tag: "language"}}) {
        counts {
          count
          facet
        }
      }
    }
  }
}
```

For more information, see the [NerdGraph GraphiQL tagging tutorial](/docs/apis/graphql-api/tutorials/graphql-tagging-api-tutorial).

````

**Get the nextCursor for paginated search results**

The NerdGraph GraphiQL explorer paginates results from an entity search.

-   If your search criteria yields more than the API limit of 200 entities in a single response, and you want to view the rest of the results, you can request `nextCursor` in your initial request, and use its value in another query to retrieve the following "page" of results.
-   If there are no more results, `nextCursor` will be null.

    ```graphql
    {
      actor {
        entitySearch(query: "name like 'nerd-graph'") {
          results {
            nextCursor
            entities {
              name
            }
          }
        }
      }
    }
    ```

    Use the value of `nextCursor` in your next search:

    ```graphql
    {
      actor {
        entitySearch(query: "name like 'nerd-graph'") {
          results(cursor: "next_cursor_value") {
            nextCursor
            entities {
              name
            }
          }
        }
      }
    }
    ```

**Get alertable entities**

The NerdGraph GraphiQL explorer allows to filter entities with alertable is true|false to show when an entity has property alertable. See [entity-defnitions](https://github.com/newrelic/entity-definitions)

-   You can filter by any of the above attributes. Additionally, you can use tags for filtering too.
-   Alertable is a entity-type configuration, that's why is not present in the results.

    ```graphql
    {
      actor {
        entitySearch(query: "alertable is TRUE") {
          results {
            entities {
              name
            }
          }
        }
      }
    }
    ```

    You can combine with other filters as well in the query:

    ```graphql
    {
      actor {
        entitySearch(query: "domain='APM' and alertable is TRUE") {
          results {
            entities {
              name
            }
          }
        }
      }
    }
    ```

**Get entities which stop reporting more than one day ago**

The NerdGraph GraphiQL explorer allows to filter entities with reporting is true|false and lastReportingChangeAt date field.

-   You can retrieve entities which stop reporting (something happend to them) in last few hours

    ```graphql
    {
      actor {
        entitySearch(query: "reporting is false and lastReportingChangeAt > 1651708800000") {
          results {
            entities {
              name
            }
          }
        }
      }
    }
    ```

## Create or delete entity relationships [#manual-relationships]

An entity may have a relationship with another entity. Some relationships are [created automatically by New Relic](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#relationship-created), but you can also use mutations to create or delete custom relationships. We have some explanations below about how to do this, but if you need help understanding the various relationship types at New Relic, take a look at [Entity relationships](https://docs.newrelic.com/docs/new-relic-solutions/new-relic-one/core-concepts/what-entity-new-relic/#related-entities).

Before you manually create additional relationships or delete them, keep the following in mind:

-   Two entities can have multiple relationships, one for each relationship type.
-   Two entities can hold a relationship IF they belong to the same trusted account.
-   For each entity, you can manually define up to 2000 relationships. When the limit is reached, the API will return a `LIMIT_EXCEEDED` error.
-   Each mutation can fail if you don't have access to one of the two entities (source/target).

### List relationships of an entity [#list-relationships]

You can use the `relatedEntities` field to see how pairs of entities interact and how they're related. This can help you troubleshoot upstream and downstream services and understand how minor issues may have larger repercussions, similar to how [service maps](https://docs.newrelic.com/docs/service-maps-dependencies-new-relic-one) can be used.

The following example shows how to query an entity by its specific GUID:

```graphql
query {
  actor {
    entity(guid: "ENTITY_GUID") {
      name
      relatedEntities {
        results {
          source {
            entity {
              guid
              name
            }
          }
          target {
            entity {
              guid
              name
            }
          }
          type
        }
      }
    }
  }
}
```

### Create or replace relationships [#create-or-replace]

Create or replace entity relationships using the mutation `entityRelationshipUserDefinedCreateOrReplace`. As its name suggests, it allows you to create a relationship between two entities with a given type. If the relationship already exists between the two entities, it will be added again with the updated given values (the creation time and the creator user id):

```graphql
mutation {
  entityRelationshipUserDefinedCreateOrReplace(
    sourceEntityGuid: "SOURCE_ENTITY_GUID",
    targetEntityGuid: "TARGET_ENTITY_GUID",
    type: BUILT_FROM
  ) {
    errors {
      message
      type
    }
  }
}
```

### Delete relationships [#delete-relationships]

Delete entity relationships using the mutation `entityRelationshipUserDefinedDelete`. The source and target are mandatory, but the type isn't. If you execute the mutation without type, all the relationships between the two entities are removed.

```graphql
mutation {
  entityRelationshipUserDefinedDelete(
    sourceEntityGuid: "SOURCE_ENTITY_GUID",
    targetEntityGuid: "TARGET_ENTITY_GUID",
    type: BUILT_FROM
  ) {
    errors {
      message
      type
    }
  }
}
```

## Delete entities [#delete-entities]

You can manually delete any entity in your account by using the NerdGraph API in the [NerdGraph GraphiQL explorer](https://api.newrelic.com/graphiql).

To delete `EXT-SERVICE` and `REF-REPOSITORY` entities, run this mutation with the entity's GUID:

```graphql
mutation {
  entityDelete(guids: ["ENTITY_GUID_1", "ENTITY_GUID_2"]) {
    deletedEntities
    failures {
      guid
      message
    }
  }
}
```

> #### ⚠️ IMPORTANT
>
> After running the `entityDelete` mutation, you may see a deleted entity in your UI if a New Relic agent reindexes it again.

To delete `APM`, `BROWSER` and `MOBILE` entities, run this mutation with the entity's GUID:

```graphql
mutation {
  agentApplicationDelete(guid: "ENTITY_GUID") {
    success
  }
}
```

> #### ⚠️ IMPORTANT
>
> -   The `agentApplicationDelete` mutation requires that the New Relic agent must not have reporting data for 12 hours before deletion.
> -   Currently, you can only remove the following [entity types](https://docs.newrelic.com/docs/new-relic-one/use-new-relic-one/core-concepts/what-entity-new-relic) using the Nerdgraph API: `APM-APPLICATION`, `EXT-SERVICE`, and `REF-REPOSITORY`.
> -   You may see a deleted entity in your UI if a New Relic agent reindexes it again.