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

# Pagination

> How search pagination works and how to page through results without extra charges

# 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 <Tooltip tip="A search session is created by POST /v1/search. It holds a fixed set of results determined by the limit parameter.">search session</Tooltip>. 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 <Tooltip tip="Credits are the billing unit for API usage. 1 credit = \$0.01.">credits</Tooltip> 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

<CodeGroup>
  ```typescript SDK theme={null}
  import Influship from 'influship';

  const client = new Influship();

  // Create the search session (billed)
  const first = await client.search.create({
    query: 'travel content creators',
    limit: 20,
  });

  console.log(`Got ${first.data.length} results, has_more: ${first.has_more}`);

  // Paginate through remaining results (free)
  let cursor = first.next_cursor;
  while (cursor) {
    const page = await client.search.retrieve(first.search_id, {
      cursor,
    });
    console.log(`Got ${page.data.length} more results`);
    cursor = page.next_cursor;
  }
  ```

  ```bash cURL theme={null}
  # Step 1: Create search session (billed)
  curl -X POST https://api.influship.com/v1/search \
    -H 'X-API-Key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{"query": "travel content creators", "limit": 20}'

  # Step 2: Paginate (free) — use search_id and next_cursor from the response
  curl "https://api.influship.com/v1/search/SEARCH_ID?cursor=NEXT_CURSOR" \
    -H 'X-API-Key: YOUR_API_KEY'
  ```
</CodeGroup>

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

## 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](/concepts/pricing) for the full cost breakdown.