Page size
count sets how many results a page holds. Each endpoint has its own maximum
and default, shown on its reference page. On endpoints charged per request, the
default is the maximum, so leaving count out gets the fullest page one request
can return; on endpoints charged per result, it is smaller, usually 10.
A page comes back with count results until the list runs out. A page can still
hold fewer than you asked for, so decide whether to keep paging from the next
page’s cursor or position, not from how many results came back.
Lists paged by cursor
Most lists are paged by cursor. Each response carries anextCursor:
- Leave out
cursorto get the first page. - Pass the
nextCursorfrom the response ascursorto get the next page. - Stop once
nextCursorisnull.
cursor. A cursor
continues the list it came from, so it is refused by a request for another
account, query or sort order.
/x/get-tweet-detail returns a tweet with its first replies and a
nextCursor; pass that cursor to /x/get-tweet-replies, with the same tweet
and sort order, to load the rest.
Lists paged by position
Some lists are paged by position instead.start is the number of results to
skip, starting at 0.
- Lists that return
nextStart: pass it asstartfor the next page, and stop once it isnull. The next page can start past the results you received, since a platform can leave some out of a page. - The two lists whose response is the array of results itself: add the number
of results you got to
startfor the next page, and stop once a page comes back empty.
Some searches only reach a fixed depth, so
start has a maximum; it is shown
on the endpoint’s reference page.
Lists that are not paginated
These endpoints return a list in a single response, with nocursor or start.
Sending the same request again returns the same kind of list, not a next page.
To reach other results, narrow or change the request instead.
Fetch pages promptly
Page through a list in one sitting, fetching each page soon after the last:- A
nextCursorthat starts withbridgly_page_stays valid for a day. After that, the request is refused with a 400 asking you to start again from the first page. - Lists change while you page through them: an account posts again, gains followers, or a search ranks new results. The longer you wait between pages, the more likely a result comes back twice or is missed.
Results that repeat or are missing
Pages come from the platform as it is at the moment you ask, so a list is not a fixed snapshot, even when you page through it quickly:- Ranked lists reorder between requests. Searches, comment threads and feeds sorted by relevance can rank results differently from one page to the next, so a result can appear on two pages, and another can be skipped.
- Fast-moving lists shift. On a list that grows by the second, such as a popular account’s followers or a trending hashtag, new entries push older ones further down, and the next page can start with results you have already received.
- Some platforms repeat results on their own. A conversation, for example, can show its first post again for context when it continues on the next page.
- Platforms hide some results. Content a platform filters out, such as replies it flags as spam or offensive, is not returned, so a total like a reply count can be higher than the number of results you can page through.
Credits
Every page is a separate request and is charged on its own. On endpoints priced per result, a page costs one result’s price for each result it returns, so smaller pages cost the same in total; on endpoints priced per request, each page costs one request. Each endpoint’s price is shown on its reference page.In the SDK
The SDK can fetch the pages for you: passpagination: true to any list
function and it returns every page in one response. See
Automatic pagination.