# How pagination works

Learn how to paginate results for list and search endpoints.

To learn about pagination with video tutorials, see [this playlist](https://www.youtube.com/playlist?list=PLy1nL-pvL2M7AvG4xrF6gmbSUW2FBUl9p).

The Stripe API has list and search endpoints that can return multiple objects, such as listing Customers or searching for PaymentIntents. To mitigate negative impacts to performance, these endpoints don’t return all results at once. Instead, Stripe returns one page of results per API call, with each page containing up to 10 results by default. Use the [limit](https://docs.stripe.com/api/pagination.md#pagination-limit) parameter to change the number of results per page.

For example, this is an API request to list Customers, with a `limit` of 3:

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d limit=3
```

The response from Stripe contains one page with 3 results:

```json
{
  "data": [
    {
      "id": "cus_005",
      "object": "customer",
      "name": "John Doe",
    },
    {
      "id": "cus_004",
      "object": "customer",
      "name": "Jane Doe",
    },
    {
      "id": "cus_003",
      "object": "customer",
      "name": "Jenny Rosen",
    },
  ],
  "has_more": true,
  /* ... */
}
```

Keep in mind the following details when using these endpoints:

- Objects are inside the `data` property.
- Objects are in reverse chronological order, meaning the most recently created object is the first one.
- The `has_more` property indicates if there are additional objects that weren’t returned in this request.

Instead of looping over the `data` array to go through objects, you should paginate results. This prevents you from missing some objects when the [has_more](https://docs.stripe.com/api/pagination.md#pagination-has_more) parameter is `true`.

## Auto-pagination

To retrieve all objects, use the auto-pagination feature. This automatically makes multiple API calls until `has_more` becomes `false`.

#### Ruby

```ruby
customers = Stripe::Customer.list()

customers.auto_paging_each do |customer|
    # Do something with customer
end
```

> When using auto-pagination with a list endpoint and setting [ending_before](https://docs.stripe.com/api/pagination.md#pagination-ending_before), the results are in chronological order, meaning the most recently created customer is the last one.

## Manual pagination

Follow these steps to manually paginate results. This process is different when calling a list endpoint or a search endpoint.

#### List

1. Make an API call to list the objects that you want to find.

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:"
```

1. In the response, check the value of [has_more](https://docs.stripe.com/api/pagination.md#pagination-has_more):

- If the value is `false`, you’ve retrieved all the objects.
- If the value is `true`, get the ID of the last object returned, and make a new API call with the [starting_after](https://docs.stripe.com/api/pagination.md#pagination-starting_after) parameter set.

Repeat this step until you’ve retrieved all of the objects that you want to find.

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d starting_after={{LAST_CUSTOMER_ID}}
```

#### Search

1. Make an API call to list the objects that you want to find.

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=metadata['foo']:'bar'"
```

1. In the response, check the value of [has_more](https://docs.stripe.com/api/pagination/search.md#search_pagination-has_more):

- If the value is `false`, you retrieved all the objects.
- If the value is `true`, get the `next_page` property from the response, and make a new API call with the [page](https://docs.stripe.com/api/pagination/search.md#search_pagination-page) parameter set.

Repeat this step until you’ve retrieved all of the objects that you want to find.

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=metadata['foo']:'bar'" \
  -d page={{NEXT_PAGE_ID}}
```