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

# Pagination

> How to paginate through list endpoints in the Nectar API.

All list endpoints in the Nectar API return paginated responses. This guide explains the response format and how to iterate through all pages.

## Response envelope

Every paginated endpoint returns a JSON object with these fields. The item key name varies by endpoint (`documents`, `usageData`, `meters`, or `connections`).

```json Example (documents) theme={null}
{
  "totalDocuments": 250,
  "perPage": 100,
  "totalPages": 3,
  "currentPage": 1,
  "hasNext": true,
  "hasPrevious": false,
  "documents": [
    { "id": "...", ... },
    { "id": "...", ... }
  ]
}
```

| Field         | Type    | Description                                                                                                            |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------- |
| `total*`      | Integer | Total number of records across all pages (e.g., `totalDocuments`, `totalUsageData`, `totalMeters`, `totalConnections`) |
| `perPage`     | Integer | Number of records per page (fixed at 100)                                                                              |
| `totalPages`  | Integer | Total number of pages                                                                                                  |
| `currentPage` | Integer | Current page number (1-indexed)                                                                                        |
| `hasNext`     | Boolean | Whether a next page exists                                                                                             |
| `hasPrevious` | Boolean | Whether a previous page exists                                                                                         |
| Items array   | Array   | Records for the current page (key name matches the endpoint: `documents`, `usageData`, `meters`, or `connections`)     |

## Query parameters

| Parameter | Default | Description                                                                             |
| --------- | ------- | --------------------------------------------------------------------------------------- |
| `page`    | `1`     | Page number (1-indexed)                                                                 |
| `limit`   | `100`   | Number of records per page (currently supported on `GET /connection/company/{id}` only) |

For most list endpoints, page size is fixed at **100 records per page**. `GET /connection/company/{id}` also supports an optional `limit` parameter.

## Example: iterate all pages

<CodeGroup>
  ```python Python theme={null}
  import requests

  API_KEY = "YOUR_SECRET_KEY"
  BASE_URL = "https://external.nectarclimate.com/v2.2"

  def get_all_documents(company_id):
      documents = []
      page = 1

      while True:
          response = requests.get(
              f"{BASE_URL}/document/company/{company_id}",
              headers={"X-API-Key": API_KEY},
              params={"page": page},
          )
          data = response.json()
          documents.extend(data["documents"])

          if not data["hasNext"]:
              break
          page += 1

      return documents
  ```

  ```javascript JavaScript theme={null}
  async function getAllDocuments(companyId) {
    const documents = [];
    let page = 1;

    while (true) {
      const response = await fetch(
        `https://external.nectarclimate.com/v2.2/document/company/${companyId}?page=${page}`,
        { headers: { 'X-API-Key': 'YOUR_SECRET_KEY' } }
      );
      const data = await response.json();
      documents.push(...data.documents);

      if (!data.hasNext) break;
      page++;
    }

    return documents;
  }
  ```
</CodeGroup>

## Tips

* Check `totalPages` on the first response to estimate total requests needed.
* If you request a page beyond the last page, the API returns the last valid page instead of an error.
* All list endpoints use this same envelope format — documents, usage data, meters, and connections.

## Next steps

<CardGroup cols={2}>
  <Card title="Filtering and query parameters" icon="filter" href="/developer-guide/filtering">
    Narrow results by date, site, commodity, and more
  </Card>

  <Card title="API getting started" icon="rocket" href="/developer-guide/getting-started">
    Authentication and first request
  </Card>
</CardGroup>