---
title: Insights query API
source: https://docs.newrelic.com/docs/apis/insights-apis/query-insights-event-data-api
---
> #### ⚠️ FEATURE AVAILABILITY
>
> This feature isn't available in all regions. Refer to the [data center and regional availability](https://docs.newrelic.com/docs/accounts/accounts-billing/account-setup/choose-your-data-center#feature-limitations-by-region) page to check if it's supported in your region and explore alternative solutions.
The New Relic Insights query API is a REST API for making NRQL queries.
> #### 💡 TIP
>
> **This API is no longer the preferred way to query New Relic data.** Please use [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) to do that.
## Requirements and recommendations [#requirements]
**This API is no longer the preferred way to query New Relic data.** For best results, you should use [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph) to query data.
Use of this API may be restricted by role-related user permissions.
To add custom data to New Relic, see [Report custom data](https://docs.newrelic.com/docs/data-apis/custom-data/get-custom-data-from-any-source).
If your organization hosts data in the EU data center, ensure you're using the proper [EU region endpoints](https://docs.newrelic.com/docs/using-new-relic/welcome-new-relic/getting-started/introduction-eu-region-data-center#endpoints).
## 1. Register an API key [#register]
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.
> #### 💡 TIP
>
> **This API is no longer the preferred way to query New Relic data.** Please use [NerdGraph](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/) to do that.
To create a new query key:
1. Go to [one.newrelic.com/api-keys](https://one.newrelic.com/api-keys). If you are using the EU data center, go to [one.eu.newrelic.com/api-keys](https://one.eu.newrelic.com/api-keys) instead.
2. Click **Create a key button** located in the top-right corner of the API keys page.
3. Configure the new key:
- Enter a name for the new key in the provided field.
- Add a description (such as "Query key").
4. Click **Save** to generate the new key.
## 2. Create the API query request [#create-request]
When you [create or edit a query key](#register), you will see an example `curl` query that you can use as a template. The example query won't work unless you follow these query rules:
- The [NRQL query string](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/using-nrql/introduction-nrql) must be [URL-encoded](http://www.w3schools.com/tags/ref_urlencode.asp).
- The query string must be less than 4000 bytes.
- The URL must contain a valid [account ID](https://docs.newrelic.com/docs/accounts-partnerships/accounts/account-setup/account-id).
- The `X-Query-Key` must contain a valid [query key](#register).
- The `Content-Type` must be `application/json`.
### Linux [#unix]
Here is a `curl` example:
```sh
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_URL_ENCODED_QUERY"
```
### Microsoft Windows [#windows]
You can use **Powershell** to query events via API:
```powershell
Invoke-WebRequest -Uri https://insights-api.newrelic.com/v1/accounts/YOUR_ACCOUNT_ID/query?nrql=YOUR_URL_ENCODED_QUERY -Headers @{"X-Query-Key"="YOUR_QUERY_KEY"} -ContentType "application/json" -Method GET
```
## 3. Process the returned JSON [#process-result]
The query API returns results in JSON format. There is a limit of 5,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 a query, its query request format, and its returned data:
**Query, query API request, returned data**
**Original NRQL query:**
````sql
SELECT count(appName) FROM PageView SINCE '2014-08-04 00:00:00+0500'
```
**Query cURL request (with URL-encoded NRQL query)**:
```sh
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:**
```json
{
"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 [#rate-limiting]
We have [query rate limits](https://docs.newrelic.com/docs/query-your-data/nrql-new-relic-query-language/get-started/rate-limits-nrql-queries/). You likely won't encounter these limits, 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 for the number of queries per minute, the query API returns a 429 error. If New Relic applies rate limits on your account for records inspected, the query API returns a 503 error and your charts may display timeout error messages.