Skip to content
Draft. The API described here is not released yet, and nothing on this site has been tested against it. Details may change.

Paging

This page shows you how to read a long list of results one page at a time.

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.

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.
Terminal window
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"
}
  1. Read the first page.
  2. If nextCursor is null, you have the whole list. Stop.
  3. Otherwise, ask for the next page, and send the value of nextCursor back in the query.
  4. Repeat from step 2.
Terminal window
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 nextCursor is null. 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.

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 json
import os
import urllib.parse
import 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.