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

# Pagination

> How list endpoints paginate, what the response carries, and how to iterate to completion.

WiseYield list endpoints use **offset pagination** with two query parameters and a response envelope that tells you exactly where you are.

## The contract

```bash theme={null}
GET /api/v1/farms?page=1&limit=20
```

| Parameter | Type    | Default | Constraints |
| --------- | ------- | ------- | ----------- |
| `page`    | integer | `1`     | ≥ 1         |
| `limit`   | integer | `20`    | 1–100       |

Responses wrap data in an envelope with a `pagination` object:

```json theme={null}
{
  "data": [
    { "id": "...", "name": "Green Valley Farm", "...": "..." }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3
  }
}
```

| Field        | Meaning                                                 |
| ------------ | ------------------------------------------------------- |
| `page`       | The page you requested (echoed back, never re-numbered) |
| `limit`      | The page size that was applied (may be clamped to 100)  |
| `total`      | Total active records matching the query                 |
| `totalPages` | `Math.ceil(total / limit)` — convenience field          |

## Iterating to completion

<CodeGroup>
  ```javascript JavaScript theme={null}
  async function* listAllFarms(apiKey) {
    let page = 1;
    while (true) {
      const res = await fetch(
        `https://www.wiseyield.co/api/v1/farms?page=${page}&limit=100`,
        { headers: { Authorization: `Bearer ${apiKey}` } }
      );
      const { data, pagination } = await res.json();
      for (const farm of data) yield farm;
      if (page >= pagination.totalPages) break;
      page++;
    }
  }

  // Usage
  for await (const farm of listAllFarms(process.env.WISEYIELD_API_KEY)) {
    console.log(farm.id);
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  def list_all_farms(api_key):
      page = 1
      while True:
          res = requests.get(
              'https://www.wiseyield.co/api/v1/farms',
              params={'page': page, 'limit': 100},
              headers={'Authorization': f'Bearer {api_key}'},
          )
          body = res.json()
          for farm in body['data']:
              yield farm
          if page >= body['pagination']['totalPages']:
              break
          page += 1

  # Usage
  for farm in list_all_farms(os.environ['WISEYIELD_API_KEY']):
      print(farm['id'])
  ```
</CodeGroup>

## Sorting and filtering

Most list endpoints accept `sort`, `order`, and resource-specific filter parameters. They compose with pagination:

```bash theme={null}
GET /api/v1/farms?status=active&sort=createdAt&order=desc&page=1&limit=50
```

| Parameter | Type            | Notes                                                          |
| --------- | --------------- | -------------------------------------------------------------- |
| `sort`    | string          | Field to sort by — varies per resource (see the endpoint page) |
| `order`   | `asc` or `desc` | Default `desc`                                                 |

Filters are resource-specific. See each endpoint's reference page for the supported set.

## Things to know

* **Pagination is stable** under steady traffic but **not snapshot-isolated** — a record created between page 2 and page 3 will shift everything. If you need a consistent snapshot, paginate by sorting on a stable cursor (e.g. `createdAt asc`) and remember the last seen value rather than re-using `page`.
* **`limit` is hard-capped at 100.** Requesting `limit=500` is silently clamped to `100`.
* **`page=0` is treated as `page=1`** rather than returning an error.
* **Soft-deleted records are excluded.** `total` reflects only active rows.
* **The `pagination` envelope is consistent across every list endpoint.** Integrators can write a single pagination helper and reuse it everywhere.

## Performance tips

* Use `limit=100` for bulk reads — fewer round-trips, same rate-limit cost (one request per page).
* Filter aggressively in the query rather than client-side — every list endpoint supports the obvious filters (status, date range, type) and applies them at the database level.
* For very large exports (>10k records), prefer the dedicated export endpoints (e.g. `GET /api/v1/farms/{id}/reports/accounting-export`) when available — they return the full dataset in a single call with a higher rate-limit budget.