Skip to main content

Pagination

Available onProResearch

Routes that can return a lot of data return it in pages. The API uses three kinds of paging, and each route uses one of them. The kind is the same everywhere it appears, and the response always tells you whether there is more. Search is not paged: it returns the best limit results.

Offset paging: document text​

GET /documents/:id returns the text of a document in pieces of up to maxChars characters (default 12,000, at most 20,000). Pass nextOffset from one answer as offset in the next, until nextOffset is null.

async function readDocument(id) {
  let offset = 0;
  let text = '';
  while (offset !== null) {
    const res = await fetch(
      `https://api.readsira.com/rest/v2/documents/${id}?offset=${offset}&maxChars=20000`,
      { headers: { Authorization: `Bearer ${process.env.READSIRA_KEY}` } },
    );
    const { data } = await res.json();
    text += data.text;
    offset = data.nextOffset;
  }
  return text;
}

Also in the answer: totalChars (the full length) and truncated, which is true while more text remains.

Cursor paging: chunks, transcripts, projects​

A cursor is a bookmark that the API gives you. Do not build it yourself. Send it back unchanged.

RouteCursor you sendWhere the next one comes fromLimit
GET /documents/:id/chunkscursor (a number)nextCursorlimit, at most 100
GET /documents/:id/transcriptcursor (a string)nextCursorlimit, at most 500
GET /projectscursor (a string)nextCursorlimit, at most 50

The first call has no cursor. Keep calling with the last nextCursor until it is null or missing.

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20"

The answer has the page of projects and, when there is more, nextCursor (shortened here):

{
  "success": true,
  "data": {
    "projects": ["..."],
    "nextCursor": "VALUE_FROM_THE_ANSWER"
  }
}

The next page sends that value back as cursor:

curl -G "https://api.readsira.com/rest/v2/projects" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Page numbers: bookmarks and collections​

The older /api/v1/bookmarks and /api/v1/collections routes use page (from 1) and limit (at most 100, default 20). The bookmark list answers with bookmarks, total, page, limit and hasMore. Ask for the next page while hasMore is true.

curl -G "https://api.readsira.com/api/v1/bookmarks" \
  -H "Authorization: Bearer $READSIRA_KEY" \
  -d page=2 -d limit=100

Tips​

  • Every page is a request and counts toward your limits. Use the biggest limit the route allows when you need everything.
  • Pages are read one after the other. Do not send them in parallel with the same cursor.
  • Stop when the cursor or nextOffset is null, or when hasMore is false.
Last updated on