Pagination for API output

For performance reasons the New Relic REST API (v2) paginates the response output. This is because returning the entire data set might be feasible for some queries but prohibitive for others that return a very large amount of data.

The sort order for returned data is indeterminate. Do not assume or rely on a particular order.

Objects returned per page

The data returned per page depends on what data is requested. The number of pages depends on the number of JSON objects necessary to complete the list.

The following limits are not configurable:

Metrics Limits
Data values 200 JSON objects per page.
Names

1000 JSON objects per page.

This applies to the following commands in the API Explorer:

Before listing metric names, see Paging for metric names and the Metric name listing guidelines.

Request a specific page

To specify a page, add the page= parameter to the query. The following example requests page 15:

curl -X GET 'https://api.newrelic.com/v2/applications/${APP_ID}/metrics.xml?page=15' \
     -H 'X-Api-Key:${API_KEY}' -i

In the REST API Explorer, you can quickly change the page being viewed.

The API call returns the Link header if the data is paginated. This indicates the number of pages and the page being viewed. This line also appears at the top of the Response in the REST API Explorer.

The Link header will only appear if the output data is paginated.

To obtain this line using some implementations of cURL, you may need to include the -v option.

curl -v -X GET 'https://api.newrelic.com/v2/applications/${APP_ID}/...'

New Relic uses the RFC 5988 standard format for links.

Example: Return 3 pages

The API output will contain a Link line similar to this. Lines are wrapped to improve readability.

Link: <https://api.newrelic.com/v2/alert_policies.xml?page=2>;rel="next", 
<https://api.newrelic.com/v2/alert_policies.xml?page=3>;rel="last"

This indicates there are three pages and you are viewing the first one.

Parameter Description
...page=2>;rel="next" Page 2 is the next page
...page=3>;rel="last" Page 3 is the last page
Example: Return 20 pages

The API output will contain a Link line similar to this. Lines are wrapped to improve readability.

Link: <https://api.newrelic.com/v2/applications/5313884/metrics.xml?page=1>;rel="first", 
<https://api.newrelic.com/v2/applications/5313884/metrics.xml?page=18>;rel="prev", 
<https://api.newrelic.com/v2/applications/5313884/metrics.xml?page=20>;rel="next", 
<https://api.newrelic.com/v2/applications/5313884/metrics.xml?page=20>;rel="last" 

This indicates there are 20 pages and you are viewing page 19.

Parameter Description
...page=1>;rel="first" This is the first page.
...page=18>;rel="prev" Page 18 is the previous page.
...page=20>;rel="next" Page 20 is the next page.
...page=20>;rel="last" Page 20 is the last page.

Pagination for metric names

New Relic recommends using this pagination technique when listing multiple pages of metric names.

Listing metric names requires intensive database computations when there are multiple pages. The process consumes resources on the New Relic collector as well as pushing the time consumed to the Overload protection limit. However, there is a cursor-based technique, which allows for easier pagination through the metric names.

When New Relic returns the first page (1000 metric names), the link header line will show page=2 rel=next, indicating that page 1 is being reported. It will also show a cursor entry that can be used to acquire the next page of data. The last page, page=x rel=last, is still reported to provide the page count as needed.

When the cursor value is submitted, the next page of metric names being shown will contain a new cursor value in the Link line referring to the next page. This process can continue until the last page is reached. On the last page, no new cursor value will appear.

The cursor paging technique is available for any API call that lists the metric names, but not for the metric values. The cursor parameter in the API explorer metric name endpoints implements this feature.

The following example shows the use of the cursor technique to request several pages of metric names:

Metric name pagination example

First request

This example shows filtering for all metric names that may contain the string "View" by specifying name=View. The output for this example is 3 pages long:

curl -X GET 'https://api.newrelic.com/v2/applications/${APP_ID}/metrics.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'name=View' 

The output Link line (wrapped for display purposes) shows the total page count indicated by "page=3" and "rel=last" as well as the cursor value that can be used to acquire the next page, page=2.:

Link: <https://api.newrelic.com/v2/applications/${APP_ID}/metrics.json?name=View&page=2&cursor=a1pHUmtaR1JiR1krYmc9PQ%3D%3D>; rel="next", 
      <https://api.newrelic.com/v2/applications/${APP_ID}/metrics.json?name=View&page=3>; rel="last"

The use of the filter is not necessary, it is included in this example to demonstrate that filtering and pagination may be used simultaneously.

Second request

This request is for the next page with filtering name=View and shows the use of the the cursor value from the first response above.

curl -X GET 'https://api.newrelic.com/v2/applications/12345/metrics.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'name=View&cursor=a1pHUmtaR1JiR1krYmc9PQ%3D%3D' 

The output Link line (wrapped for display purposes) shows a new cursor value for the "rel=next" page but does not indicate the current line.

Link: <https://api.newrelic.com/v2/applications/12345/metrics.json>; rel=first, 
      <https://api.newrelic.com/v2/applications/12345/metrics.json?cursor=REF3TURBd05ibURTOHc9PQ%3D%3D>; rel=next

Third and final request

This request is for the 3rd and final page with filtering name=View and uses the cursor value from the second response above.

curl -X GET 'https://api.newrelic.com/v2/applications/12345/metrics.json' \
     -H 'X-Api-Key:${API_KEY}' -i \
     -G -d 'name=View&cursor=REF3TURBd05ibURTOHc9PQ' 

The output Link line indicates the end of the list by the non-existent cursor, "cursor=" value for "rel=next".

Link: <https://api.newrelic.com/v2/applications/12345/metrics.json>; rel=first, 
      <https://api.newrelic.com/v2/applications/12345/metrics.json?cursor=>; rel=next

For more help

Additional documentation resources include:

Recommendations for learning more: