A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The New Relic API is how an app or AI agent works with a New Relic account: running NRQL queries over telemetry, searching monitored entities, creating alert policies and dashboards, and sending in metrics, events, and logs. Access is granted through an API key, where a user key drives querying and configuration and a license key authenticates data sent in, and an agent is limited to the accounts and role-based access that key carries. There are no per-operation scopes, and New Relic can push alert issue changes to a webhook.
How an app or AI agent connects to New Relic determines what it can reach. Querying and configuration go through one GraphQL API, and sending data in goes through a set of separate ingest endpoints, each governed by the key behind it.
NerdGraph is the single GraphQL API for querying data and changing configuration. It answers at api.newrelic.com/graphql for US accounts and api.eu.newrelic.com/graphql for EU accounts, with a typed schema reached from an actor root.
The New Relic AI MCP server lets an agent reach New Relic in natural language through the Model Context Protocol, such as turning a question into NRQL and retrieving metrics, logs, and alert status. It is in public preview, answering at mcp.newrelic.com for US accounts and mcp.eu.newrelic.com for EU accounts, and authenticates with a user API key or OAuth.
Telemetry is sent in through separate regional HTTPS endpoints, one per data type, such as metric-api.newrelic.com for metrics and log-api.newrelic.com for logs. Each accepts a JSON POST authenticated with a license key and only writes into that key's account.
Workflows match alert issues and send notifications to destinations, and a webhook is one destination type, so New Relic posts a JSON payload to a registered URL when an issue is activated, acknowledged, or closed. Destinations, channels, and workflows are managed through NerdGraph.
A user key authenticates querying and configuration through NerdGraph, sent in the 'API-Key' header. It is tied to a person, and what it can reach is set by that person's account access and assigned role, so a read-only user cannot make configuration changes.
A license key authenticates data sent into an account through the Metric, Event, Log, and Trace endpoints, sent in the 'Api-Key' header. It only writes into its own account and cannot read or configure anything.
Browser and mobile monitoring data use their own dedicated keys, separate from the license key, each tied to a specific account. They authenticate only the browser or mobile agent that reports that data.
The New Relic API is split into areas an agent can act on, such as running NRQL queries, finding entities, managing alert policies and conditions, building dashboards, and sending in metrics, events, and logs. Each area has its own operations, and configuration changes affect what a whole team sees.
Run NRQL queries over an account's telemetry through NerdGraph and read back the results.
Search for monitored entities, read one by GUID, and add or replace the tags on an entity.
Search, create, update, and delete alert policies and their NRQL conditions.
Read a dashboard by GUID, and create, update, or delete dashboards and their pages and widgets.
Create, update, and delete workloads, which group entities for a combined health view.
Create, update, and delete synthetic monitors that check sites and APIs from chosen locations.
Create the destinations, channels, and workflows that send alert notifications, including webhooks.
Send metrics, events, logs, and traces into an account through the regional ingest endpoints.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
NRQL & queriesRun NRQL queries over an account's telemetry through NerdGraph and read back the results.1 | ||||||
| POST | query actor.account(id).nrql(query) | Run a NRQL query against an account and return the results. | read | User key | Current | |
NerdGraph has no per-operation scopes; a user key reaches whatever the user's role and account access allow. The default query timeout is 5 seconds. Acts ontelemetry Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limit3,000 NRQL queries per account per minute SourceOfficial documentation ↗ | ||||||
EntitiesSearch for monitored entities, read one by GUID, and add or replace the tags on an entity.4 | ||||||
| POST | query actor.entitySearch(query) | Search for monitored entities by name, type, tag, or other criteria. | read | User key | Current | |
Results are paginated with a nextCursor. Reading tags is done here rather than through a dedicated tagging query. Acts onentity Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query actor.entity(guid) | Read a single entity by its GUID, including a dashboard read as a DashboardEntity. | read | User key | Current | |
Reading a dashboard's full layout uses this field with the DashboardEntity type. Acts onentity Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation taggingAddTagsToEntity(guid, tags) | Add tags to an entity without removing its existing tags. | write | User key | Current | |
Tags drive entity search, workload membership, and scoping, so changes here ripple beyond the single entity. Acts onentity tag Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation taggingReplaceTagsOnEntity(guid, tags) | Replace all of an entity's tags with the supplied set. | write | User key | Current | |
This removes any existing tags not in the supplied set. taggingDeleteTagFromEntity removes specific tags instead. Acts onentity tag Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AlertsSearch, create, update, and delete alert policies and their NRQL conditions.7 | ||||||
| POST | query actor.account(id).alerts.policiesSearch | Search alert policies in an account, filtered by id, name, or name pattern. | read | User key | Current | |
Results are paginated with a cursor. Acts onalert policy Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsPolicyCreate(accountId, policy) | Create an alert policy, with its incident preference. | write | User key | Current | |
A user without an alerts-management role is blocked even though the mutation exists. Acts onalert policy Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsPolicyUpdate(accountId, id, policy) | Update an alert policy, such as its name or incident preference. | write | User key | Current | |
A partial update; only the supplied fields change. Acts onalert policy Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsPolicyDelete(accountId, id) | Delete an alert policy and its conditions. | write | User key | Current | |
Deleting a policy removes the conditions inside it. Acts onalert policy Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsNrqlConditionStaticCreate(accountId, policyId, condition) | Create a static NRQL alert condition inside a policy. | write | User key | Current | |
A baseline variant, alertsNrqlConditionBaselineCreate, exists for dynamic thresholds. Acts onalert condition Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsNrqlConditionStaticUpdate(accountId, id, condition) | Update a static NRQL alert condition. | write | User key | Current | |
Conditions can be read first with the nrqlConditionsSearch query. Acts onalert condition Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation alertsConditionDelete(accountId, id) | Delete an alert condition of any type. | write | User key | Current | |
The same mutation deletes static, baseline, and other condition types. Acts onalert condition Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
DashboardsRead a dashboard by GUID, and create, update, or delete dashboards and their pages and widgets.3 | ||||||
| POST | mutation dashboardCreate(accountId, dashboard) | Create a dashboard, with its pages and widgets. | write | User key | Current | |
Widgets are defined with NRQL, so a dashboard can surface any data the account holds. Acts ondashboard Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation dashboardUpdate(guid, dashboard) | Update a dashboard's pages and widgets. | write | User key | Current | |
Any page or widget left out of the input is removed, so an update must send the full intended layout. Acts ondashboard Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation dashboardDelete(guid) | Delete a dashboard. | write | User key | Current | |
This is a recoverable delete; dashboardUndelete restores it by GUID. Acts ondashboard Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkloadsCreate, update, and delete workloads, which group entities for a combined health view.3 | ||||||
| POST | mutation workloadCreate(accountId, workload) | Create a workload that groups entities for a combined health view. | write | User key | Current | |
Membership can be set by explicit GUIDs or by entity search queries. Acts onworkload Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation workloadUpdate(guid, workload) | Update a workload's membership or status configuration. | write | User key | Current | |
An update must send the complete new status configuration, not a partial one. Acts onworkload Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation workloadDelete(guid) | Delete a workload. | write | User key | Current | |
Deleting a workload also removes its history and metadata. Acts onworkload Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SyntheticsCreate, update, and delete synthetic monitors that check sites and APIs from chosen locations.4 | ||||||
| POST | mutation syntheticsCreateSimpleMonitor(accountId, monitor) | Create a simple ping monitor that checks a URL from chosen locations. | write | User key | Current | |
The monitor makes real outbound checks on a schedule against the URI it names. Acts onsynthetic monitor Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation syntheticsCreateScriptApiMonitor(accountId, monitor) | Create a scripted API monitor that runs a script against an API from chosen locations. | write | User key | Current | |
The script runs on a chosen runtime; older Node.js runtimes face a forced upgrade by 18 November 2026. Acts onsynthetic monitor Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation syntheticsUpdateSimpleMonitor(guid, monitor) | Update a simple ping monitor by its GUID. | write | User key | Current | |
Most fields are optional on update; only the supplied ones change. Acts onsynthetic monitor Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation syntheticsDeleteMonitor(guid) | Delete a synthetic monitor of any type by its GUID. | write | User key | Current | |
The same mutation deletes simple, scripted, and other monitor types. Acts onsynthetic monitor Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Notifications & workflowsCreate the destinations, channels, and workflows that send alert notifications, including webhooks.3 | ||||||
| POST | mutation aiNotificationsCreateDestination(accountId, destination) | Create a notification destination, such as a webhook, email, or third-party service. | write | User key | Current | |
Destination type can be WEBHOOK, EMAIL, JIRA, SERVICE_NOW, MICROSOFT_TEAMS, and others; Slack is connected through the UI rather than this mutation. Acts ondestination Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation aiNotificationsCreateChannel(accountId, channel) | Create a notification channel that formats the message sent to a destination. | write | User key | Current | |
A channel references a destination by id and sets the message template for a product such as ALERTS. Acts onchannel Permission (capability) User keyVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation aiWorkflowsCreateWorkflow(accountId, createWorkflowData) | Create a workflow that filters alert issues and sends them to channels on chosen triggers. | write | User key | Current | |
Each destination configuration lists the issue triggers, such as ACTIVATED, ACKNOWLEDGED, and CLOSED, that cause a notification to be sent. Acts onworkflow Permission (capability) User keyVersionAvailable since the API’s base version Webhook event issue-activatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Data ingestSend metrics, events, logs, and traces into an account through the regional ingest endpoints.4 | ||||||
| POST | https://metric-api.newrelic.com/metric/v1 | Send dimensional metric data into an account. | write | License key | Current | |
License key in the 'Api-Key' header. EU host: metric-api.eu.newrelic.com. Validation is asynchronous, so a 202 means accepted, not fully ingested. Acts onmetric Permission (capability) License keyVersionAvailable since the API’s base version Webhook eventNone Rate limit100,000 requests per minute per account; 1 MB max per POST SourceOfficial documentation ↗ | ||||||
| POST | https://insights-collector.newrelic.com/v1/accounts/{accountId}/events | Send custom event data into an account. | write | License key | Current | |
License key in the 'Api-Key' header; Browser, Mobile, and User keys will not work. EU host: insights-collector.eu01.nr-data.net. A successful POST returns 200. Acts onevent Permission (capability) License keyVersionAvailable since the API’s base version Webhook eventNone Rate limit100,000 requests per minute per account; 1 MB max per POST SourceOfficial documentation ↗ | ||||||
| POST | https://log-api.newrelic.com/log/v1 | Send log data into an account. | write | License key | Current | |
License key in the 'Api-Key' header. EU host: log-api.eu.newrelic.com. Timestamps older than 48 hours may be dropped. Acts onlog Permission (capability) License keyVersionAvailable since the API’s base version Webhook eventNone Rate limit300,000 requests per minute; 10 GB uncompressed JSON per minute; 1 MB max per POST SourceOfficial documentation ↗ | ||||||
| POST | https://trace-api.newrelic.com/trace/v1 | Send distributed trace data into an account, in New Relic or Zipkin format. | write | License key | Current | |
License key in the 'Api-Key' header. EU host: trace-api.eu.newrelic.com. The same path accepts both the newrelic and zipkin JSON formats. Acts ontrace Permission (capability) License keyVersionAvailable since the API’s base version Webhook eventNone Rate limit1 MB max per POST SourceOfficial documentation ↗ | ||||||
New Relic can notify an app or AI agent when an alert issue changes, instead of the app repeatedly asking. Notifications run through workflows that match issues and send to destinations, and a webhook is one destination type.
| Event | What it signals | Triggered by |
|---|---|---|
Issue activated | Fires when an alert issue moves to the activated state, meaning a condition has been breached. This trigger must be enabled for a workflow to send any notification. | mutation aiWorkflowsCreateWorkflow(accountId, createWorkflowData) |
Issue acknowledged | Fires when an alert issue is acknowledged by a user, from a notification, the issue page, or a third-party integration. | In-app only |
Issue closed | Fires when an alert issue is closed, whether because all its events closed, a time-to-live expired, or it went inactive. | In-app only |
Issue priority changed | Fires when an alert issue's priority is raised, such as from high to critical. | In-app only |
New Relic limits how fast and how much an app or AI agent can call, through a concurrency cap on the GraphQL API, a per-account ceiling on NRQL queries, and per-minute and per-payload limits on each ingest endpoint.
NerdGraph limits concurrency rather than the rate of requests: it guarantees 25 in-flight requests per user, tracked per user and not per key, so multiple keys for the same person share that ceiling, and excess concurrent requests are rejected with HTTP 429. Running NRQL queries through any API has a separate ceiling of 3,000 queries per account per minute, and the default NerdGraph query timeout is 5 seconds. The ingest endpoints have their own per-minute caps: the Metric and Event endpoints each accept up to 100,000 requests per minute per account, and the Log endpoint accepts up to 300,000 requests per minute and 10 GB of uncompressed JSON per minute, each returning HTTP 429 with a Retry-After header when exceeded.
GraphQL list fields that can return many results, such as entitySearch and the alerts policiesSearch and nrqlConditionsSearch fields, use cursor-based pagination: each response includes a nextCursor, which is passed back to fetch the following page until it comes back empty. NRQL queries return up to a LIMIT set in the query, where LIMIT MAX returns the maximum the platform allows for that query.
GraphQL requests and responses are JSON. Each ingest POST must be under 1 MB (10^6 bytes) or it is rejected with HTTP 413, and payloads can be sent gzip-compressed to fit more data under that ceiling. A metric may carry up to 150 attributes and an event up to 255, with attribute names up to 255 characters and values up to 4,096 characters.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | GraphQL errors array | NerdGraph returns HTTP 200 even when a query partially fails, putting problems in an 'errors' array in the response body alongside any data. The Event endpoint also returns 200 on a successful submission regardless of data-level errors inside the payload. | Inspect the 'errors' array in the body rather than relying on the HTTP status; for ingest, query the returned NrIntegrationError events to find data-level problems. |
| 202 | Accepted | The Metric endpoint returns 202 to confirm the payload was received and passed basic validation, returning a request identifier. Because validation is asynchronous, this does not guarantee every data point was ingested. | Treat 202 as accepted, then query NrIntegrationError events by the returned request identifier to confirm there were no data-level problems. |
| 403 | Authentication failure | The key is missing or invalid, or it is the wrong type or region for the endpoint, such as sending a User key to an ingest endpoint that needs a License key. | Send the correct key type for the endpoint and region, in the right header. |
| 413 | Payload too large | The ingest POST is over the 1 MB (10^6 bytes) limit. | Split the payload into smaller batches, or send it gzip-compressed to fit more data under the limit. |
| 429 | Too many requests | A rate or concurrency limit was exceeded. NerdGraph returns 429 when a user is over 25 in-flight requests, and the ingest endpoints return 429 when over their per-minute caps. | Honor the Retry-After header where present, and reduce concurrency or request rate before retrying. |
NerdGraph is a single, continuously updated GraphQL API with no dated version to pin. New Relic ships changes through its release notes, and the dated timeline below records notable ones.
NerdGraph is one GraphQL API with no dated version and no version header. The schema evolves additively, so new fields and operations are added without breaking existing queries, and fields are marked deprecated with notice before they are removed. New Relic ships changes through its release notes rather than minting version numbers.
New Relic updated the Synthetics NerdGraph API reference pages for all monitor types, covering the create, update, and delete mutations for simple, scripted, and other monitors. It was published the week of 8 to 12 June 2026.
The Synthetics NerdGraph examples were updated to recommend a newer scripting runtime, flagging an 18 November 2026 forced upgrade for older Node.js runtimes so that scripted monitors keep running. It was published the week of 11 to 15 May 2026.
As of 1 March 2025, the older REST API v2 no longer accepts the legacy REST API keys, which had to be replaced with User API keys. NerdGraph is the recommended API and is in the process of replacing REST v2.
There is no version header to set; the GraphQL schema evolves additively, and fields are deprecated with notice before removal.
New Relic docs release notes ↗Bollard AI sits between a team's AI agents and New Relic. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.