Pagination

All list endpoints in the Sybill API use cursor-based pagination. This provides stable, efficient paging regardless of how large the result set is or how frequently data changes.

How it works

Every list endpoint (/v1/conversations, /v1/deals, etc.) returns a pagination object alongside the results:

{
  "conversations": [ ... ],
  "pagination": {
    "nextCursor": "eyJzZWFyY2hBZnRlciI6...",
    "hasMore": true
  }
}
FieldTypeDescription
nextCursorstring or nullAn opaque token pointing to the next page. null when there are no more results.
hasMorebooleantrue if additional pages exist beyond the current one.

Fetching the next page

Pass the nextCursor value as the cursor query parameter in your next request:

# First request
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.sybill.ai/v1/conversations?limit=10"

# Next page
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.sybill.ai/v1/conversations?limit=10&cursor=eyJzZWFyY2hBZnRlciI6..."
Cursor stability

Cursors are opaque strings. Do not parse, decode, or construct them — always use the exact value returned by the API. Cursors remain valid as long as the underlying data hasn't been deleted.

Controlling page size

Use the limit parameter to control how many results are returned per page:

ParameterTypeDefaultRange
limitinteger201–50

Combining with filters

Filters and pagination work together. Apply any filters on the first request, then paginate through the filtered result set using the returned cursor. You do not need to repeat filters on subsequent pages — the cursor encodes the original query context.

# First page: external meetings after Jan 1
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.sybill.ai/v1/conversations?type=EXTERNAL&startedAfter=2024-01-01T00:00:00Z&limit=20"

# Second page: just pass the cursor (no need to repeat filters)
curl -H "Authorization: Bearer sk_live_YOUR_KEY" \
  "https://api.sybill.ai/v1/conversations?cursor=eyJ..."

Full iteration example

import requests

API_KEY = "sk_live_YOUR_KEY"
BASE = "https://api.sybill.ai/v1/conversations"
headers = {"Authorization": f"Bearer {API_KEY}"}

cursor = None
all_conversations = []

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

    resp = requests.get(BASE, headers=headers, params=params)
    resp.raise_for_status()
    data = resp.json()

    all_conversations.extend(data["conversations"])

    if not data["pagination"]["hasMore"]:
        break
    cursor = data["pagination"]["nextCursor"]

print(f"Fetched {len(all_conversations)} conversations")

Paginated endpoints

The following endpoints support cursor-based pagination:

💬
List Conversations

GET /v1/conversations

🤝
List Deals

GET /v1/deals

Best practices