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
{
    "relationships": {
        "next": "w98vmfd",
        "prev": "myvc64l", 
        "limit": 200,
        "size": { "count": 1201, "qualifier": "eq" },
        "data": [...]
    },
    "referenced_by": {
        "next": "84ct7eb",
        "limit": 100,
        "size": { "count": 300, "qualifier": "eq" },
        "data": [...]
    }
}

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
{
    "offset": 100,
    "limit": 50,
    "next": true,
    "size": { "count": 10000, "qualifier": "gte" },
    "data": [...]
}

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
{
    "offset": 20,
    "limit": 20,
    "next": true,
    "explored_count": 28354,
    "data": [...]
}

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