Getting Started

Pagination and Bulk Data

How to fetch large time ranges efficiently using cursor-based pagination with from, to, and limit.

How pagination works

Every time-series endpoint accepts three query parameters that control the window of data returned:

Results are sorted by timestamp descending (newest first). If count in the response equals your limit, there is likely more data. To fetch the next page, set to to the oldest timestamp in your current batch and repeat.

How much data is there?

Snapshot endpoints (one row per coin per 10-minute cycle):

Per-option endpoints (greeks/snapshot, liquidity/options) multiply by ~2,500 options per cycle. A single 10-minute snapshot is one request. Historical per-option data requires pagination.

Python: fetch 30 days of vol/surface

import requests
import time

API_KEY = "clg_alpha_YOUR_KEY"
BASE    = "https://api.cayolargo.fi"
COIN    = "BTC"

# 30 days of 10-min data = 4,320 rows
params = {
    "coin":  COIN,
    "from":  "2026-02-10T00:00:00Z",
    "to":    "2026-03-12T00:00:00Z",
    "limit": 5000,
}

all_rows = []

while True:
    r = requests.get(
        f"{BASE}/v1/vol/surface",
        params=params,
        headers={"X-API-Key": API_KEY},
    )
    data = r.json()
    batch = data["results"]
    all_rows.extend(batch)

    # If we got fewer rows than limit, we have everything
    if data["count"] < params["limit"]:
        break

    # Move the cursor: set "to" to the oldest timestamp in this batch
    oldest = batch[-1]["timestamp"]
    params["to"] = oldest

    # Be polite
    time.sleep(0.5)

print(f"Fetched {len(all_rows)} rows")

Tips

See Tiers & Limits for per-tier request and row limits, and Response Format for the JSON envelope structure.