Send custom events with the Event API

The New Relic Event API lets you send custom events to your account with a POST command. These events appear in New Relic Insights as a new event type. You can use NRQL or the Insights Data Explorer to sample, query, and visualize your custom data.

If your account hosts data in the EU data center, ensure you are using the proper API endpoints for EU region accounts.

Basic workflow

The Event API is an asynchronous endpoint. This allows you to send a very large volume of Events POSTS, reliably, with very low response latency.

To send a custom event to your New Relic account:

  1. Register an Event API Insert key.
  2. Before creating custom events or attributes, review New Relic's list of reserved terms used by NRQL and Insights.
  3. Generate JSON for the event by instrumenting your application, querying an API, or some other method.
  4. Submit a compressed JSON payload (for example, gzip or deflate) to the HTTPS endpoint using cURL in a POST request.
  5. Recommendation: Set up NRQL alert conditions to notify you when parsing errors occur.

This method will send the events directly into your account, where they will be accessible with the Insights UI or the Query API.

The Event API limits the size, rate, and characters allowed in custom events. Also, like other Insights events, custom events cannot be updated or deleted after they are created. If you have problems with your custom event, follow the troubleshooting procedures or create a new custom event.

Register an Event API insert key

You must have access to the Insights UI and the correct permissions (Owner, Admins, or add-on managers) in order to register Event API insert keys.

Event API insert keys are generated for an account. They are not associated with a specific user. Anyone in the account with access to the insert key can add events with the Event API.

If you have a paid Insights subscription, you can submit multiple event types under a single insert key. However, to help ensure security, we recommend that you use different insert keys for different applications or different data sources.

To register an Event API insert key:

  1. Go to insights.newrelic.com > Manage data > API keys.
  2. Next to the Insert keys heading, select the symbol.
  3. Enter a short description (owner, team, purpose, data source, etc.) for the key.
  4. Select Save your notes.

The Insert key page lists the cURL command necessary to add event data for the key.

For security reasons, insert keys cannot be altered or read using the API. To change or read an insert key, use the New Relic UI.

Format the JSON

The Event API accepts specific formats for attributes included in the payload. Only float or string values are allowed.

JSON format guidelines

When defining attributes for your Insights custom events, follow these JSON format guidelines.

Attributes JSON format guidelines
eventType Required: The event's name.
Float and string values

Float value format: "label":value.

String value format: "label":"value".

Data types Insights only accepts key-value pairs, not map/object or array values. Supported data types for this API are strings and numbers (integers or floats). For more information, see Data requirements.
Digits in strings

For performance-related reasons, Insights does not cast values submitted to it. For example, Insights treats 123 as a number and "123" as a string.

Insights will only store up to 64 bit numbers. Any numbers larger than 64 bits will be truncated.

Dates For attributes that contain date information, use an unformatted Unix timestamp in the Insights Manage data > Formatter. You can define the date attribute either in seconds or in milliseconds, both relative to the Unix epoch.
Time

Unless otherwise specified, the timestamp for a submitted event is the time it was submitted to New Relic. To specify a different time for the event, use the timestamp attribute. The timestamp must be a 64-bit integer within 24 hours of the time the event is submitted to New Relic.

JSON example

Here is an example of a typical JSON data set to send to Insights. This call sends two Purchase type events as a JSON array. You can add multiple events in a single HTTP call using a JSON array.

[
  {
    "eventType":"Purchase",
    "account":3,
    "amount":259.54
  },
  {
    "eventType":"Purchase",
    "account":5,
    "amount":12309,
    "product":"Item"
  }
]

When generating the JSON, make sure your attributes are properly formatted.

Limits and restricted characters

Insights limits the size and rate of custom events:

  • Payload total size: 1MB maximum per call. We highly recommend using compression.
  • Attributes: 255 maximum per event
  • String attributes: 4KB maximum length

There is also a limit on the number of HTTP requests per minute.

Use only the following characters when adding a custom event:

  • accountId: Must be an integer.
  • appId: Must be an integer.
  • eventType: Can be a combination of alphanumeric characters, _ underscores, and : colons.
  • timestamp: Must be a 64-bit integer within 24 hours of the current time on the server. The timestamp attribute takes an unformatted Unix timestamp. You can define timestamps either in seconds or in milliseconds, both relative to the Unix epoch.

Submit the custom event

Data submitted to the Event API uses a compressed JSON format in a simple HTTPS POST request. The Insert key page in the Insights UI automatically generates a sample cURL query for you to use as a template. This example uses gzip, but you can also use deflate.

gzip -c example_events.json | curl -X POST -H "Content-Type: application/json" -H "X-Insert-Key: YOUR_KEY_HERE" -H "Content-Encoding: gzip" https://insights-collector.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/events --data-binary @-

Always use compression with every payload. This allows you to send more data to Insights, and it saves resources during parsing.

