Skip to main content
Endpoints that return a list send back one page of results at a time. Every list pages with the same few fields, so once you have paged through one, you can page through all of them.

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 a nextCursor:
  1. Leave out cursor to get the first page.
  2. Pass the nextCursor from the response as cursor to get the next page.
  3. Stop once nextCursor is null.
Send the same request fields with every page and change only 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 as start for the next page, and stop once it is null. 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 start for 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 no cursor 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 nextCursor that starts with bridgly_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.
If your use needs each result once, deduplicate on the result’s ID as you collect pages.

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: pass pagination: true to any list function and it returns every page in one response. See Automatic pagination.