Pagination & Response Limits

The API supports two pagination methods:

Page-based pagination (limited to 10,000 results)

Use page and pageSize parameters for simple pagination:

{
  "queryType": "getItemsQuery",
  "queryParams": {
    "page": 1,
    "pageSize": 100
  }
}

Limitation: Due to database constraints, page-based pagination is limited to the first 10,000 results. Requesting a page beyond this limit (e.g., page 101 with pageSize 100) will return an error.

Cursor-based pagination (unlimited)

For datasets larger than 10,000 results, use cursor-based pagination:

1. First request: Omit the cursor parameter
2. Subsequent requests: Use the sort value from the last item of the previous response as the cursor

First request:

{
  "queryType": "getItemsQuery",
  "queryParams": {
    "pageSize": 1000,
    "sortBy": { "field": "queueDate", "direction": "desc" },
    "source": ["projectName", "totalMw"]
  }
}

Response (each item includes a sort array):

{
  "total": 73600,
  "data": [
    { "id": "abc123", "projectName": "...", "sort": [1706140800000, "abc123"] },
    { "id": "xyz789", "projectName": "...", "sort": [1705968000000, "xyz789"] }
  ]
}

Next request (use the sort from the last item as cursor):

{
  "queryType": "getItemsQuery",
  "queryParams": {
    "pageSize": 1000,
    "cursor": [1705968000000, "xyz789"],
    "sortBy": { "field": "queueDate", "direction": "desc" },
    "source": ["projectName", "totalMw"]
  }
}

Repeat until you've retrieved all results. This approach allows you to paginate through unlimited results.

Note: Cursor-based pagination is forward-only. You cannot jump to arbitrary pages, but you can iterate through the entire dataset.

Response size limits

Each response is capped at approximately 6 MB. If a request would return more data than that - most often a large pageSize combined with large fields such as body (the full record text) - the API responds with 413 Payload Too Large instead of the results.

To keep responses within the limit:

• Request only the fields you need using source. Omitting large fields such as body dramatically reduces response size.
• Use a smaller pageSize, paging through your results with cursor-based pagination.

{
  "queryType": "getItemsQuery",
  "queryParams": {
    "pageSize": 500,
    "source": ["headline", "publishedDate", "state", "organizations"]
  }
}