Pagination

Every list response uses the same envelope, so one paging helper works for all of them.

{
  "object": "list",
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "eyJvIjoyNSwiayI6InJldiJ9",
  "total_count": 418,
  "period": { "start": "2026-08-16", "end": "2026-09-14", "granularity": "day", "adjusted": false },
  "currency": "USD"
}

boolean

Whether another page exists. This — not an empty data array — is the loop condition.

string | null

Pass as cursor on the next request. Null on the last page.

integer | null

Approximate number of matches. Null when the result set is too large to count exactly. Useful for a progress estimate, never as a loop bound.

The loop

def paginate(session, url, body=None, params=None, page_size=100):
    cursor = None
    while True:
        if body is not None:
            payload = {**body, "limit": page_size, **({"cursor": cursor} if cursor else {})}
            page = session.post(url, json=payload, timeout=30).json()
        else:
            query = {**(params or {}), "limit": page_size, **({"cursor": cursor} if cursor else {})}
            page = session.get(url, params=query, timeout=30).json()

        yield from page["data"]

        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

Search endpoints take the cursor in the JSON body; GET endpoints take it as a query parameter. Otherwise the mechanics are identical.

Cursor rules

Cursors are opaque

The encoding is an implementation detail and will change. Never decode one, construct one, or infer an offset from it.

A cursor pins the query

Filters, sort, period and currency are captured when the first page is issued. Changing any of them invalidates the cursor — start a new search instead.

Cursors expire after 10 minutes

An expired cursor returns 400 with cursor_expired. If you are pausing between pages for longer than that, restart the search rather than holding the cursor.

Results are a snapshot

A cursor holds a consistent view for its lifetime, so an entity will not appear twice or vanish mid-scan because the data refreshed underneath you.

Page size

limit accepts 1 to 100 and defaults to 25. Use 100 for anything you are iterating. Credits are charged per row, not per request, so larger pages cost the same in credits and a quarter as much in rate limit budget.

The default of 25 exists so an exploratory call in a terminal returns something readable. In code there is essentially no reason not to pass 100.

Result depth

Searches page to a depth of 1,000 rows. Past that, has_more is false even if total_count is larger.

rows = list(paginate(session, ".../products/search", body=body))

if page["total_count"] and page["total_count"] > len(rows):
    log.info("truncated at %d of ~%d matches", len(rows), page["total_count"])

Detail and management endpoints — GET /shops/{id}/products, GET /lists/{id}/items, GET /jobs/{id}/results — have no such cap. The limit applies to ranked search, where depth beyond the top of the ranking is not meaningfully ordered. To go deeper: narrow the filters, shard by category or period, or use an export job. See Search.

What not to do

Do not loop on len(page["data"]) > 0. A page can legitimately come back short — filtered rows are removed after the page is assembled — while has_more is still true. Breaking on a short page truncates the result set silently.

# Wrong — stops early on a short page
while page["data"]:
    ...

# Right
while page["has_more"]:
    ...

Getting started

Core concepts

Workflows

Guides

Platform

Release notes

The loop

Cursor rules

Page size

Result depth

What not to do

​The loop

​Cursor rules

​Page size

​Result depth

​What not to do

The loop

Cursor rules

Page size

Result depth

What not to do