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.
Code example
Key things to understand
| Concept | Detail |
|---|---|
limit is a billing cap | It controls the max results for the entire session, not the page size. |
| Page size is fixed | Results are returned in chunks, typically 10 at a time. |
has_more is the stop signal | Once it returns false, there are no more results to fetch. |
| Free pagination is rate-limited | Follow-up requests are free but still subject to light rate limiting to prevent abuse. |