> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grainledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> Page through list endpoints with page and limit query parameters.

List endpoints return paginated results. Use `page` and `limit` query parameters to control how many records you fetch per request.

## Query parameters

| Parameter | Type    | Default | Description           |
| --------- | ------- | ------- | --------------------- |
| `page`    | integer | `1`     | Page number (1-based) |
| `limit`   | integer | `20`    | Records per page      |

<Tip>
  Use `limit=100` or lower for most integrations. Some endpoints allow higher limits; check the API reference for per-endpoint maximums.
</Tip>

## Response shape

List endpoints return the resource array plus a `pagination` object:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "donors": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}
```

| Field        | Description                      |
| ------------ | -------------------------------- |
| `page`       | Current page number              |
| `limit`      | Page size used for this request  |
| `total`      | Total matching records           |
| `totalPages` | Total pages at the current limit |

## Iterate through all pages

<CodeGroup>
  ```javascript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  async function fetchAllDonors(accessToken, organizationId) {
    const donors = [];
    let page = 1;
    let totalPages = 1;

    while (page <= totalPages) {
      const response = await fetch(
        `https://api.grainledger.com/api/v1/donors?page=${page}&limit=100`,
        {
          headers: {
            Authorization: `Bearer ${accessToken}`,
            "X-Organization-Id": organizationId,
          },
        }
      );
      const data = await response.json();
      donors.push(...data.donors);
      totalPages = data.pagination.totalPages;
      page += 1;
    }

    return donors;
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  def fetch_all_donors(access_token, organization_id):
      donors = []
      page = 1
      total_pages = 1

      while page <= total_pages:
          response = requests.get(
              "https://api.grainledger.com/api/v1/donors",
              params={"page": page, "limit": 100},
              headers={
                  "Authorization": f"Bearer {access_token}",
                  "X-Organization-Id": organization_id,
              },
          )
          data = response.json()
          donors.extend(data["donors"])
          total_pages = data["pagination"]["totalPages"]
          page += 1

      return donors
  ```
</CodeGroup>

## Endpoints that support pagination

All list endpoints use the same pagination pattern:

* [List transactions](/api-reference/transactions/list-transactions)
* [List bills](/api-reference/bills/list-bills)
* [List donors](/api-reference/donors/list-donors)
* [List contributions](/api-reference/contributions/list-contributions)
* [List pledges](/api-reference/pledges/list-pledges)
* [List households](/api-reference/households/list-households)