Query Insights event data via API

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

To add custom events to Insights, use the Insights insert API.

For all available New Relic APIs, see Intro to APIs.

1. Register an API key

Owner, Admins, or add-on managers

To use the Insights query API, you need a query key. You can have multiple query keys, and 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, use the New Relic UI.

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.

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
      }
    ]
  }
}

Rate limiting guidelines

New Relic Insights employs rate limiting to ensure a high level of availability and reliability for all users. The amount of requests you can healthily execute depends on the type of query. A query to Insights occurs anytime an event-driven query is executed; for example:

  • Event charts rendered on an existing dashboard
  • Charts rendered through the NRQL query bar
  • Insights Query API

Most users rarely encounter rate limiting, especially if you follow these general guidelines:

  • Limit the amount of requests with complex queries (for example, queries with FACET or TIMESERIES clauses, or queries of over a million events) run at the same time.
  • Limit the amount of requests run concurrently over extended periods of time to a maximum of 5, especially if they include complex queries.

If New Relic applies rate limits on your account, the query API returns a 503 error. Dashboard charts in the New Relic UI also may display timeout error messages.

For more help

Recommendations for learning more: