Pagination

Overview

The Solatis API uses cursor-based and offset-based pagination for large result sets.

Cursor-Based Pagination (Recommended)

Cursor-based pagination is more efficient for large datasets:

curl "https://api.solatis.team/v1/documents?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [
    { "id": "doc123", "title": "Document 1" },
    { "id": "doc124", "title": "Document 2" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImRvYzEyNSJ9",
    "has_more": true,
    "total_count": 5000
  }
}

Get Next Page

curl "https://api.solatis.team/v1/documents?limit=10&cursor=eyJpZCI6ImRvYzEyNSJ9" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Default	Max
limit	integer	20	100
cursor	string	(first page)	-

Offset-Based Pagination

For simple cases, use offset pagination:

curl "https://api.solatis.team/v1/documents?offset=0&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total_count": 5000
  }
}

Get Next Page

curl "https://api.solatis.team/v1/documents?offset=10&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Parameter	Type	Default	Max
offset	integer	0	-
limit	integer	20	100

Best Practices

Use Cursor Pagination

# Good: Cursor pagination
cursor = None
while True:
    response = api.documents.list(cursor=cursor, limit=100)
    process(response['data'])

    if not response['pagination']['has_more']:
        break

    cursor = response['pagination']['next_cursor']

Avoid Large Offsets

# Bad: Offset pagination with large offset
response = api.documents.list(offset=10000, limit=10)

# Good: Cursor pagination instead
cursor = get_stored_cursor_at_page_100()
response = api.documents.list(cursor=cursor, limit=10)

Sorting & Filtering

Combine pagination with sorting:

curl "https://api.solatis.team/v1/documents?limit=10&sort=created_at&sort_dir=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameter	Options
sort	created_at, updated_at, name
sort_dir	asc, desc

Examples

Get All Documents (Python)

import requests

def get_all_documents(api_key):
    headers = {"Authorization": f"Bearer {api_key}"}
    all_docs = []
    cursor = None

    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            "https://api.solatis.team/v1/documents",
            headers=headers,
            params=params
        ).json()

        all_docs.extend(response["data"])

        if not response["pagination"]["has_more"]:
            break

        cursor = response["pagination"]["next_cursor"]

    return all_docs

Paginate Results (JavaScript)

async function getAllDocuments(apiKey) {
  const headers = { Authorization: `Bearer ${apiKey}` };
  const allDocs = [];
  let cursor = null;

  while (true) {
    const params = new URLSearchParams({ limit: 100 });
    if (cursor) params.append("cursor", cursor);

    const response = await fetch(
      `https://api.solatis.team/v1/documents?${params}`,
      { headers }
    ).then(r => r.json());

    allDocs.push(...response.data);

    if (!response.pagination.has_more) break;
    cursor = response.pagination.next_cursor;
  }

  return allDocs;
}

Performance Tips

1. Use limit=100 (maximum) for fewer API calls
2. Use cursor pagination for reliable pagination
3. Store cursors temporarily to resume if interrupted
4. Avoid repeated full scans - use timestamps instead
5. Cache results when reasonable

Troubleshooting

Cursor Invalid

{
  "error": "invalid_cursor",
  "message": "The pagination cursor has expired"
}

Solution: Start from beginning with no cursor

Offset Too Large

{
  "error": "offset_out_of_range",
  "message": "Offset exceeds total items"
}

Solution: Check total_count and adjust offset

Reference

See API Documentation for all endpoints with pagination support.