Pagination

Most EnergyCAP list endpoints return paginated responses. Instead of returning every record at once, the API splits results into pages that you iterate through.

How It Works

When you call a paginated endpoint, the response body contains the current page of data and the response headers include pagination metadata:

Query Parameters

Control pagination with these query parameters:

Example: Iterating Through Pages

First request — no pagination parameters needed:

curl -X GET "https://app.energycap.com/api/v3/meter" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response headers:

PageNumber: 1
PageSize: 250
TotalNumberOfRecords: 1100
TotalPages: 5

This tells you there are 1,100 meters across 5 pages. Request the next page by adding pageNumber:

curl -X GET "https://app.energycap.com/api/v3/meter?pageNumber=2" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Continue incrementing pageNumber until it equals TotalPages. When they match, you have all the data.

Pseudocode

page = 1
totalPages = 1

while page <= totalPages:
    response = GET /api/v3/meter?pageNumber={page}&pageSize=500
    totalPages = response.headers["TotalPages"]
    process(response.body)
    page = page + 1

Choosing a Page Size

Combine pagination with field reduction and filters to reduce both the number of pages and the size of each response.

Parallel Requests

Once you know the total number of pages from the first response, you can fetch multiple pages concurrently. For example, if TotalPages is 10, you can fire off requests for pages 2 through 10 in parallel rather than sequentially.

Guidelines:

• Limit to 5 concurrent requests to avoid hitting rate limits
• Each request should target a different pageNumber
• Ensure your processing logic handles out-of-order responses

Using the C# SDK

Pagination metadata is returned in response headers, so you must use the WithHttpMessagesAsync variants to access it:

// Use WithHttpMessagesAsync to get both body and headers
var response = await client.GetAccountsWithHttpMessagesAsync(
    filter, pageNumber, pageSize);

// Response body — same as GetAccountsAsync()
var accounts = response.Body;

// Pagination headers
var headers = response.Headers;
int currentPage = headers.PageNumber.Value;
int totalPages = headers.TotalPages.Value;
int totalRecords = headers.TotalNumberOfRecords.Value;

// Page through all results
while (currentPage < totalPages)
{
    currentPage++;
    var nextResponse = await client.GetAccountsWithHttpMessagesAsync(
        filter, currentPage, pageSize);
    accounts.AddRange(nextResponse.Body);
}