Skip to main content

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 requests
  • has_more - whether additional results are available
  • next_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.

Code example

Key things to understand

Implementation advice

Start with a small limit (5-10) while prototyping. Increase once you know how your UI consumes results. Larger limits cost more and results past the top 15-20 tend to be lower relevance.

Further reading

See Pricing for the full cost breakdown.