Pagination
Search pagination works differently from most APIs. You pay once when you create a search, then paginate through results for free.How it works
POST /v1/search creates a . The limit parameter (1-100, default 25) sets the maximum number of results that session can ever return. You’re billed once at creation time: 25 base plus 2 per creator delivered.
The response includes three pagination fields:
search_id- identifies the session for follow-up requestshas_more- whether additional results are availablenext_cursor- pass this to fetch the next page
GET /v1/search/{search_id} fetches the next page using the cursor. This costs nothing — no additional credits are charged.
Pagination does not unlock more results beyond the original limit. If you searched with limit: 10, the session exposes at most 10 results total across all pages.
Posts pagination
GET /v1/posts uses stable keyset pagination rather than numeric offsets. Its limit is the page size, and each returned post is billed normally. When has_more is true, pass next_cursor into the next request with the same sort value.
Post cursors are tied to their ordering. A cursor created with sort=most_likes cannot be reused with sort=recent; the API returns 400 instead of restarting from the first page. This prevents duplicate or skipped posts when paginating changing datasets.
For sort=top_engagement, the ordering is (likes + comments) / views. Posts without measurable views are returned after posts with a calculated engagement rate.