Before generating your HTTP request, make sure it is properly formatted, including:

  • The X-Insert-Key contains the correct Insert key.
  • The Content-Type is application/json.
  • The request uses POST only. The API does not accept PUT and GET requests.

The API supports HTTP/1.1 persistent connections. This is helpful to manage client-side performance under heavy event loads.

Verify or troubleshoot request response

The Event API follows a two-step process to process requests:

  1. The Event API synchronously acknowledges or rejects the request based on validation of the headers and payload size.
  2. The Event API asynchronously parses the payload after a successful HTTP response is provided to the client. This may generate an error due to missing or malformed data. These are classified as submission errors or parsing errors.

All successful submissions receive a 200 response, regardless of any data errors that may exist within the payload. The response includes a uuid, which is a unique ID created for each request. The uuid also appears in any error events created for the request.

Recommendation: In addition to checking for a success message, use the Insights Data explorer to ensure your events are reporting correctly and to generate queries.

Success response code
Success message Comments
200
{"success":true,"uuid":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}
Submission errors

Payloads with submission errors are handled and returned to the sender through an HTTP response code.

To troubleshoot payload submission errors, refer to these HTTP response codes.

Submission errors Troubleshooting
400

Missing or invalid content length: Unable to process empty request.

403

Missing or invalid API key: Invalid Insert key, or the account does not have access to Insights. Register a valid Insert key.

408

Request timed out: Request took too long to process.

413

Content too large: Request is too large to process. Refer to the limits and restricted characters to troubleshoot.

415

Invalid content type: Must be application/JSON. The Event API accepts any content type except multi-part/related and assumes it can be parsed to JSON.

429

Too many requests

503

Service temporarily unavailable: Retry request

Parsing errors

Parsing errors occur if:

  • An event is sent within a payload, but it is either missing data or is exceeding maximum limits. New Relic will drop the individual event from the payload, generate an NrIntegrationError event, and process the rest.
  • The JSON payload includes malformed JSON or missing required data.

Payloads with parsing errors receive a 200 response to indicate a successful submission. To resolve parsing errors, create a new event within the NrIntegrationError event type. All parsing errors are due to NRQL queries in Insights. For error messages related to dropped events, New Relic will include the number of events that were dropped as part of the message.

To troubleshoot requests with parsing errors, refer to these HTTP response codes.

Parsing errors Troubleshooting
X event(s) rejected because attribute appId was not an integer

An appId attribute has a non-integer value, such as a decimal value or string.

X event(s) rejected because eventType cannot contain the following characters: [., \]

An eventType attributed included an invalid character, such as a period or backslash.

X event(s) rejected because attribute is missing attribute name

An attribute name was set to null or an empty string.

X event(s) rejected because attribute name exceeded maximum length

An attribute name has more than 255 characters.

X event(s) rejected because attribute value exceeded maximum length

An attribute value was larger than 4KB.

X event(s) rejected because event exceeded maximum number of attributes

An event has more than 255 attributes.

X event(s) rejected because missing required attributes eventType

The eventType attribute is required for the custom event.

Error parsing JSON payload

There was an error parsing the request JSON because of formatting problems or corrupted data.

Query and alert with NrIntegrationError

The NrIntegrationError event allows you to query and set alerts on custom data being sent to your New Relic account. Recommendation: To have New Relic Alerts notify you about parsing errors, create a NRQL condition for NrIntegrationError. Use this example NRQL query:

SELECT message FROM NrIntegrationError WHERE newRelicFeature = 'Event API' AND category = 'EventApiException'
NrIntegrationError attributes Troubleshooting
timestamp The timestamp when the request was received. The timestamp attribute takes an unformatted Unix timestamp. You can define timestamps either in seconds or in milliseconds, both relative to the Unix epoch.
newRelicFeature The name of the feature experiencing errors. For all custom event parsing errors, this will be Event API.
apiKeyPrefix The first six characters of the Insert API key used for the request that generated an error.
requestId The uuid returned by the the API for the request that generated an error.
Category The category of the error. For custom events, this is EventApiException.
Message Contents of the error message.
Name The error's name. For custom events, this is always EventValidationException.

Limit on HTTP requests

The Event API has a rate limit of 100,000 HTTP requests (POSTs) per minute. (Note that this is not a limit on the number of events per minute; only on the number of POSTs per minute.)

This limit helps ensure that large traffic spikes in accounts across our multi-tenant platform do not negatively affect how the service performs for you.

If your API usage exceeds 100k POSTs in a 1-minute window, we will reject subsequent API requests with a 429 response code for the remainder of the 1-minute window. At the end of the 1-minute window, the counter will be reset and allow traffic to resume.

This limit is intended to be an upper threshold that you shouldn't hit under normal scenarios. If you have a high number of 429 responses, consider using the API less. If you are expecting a higher-than-normal activity level in the near future and want to prepare for that, contact technical support.

For more help

Recommendations for learning more: