New Relic Developers

Insights Data APIs

Add custom events and retrieve event data from the entire New Relic platform.

New Relic Insights uses an event data format, which means you can add and extract data programmatically. Event data consists of a timestamp, event type, and a set of arbitrary attributes—New Relic products report a variety of event data out of the box to track your system performance. The flexibility of this format means you can use custom events to get data-driven insights into whatever you care about.

Adding events with the Insights Insert API:

The Insert API sends custom events directly to Insights. For example, you could fire a custom event every time a user adds an item to their shopping cart, and track details about their purchase such as location or the exact item they added. Or, you could send a custom event when a user clicks a new button in your user interface to track usage of your new feature.

As an example, here is a sample JSON payload in a file named ‘example_events.json’:


Uploading the ‘example_events.json’ file contents to the Insights Data API on Unix:

gzip -c example_events.json | curl -X POST -H "Content-Type: application/json" -H "X-Insert-Key: YOUR_KEY_HERE" -H “Content-Encoding: gzip” --data-binary @-

Retrieving events with the Insights Query API:

You can retrieve your event data from Insights using NRQL queries. Using the Query API, you can send any valid NRQL query to the endpoint—so you can take the charts that drive your dashboards and access their data directly from your code. Insights returns your data in a standard JSON format, so the data is easy to parse and re-use.

Here's an example querying the sum of all Purchase events (“SELECT sum(amount) FROM Purchase”):

curl -H "Accept: application/json" -H "X-Query-Key: YOUR_KEY_HERE" ""

Insert Query API response JSON:

      "Sum": 12568.54

Learn more and start building

Group 7 Created with Sketch.


To add custom events via Insights API, see Insert custom events. To retrieve event data via Insights API, see Query Insights event data. You can also export your data in CSV.

Group 9 Created with Sketch.

NRU Tutorials

To learn how to make the most of our developer resources, check out New Relic University.

Group 8 Created with Sketch.

Community Forum

Connect with other developers in the New Relic Explorers Hub


For examples of integrations and other technologies, see our GitHub repo.