Pagination

Overview

Sayari API uses two pagination methods optimized for different endpoints:

Token Pagination

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

$
GET /entity/abc?relationships.next=qr7bvn2&relationships.limit=200

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.

$
GET /search/entity?q=China&offset=100&limit=50

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

1
{
2
    "offset": 20,
3
    "limit": 20,
4
    "next": true,
5
    "explored_count": 28354,
6
    "data": [...]
7
}

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