Paging
This page shows you how to read a long list of results one page at a time.
How does a list come back?
Section titled “How does a list come back?”An endpoint that returns a list, such as GET /v1/cases, does not send the whole list at once. It sends one page. Each page looks like this:
{ "data": [ ... ], "nextCursor": "EXAMPLE_CURSOR"}| Field | What it holds |
|---|---|
data |
The items on this page, in an array. |
nextCursor |
A cursor for the next page. It is null on the last page. |
The items in data are left out on this page, because the fields of each item are not decided yet. The API reference will list them.
How many items are on a page?
Section titled “How many items are on a page?”Send limit in the query to choose how many items you want on each page:
- If you do not send
limit, you get up to 50 items. - The most you can ask for is 200.
curl \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ "https://api.example.com/v1/cases?limit=200"Put the address in quotes when it has a ? or a &. Without quotes, your shell may change the address.
Example response:
{ "data": [ ... ], "nextCursor": "EXAMPLE_CURSOR"}How do I get the next page?
Section titled “How do I get the next page?”- Read the first page.
- If
nextCursorisnull, you have the whole list. Stop. - Otherwise, ask for the next page, and send the value of
nextCursorback in the query. - Repeat from step 2.
curl \ -H "Authorization: Bearer sdeu_key_EXAMPLE_ONLY_NOT_A_REAL_KEY" \ "https://api.example.com/v1/cases?limit=200&cursor=EXAMPLE_CURSOR"Some rules for cursors:
- A cursor is opaque. Do not read it, change it or build one yourself. Send it back exactly as you got it.
- Stop when
nextCursorisnull. That is how you know you have the last page. - There is no total count. The API does not tell you how many items the list has. To count them, read every page.
Read every page
Section titled “Read every page”These scripts read every case you can see, page by page. They use only what comes with the language, so you do not need to install anything. They read the key from an environment variable called SUPERDOCS_API_KEY.
Each script asks for 200 items on each page. Bigger pages mean fewer requests, so you stay further from the rate limits.
Python 3:
import jsonimport osimport urllib.parseimport urllib.request
API_KEY = os.environ["SUPERDOCS_API_KEY"]BASE_URL = "https://api.example.com"CURSOR_PARAM = "cursor" # A placeholder. The real name is not decided yet.
def get_all(path): items = [] cursor = None while True: query = {"limit": 200} if cursor is not None: query[CURSOR_PARAM] = cursor url = BASE_URL + path + "?" + urllib.parse.urlencode(query) request = urllib.request.Request(url, headers={"Authorization": "Bearer " + API_KEY}) with urllib.request.urlopen(request) as response: page = json.load(response) items.extend(page["data"]) cursor = page["nextCursor"] if cursor is None: return items
cases = get_all("/v1/cases")print(len(cases), "cases")JavaScript (Node.js 18 or later). Save it as read-all.mjs and run node read-all.mjs:
const API_KEY = process.env.SUPERDOCS_API_KEY;const BASE_URL = "https://api.example.com";const CURSOR_PARAM = "cursor"; // A placeholder. The real name is not decided yet.
async function getAll(path) { const items = []; let cursor = null; do { const url = new URL(BASE_URL + path); url.searchParams.set("limit", "200"); if (cursor !== null) url.searchParams.set(CURSOR_PARAM, cursor); const response = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } }); if (!response.ok) throw new Error(`Request failed with status ${response.status}`); const page = await response.json(); items.push(...page.data); cursor = page.nextCursor; } while (cursor !== null); return items;}
const cases = await getAll("/v1/cases");console.log(`${cases.length} cases`);If a request fails, both scripts stop with an error. To wait and try again after a 429, see Rate limits.