Pagination (cursors)

Every list endpoint — GET /v2/forms, GET /v2/submissions, and others — returns results one page at a time using cursor-based pagination. This guide shows you how to follow the pages until you've read everything.

New term — cursor: an opaque token that marks your place in a result set. You don't read or construct it — you just pass back exactly what InsurGrid gave you to get the next page.

How it works

Two query params control paging:

Param	Type	Meaning	Default
limit	integer	How many results per page. 1–100.	25
cursor	string	Opaque page marker from the previous response's next_cursor. Omit on the first call.	—

Every response carries next_cursor:

{
  "data": [ /* … up to `limit` items … */ ],
  "next_cursor": "eyJpZCI6NTUyMzF9"
}

• If next_cursor is a string, there's more — pass it as cursor on your next call.

• If next_cursor is null, you've reached the end.

Treat the cursor value as opaque. Don't decode it, store it long-term, or construct one yourself — InsurGrid may change its internal format at any time.

Fetch every page

Node:

// client.js — run with: node client.js
async function listAllForms(token) {
  const all = [];
  let cursor;

  do {
    const url = new URL("https://api.insurgrid.com/v2/forms");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${token}` },
    });
    const page = await res.json();

    all.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);

  return all;
}

Python:

# client.py
import requests

def list_all_forms(token: str) -> list[dict]:
    all_forms = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        resp = requests.get(
            "https://api.insurgrid.com/v2/forms",
            headers={"Authorization": f"Bearer {token}"},
            params=params,
        )
        page = resp.json()

        all_forms.extend(page["data"])
        cursor = page.get("next_cursor")
        if not cursor:
            break

    return all_forms

Which endpoints paginate

Any endpoint that returns a data array — for example GET /v2/forms and GET /v2/submissions — uses this same shape. Learn it once and it works everywhere.

Related

• Errors & status codes

• Rate limits

• Forms API reference

• Submissions API reference