> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documentation.sayari.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documentation.sayari.com/_mcp/server.

# 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`**

```bash title="Request"
GET /entity/abc?relationships.next=qr7bvn2&relationships.limit=200
```

**`Response`**

```json title="Response" {3-4,10-11}
{
    "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`**

```bash title="Request"
GET /search/entity?q=China&offset=100&limit=50
```

**`Response`**

```json title="Response" {2-4}
{
    "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

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

### Traversals

```bash
GET /traversal/123?offset=20&max_depth=8
```

**`Traversal Response`**

```json title="Traversal Response" {3-4}
{
    "offset": 20,
    "limit": 20,
    "next": true,
    "explored_count": 28354,
    "data": [...]
}
```

> **Note**
>
> 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