---
title: Pagination for API output
source: https://docs.newrelic.com/docs/apis/rest-api-v2/basic-functions/pagination-api-output
---

The New Relic REST API (v2) paginates some responses, for performance reasons. 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.

## Requirements and limitations [#requirements]

-   Metric data return:
    -   Pagination is no longer available for metrics output for some customers (deprecation beginning December 2020).
    -   Returns up to 3000 results per cell. For large outputs, we recommend narrowing the query using application ID or another attribute.
-   The sort order for returned data is indeterminate. Do not assume or rely on a particular order.

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.

> #### ⚠️ IMPORTANT
>
> Before listing metric names, see [Metric name listing guidelines](https://docs.newrelic.com/docs/apis/rest-api-v2/application-examples-v2/listing-your-app-id-metric-data-v2#name_list_guidelines).

## Request a specific page [#requesting_page]

To specify a page, add the `page=` parameter to the query. Here's an example:

```sh
curl -X GET 'https://api.newrelic.com/v2/alerts_incidents.json?page=3' \
     -H "Api-Key:$API_KEY" -i
```

In the REST API Explorer, you can quickly [change the page being viewed](https://docs.newrelic.com/docs/apm/apis/api-explorer-v2/parts-api-explorer#data_page).

## Link header examples showing page count [#link-header]

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.

> #### ⚠️ IMPORTANT
>
> The Link header will only appear if the output data is paginated.

> #### 💡 TIP
>
> The `rel="last"` reference will not be shown when making calls to the violations endpoint (`https://api.newrelic.com/v2/alerts_violations.json`). To determine the final page when making calls to this endpoint, look for the absence of a `rel="next"` reference.

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

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

New Relic uses the [RFC 5988](http://www.rfc-editor.org/rfc/rfc5988.txt) 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.

<table>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `...page=2>;rel="next"`
      </td>

      <td>
        Page 2 is the next page
      </td>
    </tr>

    <tr>
      <td>
        `...page=3>;rel="last"`
      </td>

      <td>
        Page 3 is the last page
      </td>
    </tr>
  </tbody>
</table>

````