Paging through results

Search and list endpoints return results a page at a time. This guide shows how to read the next page, and the next, until you have what you need, without paying for more than you use.

Is there more?

Each page tells you whether more follow, usually as has_more. Where it sits depends on the endpoint: in pagination for some, in summary for others. The fields table on the endpoint's reference page shows where, and its input table shows how to ask for the next page.

Every page is a call of its own, charged at the endpoint's price. Stop when you have enough: there is no need to read to the end.

With a cursor

Most list endpoints hand back a next_cursor. Send it as cursor, with the same other input, to get the next page:

"pagination": {  "has_more": true,  "next_cursor": "eyJwcm9ncmVzcyI6…",  "retrieved_total": 25}

{  "capability": "pinterest.board-pins.list",  "input": {    "url": "https://www.pinterest.com/PinterestPredicts/gimme-gummy/",    "limit": 25,    "cursor": "eyJwcm9ncmVzcyI6…"  }}

Copy the cursor exactly as it came, and don't build or change one yourself. Keep every other input the same, or the cursor may not fit.

This reads a whole Pinterest board, at most four pages:

import osimport requestsAPI = "https://data.upscrape.com"HEADERS = {"Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}", "Prefer": "wait=30"}def call(capability, input):    job = requests.post(f"{API}/execute", headers=HEADERS,                        json={"capability": capability, "input": input}).json()    if job.get("state") != "completed":        raise RuntimeError(job.get("error", {}).get("code", job.get("state")))    return job["results"][0]["data"]board = "https://www.pinterest.com/PinterestPredicts/gimme-gummy/"pins, cursor = [], Nonefor _ in range(4):  # at most 4 pages: 100 pins, 4 credits    input = {"url": board, "limit": 25}    if cursor:        input["cursor"] = cursor    data = call("pinterest.board-pins.list", input)    pins += data["items"]    if not data["pagination"]["has_more"]:        break    cursor = data["pagination"]["next_cursor"]print(len(pins), "pins")

It printed 84 pins when we ran it on 16 October 2026: the board's last page said has_more: false and the loop stopped there.

With a page number

Some endpoints take a page number instead: send page: 2, then 3, while has_more is true. A few take an offset, the number of results to skip.

Several pages in one call

Some endpoints take max_pages and fetch that many pages in one call. That saves round trips, but each page still has a price: such an endpoint shows a price range on its reference page, and you pay for the pages it fetched. Set max_credits if you want a hard cap.

When a list ends early

A platform can report more results than it actually shows. Endpoints that know this end the list with has_more: false and outcome.status: "incomplete", so a loop that follows has_more always finishes. Read outcome when you need to know whether you got everything.