Pagination

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).

Example (documents)

{
  "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

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

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;
}

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.

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Response envelope

Query parameters

Example: iterate all pages

Tips

Next steps

Filtering and query parameters

API getting started

​Response envelope

​Query parameters

​Example: iterate all pages

​Tips

​Next steps

Filtering and query parameters

API getting started

Response envelope

Query parameters

Example: iterate all pages

Tips

Next steps