> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bridgly.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How list endpoints page through results with count, cursor and start, and which lists come back in a single response.

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.

```bash theme={"dark"}
curl https://api.bridgly.app/x/get-followers \
  -H "Authorization: Bearer bgly_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "44196397", "count": 20, "cursor": "<nextCursor from the previous page>" }'
```

| Platform | Endpoints |
| - | - |
| LinkedIn | `get-posts/from-profile`, `get-profile-comments`, `get-profile-reactions` |
| Reddit | `list-user-posts`, `list-user-comments`, `list-user-overview`, `list-subreddit-posts`, `list-subreddit-comments`, `search/all`, `search/communities`, `search/posts`, `search/users`, `search/comments` |
| X | `get-tweet-replies`, `search`, `search/users`, `get-user-tweets`, `get-user-replies`, `get-user-media`, `get-followers`, `get-following`, `get-tweet-retweeters`, `get-tweet-quotes` |
| GitHub | `list-repositories`, `list-starred`, `list-projects`, `search-repositories`, `search-issues`, `search-pull-requests`, `search-discussions`, `search-users` |
| Instagram | `user-posts`, `user-reels`, `tagged-posts`, `highlights`, `followers`, `following`, `post-comments`, `comment-replies`, `location-posts`, `search` |
| TikTok | `get-user-posts`, `get-user-liked-videos`, `get-user-reposts`, `get-user-followers`, `get-user-following`, `get-user-playlists`, `get-playlist-videos`, `get-video-comments`, `get-comment-replies`, `get-hashtag-videos`, `get-sound-videos`, `search-users`, `search-videos` |
| Meta Ads | `search` |

`/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.

| Platform | Endpoints | Next page |
| - | - | - |
| LinkedIn | `get-profile-experience`, `get-profile-education`, `get-profile-skills`, `get-profile-certifications`, `get-profile-publications`, `get-profile-volunteering`, `get-profile-honors`, `get-profile-interests/top-voices`, `get-profile-interests/companies`, `get-profile-interests/groups`, `get-profile-interests/newsletters`, `get-profile-interests/schools`, `get-posts/from-company`, `search/all`, `search/companies`, `search/courses`, `search/events`, `search/groups`, `search/jobs`, `search/posts`, `search/products`, `search/schools`, `search/services` | `nextStart` |
| LinkedIn | `get-activity-comments`, `get-post-reactions` | `start` + results returned |
| GitHub | `search-code`, `search-commits`, `search-topics` | `nextStart` |

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`.

| Endpoint | What comes back |
| - | - |
| `/instagram/stories` | Every story the profile has available, in one go. |
| `/instagram/highlight` | Every story in the highlight, in one go. |
| `/instagram/post-likers` | The likers we could get for the post, which is not always every liker. |
| `/instagram/search-users` | The accounts we could get for the query, which is not always every match. |
| `/tiktok/get-related-videos` | The related videos we could get for the video, which is not always all of them. |
| `/meta-ads/search-companies` | Up to 15 advertisers matching the search, best match first. |

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](https://docs.bridgly.app/sdk/functions.md#automatic-pagination).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.