• /
  • Log in
  • Free account

NerdGraph entities API tutorial

To query data with New Relic's NerdGraph, we use the concept of an entity. An entity provides unified access to all the things you monitor with New Relic, including but not limited to:

To view entity details in the our UI, use the New Relic Explorer in New Relic One.


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

Entity definition

Each entity has similar traits:

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


All you need is 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.

For more help

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

Create issueEdit page
Copyright © 2021 New Relic Inc.