Key Concepts

Pagination

Navigate large datasets efficiently with token and offset pagination

Overview

Sayari API uses two pagination methods optimized for different endpoints:

Token Pagination

Entity endpoints with dynamic content

Offset Pagination

Search, records, and traversals

Token Pagination

Used for entity endpoints (/entity/:id) where result size is unpredictable.

Request
$GET /entity/abc?relationships.next=qr7bvn2&relationships.limit=200
Response
1{
2    "relationships": {
3        "next": "w98vmfd",
4        "prev": "myvc64l", 
5        "limit": 200,
6        "size": { "count": 1201, "qualifier": "eq" },
7        "data": [...]
8    },
9    "referenced_by": {
10        "next": "84ct7eb",
11        "limit": 100,
12        "size": { "count": 300, "qualifier": "eq" },
13        "data": [...]
14    }
15}

Parameters:

  • next/prev: String tokens for navigation
  • limit: Items per page (default: 100)

Offset Pagination

Used for search, records, and traversals with bounded results.

Request
$GET /search/entity?q=China&offset=100&limit=50
Response
1{
2    "offset": 100,
3    "limit": 50,
4    "next": true,
5    "size": { "count": 10000, "qualifier": "gte" },
6    "data": [...]
7}

Parameters:

  • offset: Results to skip (default: 0)
  • limit: Max items to return (default: 100)
  • next: Boolean indicating more results

Endpoint Examples

Records

$GET /record/123?references.offset=100&references.limit=100

Traversals

$GET /traversal/123?offset=20&max_depth=8
Traversal Response
1{
2    "offset": 20,
3    "limit": 20,
4    "next": true,
5    "explored_count": 28354,
6    "data": [...]
7}

Traversal responses include explored_count showing entities examined during graph traversal, but omit size values for performance.

Best Practices

  • Token pagination: Check for next/prev token presence
  • Offset pagination: Use next boolean to continue
  • Start with default limits, adjust based on performance needs
  • Avoid deep offsets for better performance