Use New Relic GraphQL API to query entities

To query your data with the New Relic GraphQL API, New Relic uses 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 our product UI, use the entity explorer in New Relic One.

Entity definition

Each entity has similar traits:

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

For a more detailed description, see What is an entity?

Requirements

Owner, Admins, or Add-on managers.

You must have a user-specific API key to run GraphQL queries. To create an API key, use the or GraphQL API explorer or New Relic UI.

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.

To use the New Relic GraphQL API to query one or more entities:

Search by attribute

  1. Run a basic query with the New Relic GraphQL API explorer to find entities that match your search criteria. For example:

    query($query: String!) {
      actor {
        entitySearch(query: $query) {
          count
          results {
            entities {
              name
              entityType
              guid
            }
          }
        }
      }
    
  2. Add the following variables to the Query variables section:
    {"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) {
          entityType
          name
        }
      }
    }
  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). Queries in GraphQL 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.

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

Get alert information on alertable entities in search results

You can fetch the alert severity of any entity that can be monitored by alerts. This query will tell you if New Relic is currently receiving data from your application (via the reporting field) and, if the entity is an alertable type, the alert severity of the entity. If entities that are not alertable are returned in your search results, they will not include the AlertableEntityOutline fields.

{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      results {
        entities {
          reporting
          ... on AlertableEntityOutline {
            alertSeverity
          }
        }
      }
    }
  }
}
Get summary data on APM entities in search results

Different entity types have specific data associated with them. Below is 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.

    
{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      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 query is an example of requesting the name for all entities regardless of which entity type they are as well as requesting error rate for APM, Browser, and Mobile entities. If entities of other types are returned in your search results, they will not include an error rate field.

    
{
  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 query shows fetching the tags for every entity returned in the search results. You can read more about tags in the GraphQL tagging tutorial.

{
  actor {
    entitySearch(query: "name like 'nerdgraph'") {
      results {
        entities {
          name
          tags {
            key
            values
          }
        }
      }
    }
  }
}
Get the nextCursor for paginated search results

The GraphQL API paginates results from an entity search. If your search criteria yields more than the API limit 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.

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

Use the value of nextCursor in your next search:

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

For more help

Recommendations for learning more: