• EnglishEspañol日本語한국어Português
  • Log inStart now

Incident event REST API

You can use the Event API to report custom alert incident events to New Relic.

The API is an asynchronous endpoint. This means you can send a large volume of POSTS, reliably, with low-response latency.

Using the API: an overview

Here's the general process for sending custom incident events to New Relic via the incident event API:

  1. Generate a for the account you want to report data to.
  2. Before you get started creating custom attributes, review the Event API's limits and restricted characters.
  3. Generate the JSON for your incident event that follows our JSON format guidelines.
  4. Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using curl in a POST request.

Once you've started sending incident event data to New Relic, we recommend that you set up NRQL alert conditions to get notifications about parsing errors.

Example JSON

Your JSON payload may look something like this example.

"eventType": "NrAiIncidentExternal",
"title": "Test",
"description": "The latency is above threshold of 500000 MS",
"state": "trigger",
"source": "luna",
"entityName": "testEntity",
"entity.guid": "testEntity123",
"aggregationTag.serviceId": 5,
"aggregationTag.environment": "testing",
"aggregationTag.errorId": 10543,
"tag.stackTrace": "some stack trace...",
"version": 1

The eventType field must use NrAiIncidentExternal.

Send your incident event from the command line

Here's an example of how to use curl to send your JSON payload.

gzip -c example_incidents.json | curl --data-binary @- \
-X POST -H "Content-Type: application/json" \
-H "Api-Key: YOUR_LICENSE_KEY" -H "Content-Encoding: gzip" \
{"success":true, "uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}%

Once you've successfully sent your incident event data, you can see it in the alerts UI or by querying that data.

Example query for incident events

You can query your data with Nerdgraph API.

Here's an example of a NerdGraph query and its result.

actor {
account(id: YOUR_ACCOUNT_ID) {
nrql(query: "SELECT * FROM NrAiInternalIncident since 3 days ago") {
"results": [
"timestamp": 1641910123824,
"totalViolations": 3,
"violationIds": "[416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6]",
"triggeredAt": 1641909163980,
"entitiesData.ids": "testEntity123",
"entitiesData.types": "unknown",
"labelsHash": "91f938318e899dcd62965e2724548f4844f2898f3cf1c5411397ecc0eec87fc1",
"annotations.description": "[\"The latency is above threshold of 500000 MS\"]",
"labels.originalAccountIds": "YOUR_ACCOUNT_ID",
"entitiesData.names": "testEntity",
"entitiesData.entities": "{\"id\":\"testEntity123\",\"name\":\"testEntity\",\"type\":\"unknown\"}",
"priority": "HIGH",
"labels.serviceId": "5",
"labels.environment": "testing",
"closedAt": "",
"updatedAt": 1641910123824,
"annotations.title": "[\"Test\",\"Test2222\",\"Test3\"]",
"nrAccountId": YOUR_ACCOUNT_ID,
"accumulations": "{\"source\":[\"rest\"],\"origin\":[\"luna\"],\"entity_guid\":[\"testEntity123\"],\"tag.stackTrace\":[\"some stack trace...\"]}",
"labels.accountIds": "YOUR_ACCOUNT_ID",
"createdAt": 1641909163997,
"priority.order": 2,
"labels.aggregationKeys": "416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6",
"accumulations.origins": "[\"luna\"]",
"accumulations.entity_guid": "[\"testEntity123\"]",
"incidentId": "a06ffb92-2f7e-473b-953f-151ff4777cb0",
"labels.errorId": "10543",
"dataMLModules": "{}",
"triggerEvent": "VIOLATION_ADDED",
"accumulations.tag.stackTrace": "[\"some stack trace...\"]",
"isIint": false,
"accumulations.sources": "[\"rest\"]",
"entitiesData": "{\"name\":\"testEntity\",\"id\":\"testEntity123\",\"type\":\"unknown\",\"entities\":\"{\\\"id\\\":\\\"testEntity123\\\",\\\"name\\\":\\\"testEntity\\\",\\\"type\\\":\\\"unknown\\\"}\"}",
"annotations": "{\"title\":[\"Test\",\"Test2222\",\"Test3\"],\"description\":[\"The latency is above threshold of 500000 MS\"]}",
"labels": "{\"accountId\":\"XXXXXXX\",\"originalAccountId\":\"XXXXXXX\",\"entityId\":\"testEntity123\",\"entityName\":\"testEntity\",\"entityType\":\"unknown\",\"aggregationKey\":\"416e2e55069764086ad83e97a1160be0cb4c545b7950522f7c86baaa2a11b9b6\",\"serviceId\":\"5\",\"errorId\":\"10543\",\"environment\":\"testing\"}",
"state": "CREATED"

Incident event API specification

The incident event API uses the Event API's value types. For descriptions of these value types and guidelines on using them, see our event API JSON guidelines.




string, number, or timestamp


Any attribute prefixed with aggregationTag will be used to aggregate trigger events together.

In other words, two trigger events with the same aggregation tags are aggregated to the same incident. (This assumes there's no resolve event between them).

When resolving incidents, it’s important that the resolve event include the same aggregation tags.

Aggregations tags with reserved keywords are filtered out. For example, in a JSON payload with aggregationTag.priority: 2 this key-value pair will be omitted in the incident event with these reserved keywords:

reserved_key: {"priority", "accountId", "originalAccountId", "policyId", "conditionId", "aggregationKey", "entityType", "entityName", "entityId", "violationUuid", "violationId", "nrIncidentId" }


enum: (trigger, resolve)


Whether the event should trigger a new incident or resolve an existing one. Updates to the incident can also be sent using trigger.


enum: (low, medium, high, critical)

The incident's priority. Default: high.

Highest priority will be used when different priorities are sent.



REQUIRED, when state is trigger

The triggering event's title.



REQUIRED, when state is trigger

The origin of the incident, or the monitoring system that triggered it (not the entity that faulted).



The triggering event's description.



A deep link to a page related to the incident.



A runbook URL.



An external ID you can attach to the event.

For example, it can be used to query for errors related to ingesting this event.



The name of the entity that generated the incident.



The ID of the entity that generated the incident.



The current format's version.

Copyright © 2024 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.