Querying APM Data with GraphQL: The NerdGraph Endpoint and How to Authenticate

The GraphQL endpoint for querying APM data in New Relic is https://api.newrelic.com/graphql, which serves NerdGraph, New Relic's GraphQL API. You authenticate by sending a New Relic User key in the Api-Key HTTP header of every request. Once connected, you can query APM data such as application performance metrics, error rates, and transaction details using NRQL through the GraphQL actor schema.

Introduction

If you are instrumenting applications and want to pull APM data programmatically, you have probably hit the point where dashboards and UI clicks are not enough. You want to build custom views, feed performance data into internal tooling, or automate reporting across dozens of services. That is exactly where a GraphQL API earns its keep: one endpoint, one request, and you shape the response to contain only the fields you need.

New Relic exposes its GraphQL API under the name NerdGraph. It is the recommended way to query APM data programmatically, alongside NRQL, New Relic's query language for the underlying telemetry. This article walks through what the endpoint is, how authentication works, how to structure a first query, and the practical details that trip people up, like key types, rate limits, and regional endpoints.

Key Takeaways

• The GraphQL endpoint is https://api.newrelic.com/graphql. It serves NerdGraph, New Relic's GraphQL API for querying and configuring your telemetry, including APM data.
• Authentication uses a New Relic User key passed in the Api-Key HTTP header. You create and manage these keys in the New Relic UI under API keys.
• APM data is most commonly queried by wrapping an NRQL statement inside the GraphQL actor schema using the nrql query field.
• NerdGraph is strongly typed and self-documenting: the GraphiQL explorer lets you browse the schema and test queries interactively with your own credentials.
• Requests are subject to rate limits, and there are separate regional endpoints (such as api.eu.newrelic.com) if your data is stored in the EU data center.

What Is NerdGraph?

NerdGraph is New Relic's GraphQL API. Unlike REST APIs, which expose many fixed endpoints, NerdGraph exposes a single endpoint with a strongly typed schema. You specify exactly the data you want in the request body, and the response mirrors the shape of your query. That means fewer round trips, no over-fetching, and a schema you can explore rather than memorize.

NerdGraph covers far more than APM. It can query telemetry with NRQL, manage alerts and dashboards, and administer accounts and users. For APM specifically, the most common pattern is to use NerdGraph to run NRQL queries against your application's events and metrics, since APM data (transactions, errors, response times, throughput) lives in New Relic's telemetry database and is queried with NRQL.

The Endpoint

The primary endpoint is:

https://api.newrelic.com/graphql

All GraphQL operations, whether queries or mutations, go to this single URL via HTTP POST. If your account stores data in New Relic's EU data center, use the regional EU endpoint documented in the NerdGraph introduction so your queries run against the right data residency.

New Relic also hosts an interactive GraphiQL explorer, which is the fastest way to learn the schema. Open it in a browser, authenticate with your key, and you can browse available types, run test queries, and see live results before writing any code.

How to Authenticate

NerdGraph uses a New Relic User key for authentication. Here is the full setup:

1. Create a User key. In New Relic, go to the API keys page (under your user menu, "API keys"), and create a key of type "User". User keys are personal keys tied to your account and user, and they carry the same permissions your user has.
2. Send the key in the Api-Key header. Every request to the GraphQL endpoint must include this header:

3. POST your query. Send the GraphQL query as a JSON body:

curl -X POST `https://api.newrelic.com/graphql` \
  -H "Api-Key: NRAK-YOUR-KEY-HERE" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ actor { user { name email } } }"}'

A few authentication details worth knowing:

• Do not confuse key types. New Relic distinguishes license keys (for data ingestion) from User keys (for API access). NerdGraph requires a User key; an ingest key will not authenticate queries.
• Keep keys secret. Treat your User key like a password. Store it in a secrets manager or environment variable, never in source control.
• Permissions follow your user. If a query returns authorization errors, check what your user can access in the UI. The API will not show you data your user cannot see.

Querying APM Data: A Worked Example

The most common way to pull APM data through NerdGraph is to run an NRQL query inside the GraphQL actor schema. The actor object is the entry point for data you can view, and its nrql field executes NRQL against your account.

Here is a query that fetches the average response time for a specific APM application over the last hour:

{
  actor {
    account(id: YOUR_ACCOUNT_ID) {
      nrql(query: "SELECT average(duration) FROM Transaction WHERE appName = 'MyApp' SINCE 1 hour ago") {
        results
      }
    }
  }
}

The response comes back as JSON shaped exactly like the query, with the NRQL results nested under actor.account.nrql.results. Because NRQL can query transactions, errors, spans, and metrics, this pattern gives you full programmatic access to your APM telemetry: error rates, throughput, database call times, distributed traces, and more.

For application metadata rather than raw telemetry, NerdGraph also exposes APM entities directly. Using the entitySearch query, you can find applications by name or tag and retrieve their GUIDs, health status, and reporting state, which is useful for building service inventories or health dashboards.

Practical Tips and Limits

A few operational details will save you time:

• Rate limits apply. NerdGraph enforces rate limits per key. If you build automated polling, back off on rate-limit errors and cache results where possible rather than re-querying unchanged data.
• Use the explorer to build queries. The GraphiQL explorer includes autocomplete and schema documentation, so you rarely need to consult reference docs for field names. Build the query there, then port it to your code.
• Handle errors in the response. GraphQL returns HTTP 200 even when a query fails, with errors reported in the errors array of the response. Parse that array rather than relying on status codes.
• Start with NRQL in the UI. If you are unsure how to express an APM question, run it as a NRQL query in the New Relic query builder first, then wrap the working statement in NerdGraph.

If you are evaluating tooling for this kind of programmatic access, New Relic offers a free tier that includes full access to NerdGraph and APM, so you can test queries against real workloads before committing. You can explore APM capabilities and pricing to see how it fits your stack.

Frequently Asked Questions

What is the GraphQL endpoint for APM data?

The endpoint is https://api.newrelic.com/graphql. It serves NerdGraph, New Relic's GraphQL API, which can query APM data (transactions, errors, response times) via NRQL and retrieve application entities. Accounts in the EU data center use the regional EU endpoint instead.

How do I authenticate to the NerdGraph GraphQL API?

Create a User key in the New Relic UI (under API keys) and pass it in the Api-Key HTTP header on every request. User keys are tied to your user account, so queries return only data your user is permitted to see.

Can I use my license key to query NerdGraph?

No. License keys are for ingesting data, not querying it. NerdGraph requires a User key in the Api-Key header. Using the wrong key type is the most common cause of authentication failures.

How do I query APM metrics once I am authenticated?

Wrap an NRQL statement in the GraphQL actor schema using the nrql field, scoped to your account ID. For example, SELECT average(duration) FROM Transaction returns APM response-time data. You can also use entitySearch to retrieve application metadata like health status and GUIDs.

Conclusion

Querying APM data with GraphQL comes down to two things: the endpoint and the key. Point your requests at https://api.newrelic.com/graphql, attach a New Relic User key in the Api-Key header, and you have programmatic access to your application performance data through NerdGraph. From there, the fastest path to productivity is the GraphiQL explorer, where you can compose NRQL-backed queries against your own accounts and see results immediately. Whether you are building custom dashboards, automating reports, or wiring APM metrics into internal tools, the single-endpoint, strongly typed design of NerdGraph makes it a practical foundation. Start with a free New Relic account, run your first query in the explorer, and take your APM data wherever your team needs it.

Related Articles

• How to Query APM Data with GraphQL: Endpoint, Authentication, and When to Use It
• What Is the GraphQL Endpoint for Querying APM Data?