Pagination and sorting

Cursors#

Every list is cursor-paginated. Pass limit, then pass the next_cursor of each page to get the next one, until has_more is false.

{
  "data": [
    "…"
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJrIjoiNDIuNSIsImkiOiJjYXBfMDFrNS4uLiJ9",
    "limit": 50
  },
  "meta": {
    "request_id": "req_…",
    "comparability": "best_effort",
    "warnings": []
  }
}

• Cursors are opaque and keyed on the sort value plus a tiebreaker id, so page 2,000 costs what page 1 costs and rows sharing a sort value survive a page boundary.
• A cursor is only meaningful with the query that produced it: keep the filters and the sort unchanged while you page. A cursor the API cannot read is 400 invalid_cursor, never a silent restart at page one.

async function* all(path, params, key) {
  let cursor;
  do {
    const url = new URL(`https://api.gridcapacityapi.com${path}`);
    url.search = new URLSearchParams({ ...params, ...(cursor ? { cursor } : {}) }).toString();
    const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
    if (!res.ok) throw new Error((await res.json()).error.code);
    const page = await res.json();
    yield* page.data;
    cursor = page.pagination.has_more ? page.pagination.next_cursor : null;
  } while (cursor);
}

Page sizes#

Pass limit explicitly, up to your plan’s maximum. A limit above it is 400 invalid_parameter naming the maximum — not a quietly truncated page.

Sorting#

sort takes one key from an allow-list; a leading - sorts descending. Anything else is 400 invalid_parameter.

Sorting by capacity across different units orders numbers that do not measure the same thing; filter by unit first, or use comparability=strict.