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

Owner, Admins, or add-on managers

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 any errors occur, all events in the request are rejected to prevent partial inserts. An error response includes the source of the error to aid debugging.

  • The X-Insert-Key must contain the correct Insert Key.
  • The Content-Type must be application/json.
  • Use POST only (PUT and GET requests are not accepted).

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

Submission errors

The following dropdown contains event submission errors and their meanings:

Error definitions
Error message Additional info
400 Missing API Key No account id path token supplied
400 Unparseable API Key Invalid insert key or the account does not have access to Insights
400 Invalid content type Invalid Content Type. Must be application/json. Note: the ICEI accepts any content type except multipart/related and assumes it can be parsed to json
400 JSON Parsing Error Error parsing JSON payload at event index X (X reflects the index within the JSON body at which the error occurred)
400 Missing Event Type Missing required field eventType at event index X (X reflects the index within the JSON body at which the error occurred)
400 Invalid event data Missing required field eventType at event index X (X reflects the index within the JSON body at which the error occurred)
400 Missing or Invalid Content Length Unable to process empty request
403 Invalid insert key
408 Request timed out
413 Content too large Request is too large to process (see below for more details)
429 Too many requests Unable to accept request at this time

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
  • API calls exceeding 10 seconds will timeout
  • Payloads exceeding 100KB may see increased response times

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