Skip to main content
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, or meters).
Example (documents)
{
  "totalDocuments": 250,
  "perPage": 100,
  "totalPages": 3,
  "currentPage": 1,
  "hasNext": true,
  "hasPrevious": false,
  "documents": [
    { "id": "...", ... },
    { "id": "...", ... }
  ]
}
FieldTypeDescription
total*IntegerTotal number of records across all pages (e.g., totalDocuments, totalUsageData, totalMeters)
perPageIntegerNumber of records per page (fixed at 100)
totalPagesIntegerTotal number of pages
currentPageIntegerCurrent page number (1-indexed)
hasNextBooleanWhether a next page exists
hasPreviousBooleanWhether a previous page exists
Items arrayArrayRecords for the current page (key name matches the endpoint: documents, usageData, or meters)

​
Query parameters

ParameterDefaultDescription
page1Page number (1-indexed)
Page size is fixed at 100 records per page for all endpoints and cannot be changed.

​
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

​
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, and meters.

​
Next steps

Filtering and query parameters

Narrow results by date, site, commodity, and more

API getting started

Authentication and first request