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.

Walking backwards eventually reaches your tier's history floor. We do not refuse that request and we do not silently truncate it: the window is clamped to the floor and the response carries window_start with the oldest instant served, plus history_clamped: true. Stop your loop when you see it, or when count comes back below your limit. Both conditions mean the same thing, that there is nothing further back to fetch.

How much data is there?

Snapshot endpoints return one row per coin per cycle, so the row count depends on your tier's sampling resolution, not just on the range. Core reads 4-hourly cycles, Pro hourly, Alpha every stored 10-minute cycle. One coin:

Per-option endpoints are the ones that actually need pagination. On /v1/greeks/snapshot a single BTC cycle is roughly 700 rows, and the six coins together are roughly 2,500. At Alpha's 10,000-row cap that is about 14 BTC cycles, so one full-size request covers a little over two hours of one coin. Plan historical backfills in days, not in single calls.

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": 10000,
}

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

    # We reached the history floor for this tier. Nothing older exists for us.
    if data.get("history_clamped"):
        print(f"history floor reached at {data['window_start']}")
        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.