Pagination
The Search endpoint supports three pagination methods. Choose the one that best fits your use case.
Page-based PaginationSimplest
Use the page parameter (1-indexed) for traditional pagination:
Request
{
"query": "coffee shop",
"page": 2,
"limit": 25
}Response
{
"data": [...],
"meta": {
"total": 847,
"limit": 25,
"page": 2,
"total_pages": 34,
"has_more": true
}
}Page limit
Page-based pagination is limited to 10,000 total results (page × limit ≤ 10,000) due to Elasticsearch constraints.
Cursor-based PaginationRecommended
Use the next_cursor value from the response to fetch the next page. This is the most efficient method for large datasets:
Request
{
"query": "coffee shop",
"cursor": [0.95, 4.5, 234, "abc123"],
"limit": 25
}Response
{
"data": [...],
"meta": {
"total": 847,
"limit": 25,
"has_more": true,
"next_cursor": [0.92, 4.3, 189, "def456"]
}
}✓
No 10,000 limit — iterate through all results
✓
Consistent results — immune to data changes between pages
✓
Better performance — optimized for deep pagination
Offset-based Pagination
Use the offset parameter to skip a specific number of results:
Request
{
"query": "coffee shop",
"offset": 50,
"limit": 25
}Offset limit
Like page-based pagination, offset is limited to 10,000 results. Use cursor-based pagination for larger datasets.
Contacts Pagination
The Contacts endpoint uses cursor-based pagination. Pass the next_cursor string from the response as the cursor query parameter:
javascript
// First request
GET /api/v1/contacts?limit=25
// Response includes cursor
{
400">"data": [...],
400">"meta": {
400">"total": 150,
400">"limit": 25,
400">"has_more": true,
400">"next_cursor": 400">"2024-01-15T10:30:00Z,c1d2e3f4-..."
}
}
// Next page
GET /api/v1/contacts?limit=25&cursor=2024-01-15T10:30:00Z,c1d2e3f4-...Comparison
| Method | Max Results | Best For |
|---|---|---|
| Page | 10,000 | Simple UIs with page numbers |
| Cursor | Unlimited | Large datasets, data exports |
| Offset | 10,000 | Random access, skip patterns |