Query Insights event data via API

The Insights query API is a REST API for querying your New Relic Insights' event data. After you supply a standard NRQL query via HTTPS request, the query API returns a JSON response for parsing. The query API is not the same as the Insights insert API:

  • Use the query API key to query your Insights data.
  • Use the insert API key to insert custom data into your Insights account.

1. Register an API key

Owner or Admins

To use the Insights query API, you will need a query key. To create a new query key:

  1. Go to insights.newrelic.com > Manage Data > API Keys.
  2. Select the plus icon next to the Query Keys heading.
  3. Enter a short description of the key.
  4. Select Save your notes.

You can have multiple query keys. Any query key can be used to initiate any Insights API query. If you have multiple systems querying Insights or different data destinations, New Relic recommends you use multiple query keys to enhance data security.

For security reasons, query keys cannot be altered or read using the API. To change or read a query key, you must do so from the New Relic UI.

2. Create the API query request

When you create or edit a query key, you will see a sample cURL query that you can use as a template:

curl -H "Accept: application/json" -H "X-Query-Key: YOUR_QUERY_KEY" "https://insights-api.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/query?nrql=YOUR_QUERY_STRING"

You must follow certain query rules or the query may fail:

3. Process the returned JSON

The query API returns results in JSON format. There is a limit of 1,000 results per request. The structure of the JSON data depends on the NRQL that you used in the request: Different combinations of SELECT statements, clauses, and functions each return an appropriate response. When writing your code to process the JSON, you should do a test run of your query and examine the resulting JSON.

Example

The Insights query API returns JSON data. Here's an example of an Insights query, its query request format, and its returned data:

Query, query API request, returned data

Original NRQL query:

SELECT count(appName) FROM PageView SINCE '2014-08-04 00:00:00+0500'

Query cURL request (with URL-encoded NRQL query):

curl -H "Accept: application/json" -H "X-Query-Key: YOUR_QUERY_KEY" "https://insights-api.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/query?nrql=SELECT+count%28appName%29+FROM+PageView+SINCE+%272014-08-04+00%3A00%3A00%2B0500%27"

Returned JSON data:

{
  "results": [
    {
      "count": 80275388
    }
  ],
  "metadata": {
    "eventTypes": [
      "PageView"
    ],
    "eventType": "PageView",
    "openEnded": true,
    "beginTime": "2014-08-03T19:00:00Z",
    "endTime": "2017-01-18T23:18:41Z",
    "beginTimeMillis=": 1407092400000,
    "endTimeMillis": 1484781521198,
    "rawSince": "'2014-08-04 00:00:00+0500'",
    "rawUntil": "`now`",
    "rawCompareWith": "",
    "clippedTimeWindows": {
      "Browser": {
        "beginTimeMillis": 1483571921198,
        "endTimeMillis": 1484781521198,
        "retentionMillis": 1209600000
      }
    },
    "messages": [],
    "contents": [
      {
        "function": "count",
        "attribute": "appName",
        "simple": true
      }
    ]
  }
}

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 support.newrelic.com.