> For the complete documentation index, see [llms.txt](https://docs.commercelayer.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.commercelayer.io/core/pagination.md).

# Pagination

How paginated results work

When you fetch a collection of resources, you get paginated results. The response contains the record count and the page count, number, and size in the `meta` attribute and the URLs of the other pages in the `links` attribute.

```json
{
  "data": [...],
  "meta": {
    "record_count": 140,
    "page_count": 14,
    "page_number": 1,
    "page_size": 10,
    "...": "..."
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/skus?page[number]=1&page[size]=10",
    "next": "https://yourdomain.commercelayer.io/api/skus?page[number]=2&page[size]=10",
    "last": "https://yourdomain.commercelayer.io/api/skus?page[number]=14&page[size]=10"
  }
}
```

{% hint style="warning" %}
On some high-volume collections (e.g. orders, SKUs, prices, customers, line items, stock items, gift cards, and order subscriptions), `record_count` and `page_count` become approximate once the result set is estimated to exceed **10,000** records. When this happens, the [document-level meta](/core/api-specification.md#document-level-meta) includes a `record_count_estimated` attribute set to `true` — if it's absent, the counts are exact. Page contents stay exact either way.
{% endhint %}

{% hint style="info" %}
The default page number is **1** (consequently, the link to the `prev` page is missing), and the default page size is **10**. The maximum page size allowed is **25**, but we recommend using a lower value unless strictly necessary. If you need to modify these default settings, use the `page` query parameter in your request.
{% endhint %}

{% hint style="warning" %}
If you need to gather information about large sets of resources for analytics/reporting purposes, please avoid making multiple paginated requests to the related resource endpoint. Use [exports](/core/exporting-resources.md) instead, which are a best fit for that. Alternatively, you can also perform a [search query](/metrics/getting-started/queries/search.md) using our [Metrics API](https://docs.commercelayer.io/metrics/) (at the moment limited to [orders](/metrics-api-reference/resources/orders.md), [carts](/metrics-api-reference/resources/carts.md), and [returns](/metrics-api-reference/resources/returns.md)).
{% endhint %}

### Example

{% tabs %}
{% tab title="Request" %}
The following request fetches the SKUs, setting the page number to 3 and the page size to 5:

```shell
curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/skus?page[size]=5&page[number]=3' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'
```

{% endtab %}

{% tab title="Response" %}
On success, the API responds with a `200 OK` status code, returning the five resource objects listed on the third page (from the 6th object to the 10th), together with the record and page counts and the links to the `first`, `prev`, `next,` and `last` page.

```json
{
  "data": [
    {
      "id": "xYZkjABcde",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
                  {
      "id": "yzkWXfgHQS",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}   
    },
    {
      "id": "aBmNkPQRst",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
    {
      "id": "WAspXYhfCV",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    },
    {
      "id": "QWERtyUpBa",
      "type": "skus",
      "links": {...},
      "attributes": {...},
      "relationships": {...},
      "meta": {...}
    }       
  ],
  "meta": {
    "record_count": 140,
    "page_count": 28,
    "page_number": 3,
    "page_size": 5,
    "mode": "test",
    "organization_id": "QKpXnYvZeB",
    "trace_id": "8c5f3a9e1d7b4c2f8a6e0d5b9c3f7a1e4d8b6c0f2a5e9d3b7c1f5a8e2d6b4c9f"
  },
  "links": {
    "first": "https://yourdomain.commercelayer.io/api/skus?page[number]=1&page[size]=5",
    "prev": "https://yourdomain.commercelayer.io/api/skus?page[number]=2&page[size]=5",
    "next": "https://yourdomain.commercelayer.io/api/skus?page[number]=4&page[size]=5",
    "last": "https://yourdomain.commercelayer.io/api/skus?page[number]=28&page[size]=5"
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The example query parameters above use unencoded `[` and `]` characters simply for readability. In practice, these characters must be percent-encoded, per the requirements in [RFC 3986](http://tools.ietf.org/html/rfc3986#section-3.4).
{% endhint %}

{% hint style="danger" %}
Event stores use a slightly different pagination method based on a cursor instead of the page number (learn more [here](/core-api-reference/event_stores.md#pagination)).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.commercelayer.io/core/pagination.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.