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

> Read saved search results for free and paginate other API resources.

Search delivers results when you create it. You can then read the saved result set again without another search charge.

| Before you start | Details |
| - | - |
| Auth | Use the credential that owns the search/resource |
| Resource | Saved searches, posts, lookalikes, live pages |
| Cost | Saved search reads are free; other pages use endpoint pricing |
| Limits | Search POST/GET limit: 1–100; other resource limits vary |

## Initial search delivery

`POST /v1/search` accepts a `limit` from 1–100 (default 25), which caps the number of creators delivered and billed. It returns those results in `data`, their count in `total`, and a `search_id` for later retrieval.

The initial response delivers the visible result set together, with `has_more: false` and no next cursor. You do not need to fetch more pages to collect that response's results.

## Read a saved search

`GET /v1/search/{search_id}` reads the same result set. Its `limit` controls the page size (1–100, default 25). Start without a cursor, then pass `next_cursor` unchanged while `has_more` is true.

These reads are free. They do not run a new search or add creators beyond the original POST limit. Keep reads under the credential that created the search.

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

  const client = new Influship({ maxRetries: 0 });

  // Create and pay for discovery once. The results are already in data.
  const search = await client.search.create({
    query: 'travel content creators',
    limit: 20,
  });
  console.log(`Delivered ${search.data.length} creators`);

  // Later, reread that saved set in pages of five. Do not append these to
  // search.data: they are the same creators, not additional discovery results.
  let page = await client.search.retrieve(search.search_id, { limit: 5 });
  while (true) {
    console.log(page.data);
    if (!page.has_more || !page.next_cursor) break;
    page = await client.search.retrieve(search.search_id, {
      limit: 5,
      cursor: page.next_cursor,
    });
  }
  ```

  ```bash cURL theme={null}
  # Reread a search using the search_id from your POST response.
  curl "https://api.influship.com/v1/search/SEARCH_ID?limit=5" \
    -H 'X-API-Key: YOUR_API_KEY'

  # Only continue when has_more is true, using the returned next_cursor.
  curl --get "https://api.influship.com/v1/search/SEARCH_ID" \
    -H 'X-API-Key: YOUR_API_KEY' \
    --data-urlencode 'limit=5' \
    --data-urlencode 'cursor=NEXT_CURSOR'
  ```
</CodeGroup>

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

## Other paginated resources

Free rereads apply to saved search results. Other endpoints charge according to their own result or page pricing. Keep the same resource, filters, and ordering when passing an opaque cursor.

* [Lookalikes](/concepts/lookalikes) charge per creator delivered.
* [TikTok live data](/guides/tiktok-live-data) charges per source page for paginated operations.
* [YouTube live data](/guides/youtube-live-data) charges per fetched search page.

See [Pricing](/concepts/pricing) for each endpoint's cost and the [API Reference](/api-reference) for its cursor fields.


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