Making a New Relic NerdGraph API Request with curl: Endpoint and Headers Explained

To query New Relic's NerdGraph API with curl, send a POST request to https://api.newrelic.com/graphql with two required headers: Api-Key set to a New Relic user key and Content-Type: application/json, with your GraphQL query passed as a JSON body in the query field.

Introduction

NerdGraph is New Relic's GraphQL API, and it is the recommended way to query and configure your New Relic account programmatically. Unlike REST endpoints that expose fixed resources, NerdGraph lets you ask for exactly the data you need in a single request, which makes it well suited for dashboards, automation scripts, and reporting jobs.

Because NerdGraph is GraphQL over HTTPS, you do not need a special client to get started. A single curl command is enough to run your first query, provided you know three things: the endpoint URL, the required headers, and how to format the request body. This article walks through each of those pieces, shows a complete working example, and covers the mistakes that most commonly cause a failed request.

Key Takeaways

NerdGraph is New Relic's GraphQL API, documented in the NerdGraph introduction.
The endpoint is https://api.newrelic.com/graphql, and requests must use the HTTP POST method.
Two headers are required: Api-Key: NRAK-... (a user key, not a license key) and Content-Type: application/json.
The GraphQL query travels in the JSON body as a string under the query field.
You can explore the schema interactively in the NerdGraph GraphiQL explorer.

What NerdGraph Is and Why It Uses GraphQL

NerdGraph is a GraphQL API, which means it uses a single endpoint and a typed schema instead of many resource-specific URLs. You write a query describing the fields you want, and the response comes back as JSON containing exactly those fields. If you have used NRQL, New Relic's query language for event data, note that NerdGraph is a different layer: NerdGraph is the API surface for the whole platform, and you can even run NRQL queries through it using the actor.account.nrql field. You can read more about NRQL in the NRQL introduction.

The practical benefit for curl users is consistency. Whether you are fetching account details, listing dashboards, or running a NRQL query, the endpoint, headers, and request shape stay the same. Only the query string changes.

The Endpoint and Required Headers

Every NerdGraph request goes to the same URL:

`https://api.newrelic.com/graphql`

The request must be an HTTP POST. Two headers are required:

Api-Key: a New Relic user key, which starts with the prefix NRAK-. You can create one in the New Relic UI under API keys. This is not the same as a license key, which is used for data ingestion and will not authorize NerdGraph queries.
Content-Type: application/json: because the GraphQL query is sent as a JSON document.

Authentication is header-based, so there is no token in the URL or body. Keep your user key secret and store it in an environment variable rather than pasting it directly into scripts.

A Complete curl Example

Here is a minimal, working request that asks for your account name and ID:

#!/bin/bash

API_KEY="NRAK-YOURKEYHERE"

curl -X POST `https://api.newrelic.com/graphql` \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ actor { account(id: 1234567) { name id } } }"}'

#!/bin/bash

API_KEY="NRAK-YOURKEYHERE"

curl -X POST `https://api.newrelic.com/graphql` \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ actor { account(id: 1234567) { name id } } }"}'

A few details in this example matter:

The -X POST flag sets the method. NerdGraph rejects GET requests.
The -d flag supplies the JSON body. The GraphQL query is a string inside that JSON, so any double quotes inside the query must be escaped or, more simply, the query itself must use single-quoted GraphQL strings where possible.
Replace 1234567 with your actual New Relic account ID, visible in the account dropdown or via the actor.accounts field.

A successful response looks like this:

{
  "data": {
    "actor": {
      "account": {
        "name": "My Production Account",
        "id": 1234567
      }
    }
  }
}

{
  "data": {
    "actor": {
      "account": {
        "name": "My Production Account",
        "id": 1234567
      }
    }
  }
}

Running a NRQL Query Through NerdGraph

One of the most common curl use cases is running a NRQL query from a script. The NRQL statement is passed as a GraphQL argument, wrapped in escaped quotes:

curl -s -X POST `https://api.newrelic.com/graphql` \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ actor { account(id: 1234567) { nrql(query: \"SELECT count(*) FROM Transaction SINCE 1 hour ago\") { results } } } }"
  }'

curl -s -X POST `https://api.newrelic.com/graphql` \
  -H "Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "{ actor { account(id: 1234567) { nrql(query: \"SELECT count(*) FROM Transaction SINCE 1 hour ago\") { results } } } }"
  }'

This pattern is the backbone of most NerdGraph automation: the outer structure never changes, and you swap the NRQL string to change what data you get back.

Common Errors and How to Fix Them

403 Forbidden or "license key" errors: you passed a license key instead of a user key. NerdGraph requires a user key with the NRAK- prefix.
Empty data with an errors array: the request was authorized, but the GraphQL query itself was invalid. Read the errors messages carefully; they usually name the exact field or argument that failed.
Malformed JSON body: GraphQL double quotes inside the query string must be escaped with backslashes when the body is JSON. If curl returns a parse error, check your quoting first.
Wrong account ID: NerdGraph returns null fields rather than errors when an ID does not exist or you lack access. Verify the ID and your key's permissions.

For building queries interactively, use the GraphiQL explorer, which includes schema browsing and autocomplete, then copy the finished query into your curl command. The full schema and capabilities are described in the NerdGraph documentation.

Frequently Asked Questions

What is the NerdGraph endpoint URL?

The endpoint is https://api.newrelic.com/graphql. All NerdGraph requests, regardless of what they query or configure, go to this single URL using HTTP POST.

Which API key do I need for NerdGraph?

You need a user key, which starts with NRAK-. License keys used for sending data will not work. Create and manage user keys from the API keys page in the New Relic UI.

Can I use GET instead of POST?

No. NerdGraph accepts POST requests with a JSON body containing the query field. GET requests are not supported.

How do I test a NerdGraph query before writing curl?

Use the GraphiQL explorer. It authenticates with your user key, provides schema autocomplete, and shows the exact response shape, so you can paste a proven query into your script.

Conclusion

Making a NerdGraph request with curl comes down to three ingredients: POST to https://api.newrelic.com/graphql, include a user key in the Api-Key header, and send your GraphQL query as a JSON string. Once that skeleton works, you can reuse it for everything from simple account lookups to scheduled NRQL reporting. If you are new to the platform, create a free New Relic account and explore what the API can do for your observability workflows.