Pagination

Some endpoints return a list of items, a page at a time. Every list endpoint pages the same way, so you write the loop once.

The response

A successful list response has three keys: data, an array of items in the resource's shared schema; page, which says whether more items exist and how to get them; and meta, as on every response:

{
  "data": [
    "…"
  ],
  "page": {
    "has_more": true,
    "next_cursor": "…",
    "next_cursor_expires_at": "…"
  },
  "meta": {
    "request_id": "…",
    "platform": "…",
    "source": "…",
    "is_cached": true,
    "credits_charged": 0,
    "latency_ms": 0,
    "fetched_at": "…"
  }
}

There are no totals: platforms don't report them reliably, and counting would cost extra requests.

Parameters

Every list endpoint accepts these on top of its own parameters and the common options:

Getting the next page

1. Send the first request without cursor.
2. If page.has_more is true, send the same request again with cursor set to page.next_cursor from the previous response.
3. Stop when page.has_more is false.

Keep every other parameter the same: only limit and the common options such as max_age may change between pages. A page can be empty and still have page.has_more set to true; keep going.

const items = [];
let cursor = null;
do {
  const params = new URLSearchParams({ ...yourParams, ...(cursor ? { cursor: cursor } : {}) });
  const res = await fetch(`https://staging.socialtap.dev/v1/<platform>/<endpoint>?${params}`, {
    headers: { "x-api-key": process.env.SOCIALTAP_API_KEY },
  });
  if (!res.ok) throw new Error((await res.json()).error.code);
  const body = await res.json();
  items.push(...body.data);
  cursor = body.page.next_cursor;
} while (cursor);

Cursors

Cursors are opaque and short-lived: don't parse, build or store them. Each one stops working at page.next_cursor_expires_at. A cursor that is malformed, expired, from another endpoint, or sent with different parameters fails with invalid_cursor (HTTP 400) and costs nothing; repeat the original request without a cursor to start again.

Order and page size

Each list endpoint states the order of its items and its page size: the default and the largest limit it accepts (larger values are reduced). One request reads one page from the platform, so a list of N items takes about N ÷ page size requests when you leave limit out.

Pricing

A list endpoint's price is per page: every successful page costs the same, however many items it holds and whatever limit you send (a smaller limit reduces the payload, not the price). Empty pages are charged like any other successful page. Failed requests, including invalid_cursor, are free, and so are pages served from the cache. See Credits and caching.

A smaller limit costs more

A limit below the page size does not split one charge into parts. The request returns the first limit items of a platform page, and the next request, with its cursor, serves the rest of that same platform page: it is fetched again and charged as a page each time. Walking a page in parts therefore costs one page per part, and because the platform page is read again for every part, items can shift between those requests if the platform adds or removes items in the meantime, so an item may repeat or be skipped.

Omitting limit is the cheapest way to walk a list: every request returns a full page, and each platform page is read and charged once. Use a smaller limit only when you need fewer items than a page holds and will stop there.

Errors

On top of the errors every endpoint can return, list endpoints have these:

A rejected cursor costs nothing; repeat the original request without cursor to start again.