Insert custom events via the Insights API

You can store custom events to make them available for querying, by inserting them via the Insights API. Your custom events appear in New Relic Insights as a new event type. You can also use the Insights Data Explorer to ensure your events are reporting correctly and to generate queries.

You can also record custom events directly from supported agents using the appropriate agent API for regular events; for example Transactions (inserted via New Relic APM agents) and PageViews (inserted via New Relic Browser agents).

You must have access to the Insights UI in order to register Insert keys or to insert custom events via the Insights API.

Insert an event

Insights only supports event insertion via POST. To insert an event into your New Relic Insights account:

  1. Register an Insights API Insert key.
  2. Generate JSON for the event by instrumenting your application, querying an API, or some other method.
  3. Submit the JSON to the Insights HTTPS endpoint using cURL in a POST request.

This method will insert the events directly into your Insights account. You can query those events as a new event type. You can also use custom attributes to decorate your default Transaction and PageView events with additional attributes.

Insights limits the size, rate, and characters allowed in custom events. Like other Insights events, custom events cannot be updated or deleted after they are created.

Register an API key

The Insert key allows you to insert events into Insights. If you have a paid Insights subscription, you can submit multiple event types under a single insert key. To help ensure security, use different insert keys for different applications or different data sources.

Insights > Manage data > API keys > Edit: When you create or edit an insert key, Insights provides both the key and an example HTTP request using the key.

To add an insert key:

  1. From the New Relic menu bar, select Insights > Manage data > API keys.
  2. From API key management, select the symbol next to the Insert keys heading.
  3. Enter a short description for the key.
  4. Select Save your notes.

The Insert key page lists the cURL command necessary to insert data for that 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.

Instrument your application

You can insert custom events from your APM-instrumented app directly from a New Relic agent. You can also insert events from end-user browsers with the Insights JavaScript API.

Format the JSON

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 insert multiple events in a single HTTP call using a JSON array.


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

Attributes JSON format guidelines
eventType Required. This is the Insights name for the event.
Float values Use the format "label":value.
String values Use the format "label":"value".
Data types Insights only accepts key-value pairs, not map/object or array values. Only floats and strings are supported data types.
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.
Dates For attributes that contain date information, use an unformatted Unix timestamp in the Insights Manage data > Data formatter. You can define the date attribute either in seconds or in milliseconds, both relative to the Unix epoch.

Specify different timestamp

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 within 24 hours of the time the event is submitted to New Relic.

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 event

Data is submitted to Insights in JSON format using a simple HTTP request. The Insert key page automatically generates a sample cURL query for you to use as a template:

cat example_events.json | curl -d @- -X
  POST -H "Content-Type: application/json" -H "X-Insert-Key: YOUR_KEY_HERE"

When generating the HTTP request, make sure it is properly formatted. If the event type is missing, Insights may not report an error when it fails to record the data. Insights will fail silently on JSON errors.

  • The X-Insert-Key must contain the correct Insert Key.
  • The Content-Type must be application/json.
  • Use POST, not PUT or GET.

HTTP/1.1 Persistent connections are supported. This is helpful to manage client-side performance under heavy event loads.

Limits and restricted characters

Insights limits the size and rate of custom events:

  • Attributes: 255 maximum per event
  • String attributes: 4KB maximum length
  • Batch total count: 1000 events per call
  • Batch total size: 1MB maximum per call

Use only the following characters when inserting 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 +/- 1 day (24 hours) of the current time on the server.

NRQL syntax terms as attribute names

Before creating custom attributes, review New Relic's list of reserved terms used by NRQL and Insights. Otherwise unexpected results may occur.

For more help

For assistance with New Relic Insights, join us in the New Relic Online Technical Community. Ask and answer questions, and learn more about New Relic Insights from fellow Insights users.

If you need additional help, get support at