Pagination – Celper AI API Docs

Overview

The Celper AI API uses cursor-based pagination instead of offset-based pagination. Cursors are more efficient for large datasets because they maintain a stable position even when records are added or removed between requests.

Cursors are opaque strings — do not attempt to parse or construct them. Always use the cursor value returned by the API in your next request.

Parameters

Pagination Parameters

Parameter	Type	Required	Description
`limit`	`number`	Optional	Number of results to return per page. Min 1, max 200. Default: 50.
`cursor`	`string`	Optional	Pagination cursor from a previous response. Omit for the first request.

Response Shape

Every paginated response wraps the results in a standard envelope:


{
  "success": true,
  "data": [...],
  "pagination": {
    "cursor": "eyJjcm...",
    "hasMore": true
  }
}

Field	Description
`data`	Array of results for the current page.
`pagination.cursor`	Opaque string to pass as the `cursor` parameter in the next request. `null` when `hasMore` is `false`.
`pagination.hasMore`	`true` if there are more results beyond this page, `false` if this is the last page.

Pagination Flow

Send first request

Send a request without a cursor parameter. Optionally set limit to control page size.

Check for more results

If pagination.hasMore is true, there are more results to fetch.

Pass cursor to next request

Take the pagination.cursor value from the response and pass it as the cursor query parameter in your next request.

Repeat until done

Continue fetching pages until pagination.hasMore is false.

Complete Example

Paginate through all candidates in a job position:

#!/bin/bash
API_KEY="celp_your_api_key_here"
JOB_ID="pos_abc123"
BASE_URL="https://api.celper.ai/v1/candidates"

CURSOR=""
HAS_MORE=true
PAGE=1

while [ "$HAS_MORE" = true ]; do
if [ -z "$CURSOR" ]; then
  URL="${BASE_URL}?jobPositionId=${JOB_ID}&limit=50"
else
  URL="${BASE_URL}?jobPositionId=${JOB_ID}&limit=50&cursor=${CURSOR}"
fi

RESPONSE=$(curl -s "$URL"   -H "X-API-Key: ${API_KEY}")

echo "Page ${PAGE}:"
echo "$RESPONSE" | python3 -m json.tool

CURSOR=$(echo "$RESPONSE" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(data.get('pagination', {}).get('cursor', ''))
")

HAS_MORE=$(echo "$RESPONSE" | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(str(data.get('pagination', {}).get('hasMore', False)).lower())
")

PAGE=$((PAGE + 1))
done

echo "All pages fetched."