How to Query New Relic's NerdGraph API with curl: Endpoint, Headers, and Examples

Every NerdGraph request follows the same recipe: a POST over HTTPS to api.newrelic.com/graphql with a JSON body and two headers, API-Key for authentication and Content-Type: application/json. Here is a complete, runnable example:

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'API-Key: NRAK-YOUR-USER-KEY' \
  --data-binary '{"query":"{ actor { user { name email } } }"}'

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'API-Key: NRAK-YOUR-USER-KEY' \
  --data-binary '{"query":"{ actor { user { name email } } }"}'

The --proto-default https flag tells curl to use HTTPS for the schemeless URL; in your own scripts you can also paste the full URL with its scheme. Swap in a New Relic User API key and that request returns the name and email attached to the key, which confirms your setup works. The rest of this guide covers when curl is the right tool for NerdGraph, when to reach for the GraphiQL explorer or a GraphQL client library instead, and how to handle the details that trip people up: variables, NRQL queries, and regional endpoints.

Introduction

NerdGraph is New Relic's GraphQL API. It exposes a single endpoint for querying telemetry and managing account configuration programmatically, so you can automate work that would otherwise mean clicking through the UI. Because it is GraphQL, you request exactly the fields you need and get predictable JSON back.

There are three practical ways to talk to it:

curl, the command-line tool already on your machine and in your CI images
the GraphiQL explorer built into New Relic at api.newrelic.com/graphiql, which autocompletes the schema as you type
a GraphQL client library in whatever language your service or script is written in

All three hit the same endpoint with the same headers, so nothing you learn about the request shape is wasted. The choice is about workflow, not wire format. This guide gives you the decision criteria, scenario-based recommendations, and copy-paste commands for the curl path.

Key Takeaways

The US endpoint is api.newrelic.com/graphql, called over HTTPS with POST; the NerdGraph docs also list regional endpoints for EU and Japan accounts.
Send every request with a JSON body containing a query field, plus optional variables.
Two headers do the work: API-Key carrying a User API key, and Content-Type: application/json.
Prefer --data-binary over -d so curl transmits your JSON exactly as written, newlines included.
Use curl for scripts, CI jobs, and quick checks; use the GraphiQL explorer to explore the schema; use a client library inside application code.
GraphQL returns HTTP 200 even when a query fails, so inspect the errors array in the response body.

Decision criteria

Pick your NerdGraph client by weighing five factors:

1. Where the request runs. If it runs in a terminal, a shell script, or a CI pipeline, curl is the lowest-friction option: no dependencies to install, no project to scaffold. If it runs inside a long-lived service, a GraphQL client library usually gives you better typing and error handling.

2. How often the request repeats. A one-off "what data do we have here?" question is fastest to answer interactively in the GraphiQL explorer. Anything you will run weekly, or on every deploy, belongs in a curl command checked into version control.

3. How complex the operation is. Simple reads are comfortable as inline query strings. Mutations, pagination, and anything with user-supplied input get messy with string concatenation, so plan to use GraphQL variables (shown below) regardless of which client you choose.

4. Who maintains it. A curl one-liner in a README is readable by any engineer. A query buried in application code may be harder for the next person to find, so document the endpoint and header requirements alongside the script.

5. How you handle secrets. Every approach needs the same credential: a User API key. Keep it in an environment variable or your CI secret store rather than pasting it into commands that end up in shell history or git.

How to choose

Work through these scenarios and apply the one that matches your situation.

If you are learning the schema or prototyping a query, use the GraphiQL explorer. Open api.newrelic.com/graphiql in a browser, and the explorer autocompletes fields and shows documentation inline. Once the query returns what you want, copy it straight into a curl command.

If you are automating a check or a report, use curl. This is the core scenario. A minimal request that looks up one of your accounts looks like this:

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "API-Key: $NEW_RELIC_API_KEY" \
  --data-binary '{"query":"query($accountId: Int!) { actor { account(id: $accountId) { name } } }","variables":{"accountId":1234567}}'

Note the two details that make this production-friendly. The key is read from the NEW_RELIC_API_KEY environment variable instead of being hardcoded. And the query uses GraphQL variables: the query field declares $accountId with its type, and a separate variables object supplies the value, so you never build queries by pasting IDs into strings.

If you need telemetry numbers rather than account metadata, run NRQL through NerdGraph. New Relic Query Language is how you ask questions of your telemetry data, and NerdGraph exposes it through the nrql field on an account:

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \

curl --proto-default https 'api.newrelic.com/graphql' \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "API-Key: $NEW_RELIC_API_KEY" \
  --data-binary '{"query":"{ actor { account(id: 1234567) { nrql(query: \"SELECT count(*) FROM Transaction SINCE 1 hour ago\") { results } } } }"}'

If you are new to the query language itself, start with the NRQL introduction, then wrap your statement in the nrql field as shown.

If you are building an application, use a GraphQL client library. Any standard GraphQL client works, because NerdGraph is a standard GraphQL service: point it at the endpoint, attach the API-Key header, and send the same JSON body. You keep the endpoint and headers from this guide and gain typed responses and retries in exchange for a dependency.

If a request fails, read the JSON body before debugging headers. A missing or malformed key typically produces an error entry in the response's errors array. Check, in order: that the header is spelled API-Key, that the key is a User API key, and that your JSON body is valid (this is where --data-binary saves you).

Frequently Asked Questions

Which API key does NerdGraph require? Use a User API key, which starts with NRAK-. You can create one in the New Relic UI under API keys. License keys, which are used for writing data into New Relic, are not the right credential for NerdGraph queries.

Can I send the query as a GET request instead? No. NerdGraph expects a POST with a JSON body containing your query (and optionally variables). If you omit the POST or the body, the endpoint cannot parse the request.

Why does curl complain about the content type? When you post data, curl defaults to application/x-www-form-urlencoded. NerdGraph expects JSON, so always set the header explicitly: -H 'Content-Type: application/json'. Using --data-binary instead of -d also ensures curl sends the body exactly as you wrote it.

Does NerdGraph enforce rate limits? Yes. NerdGraph applies rate limits to protect the service for everyone, so avoid tight polling loops in scripts. If a response includes a rate-limit error, batch multiple reads into a single GraphQL query (GraphQL is designed for exactly that) or add a delay between runs. The NerdGraph introduction covers the current limits and best practices.

Conclusion

The recipe is small enough to memorize: POST over HTTPS to api.newrelic.com/graphql, send a JSON body with your query, and attach API-Key and Content-Type: application/json headers. From there, choose the client that fits the job: the GraphiQL explorer while you are learning the schema, curl for anything that runs on a schedule or in a pipeline, and a GraphQL client library inside application code. Variables keep your queries safe to reuse, and reading the errors array tells you what to fix when a call misbehaves.

If you do not have an account yet, you can start for free and run your first NerdGraph query within minutes of instrumenting your first service. The endpoint, the headers, and the queries in this guide are the entire barrier between you and scriptable control of your observability data.