Come scaricare dati storici

Cammina l'endpoint /rounds all'indietro con un cursor `until` per costruire un dataset Parquet / CSV / JSONL di ogni round in qualsiasi finestra. Questa guida copre paginazione, checkpoint, gestione rate-limit e uno script Python funzionante che puoi riprendere dopo un crash.

1. Modello del cursor

Niente cursor opaco — pagini sui timestamp ISO `finalized_at`. I round tornano dal più recente. Per camminare nello storico più vecchio, imposta `until` al finalized_at più vecchio visto finora: ogni call ritorna i successivi `limit` round con finalized_at < until. Ripeti finché una pagina torna vuota. (Il parametro speculare `since` fa l'opposto — finalized_at > since — per il polling in avanti dei delta live.)

2. Dimensione pagina

Il max di limit è 10000. Consigliamo 1000 per throughput costante; pagine molto grandi sul tier Starter possono far scattare il rate limit al minuto, quindi cadenza il loop. I tier Pro ed Enterprise gestiscono pagine grandi senza problemi.

3. Checkpoint

Persisti l'ultimo `until` riuscito su un piccolo file JSON (o chiave Redis). Al restart, riprendi da lì — la call API è idempotente quindi rifetchare due volte la riga di confine è innocuo.

4. Script di backfill completo

Python (requests)

python

import json, time, requests
from pathlib import Path

API    = 'https://api.trackersino.com'
KEY    = 'YOUR_KEY'
SLUG   = 'stake-crash'           # any slug from the Games & slugs table
LIMIT  = 1000
END    = '2026-01-01T00:00:00Z'  # stop point (oldest finalized_at to keep)
OUT    = Path(f'{SLUG}.jsonl')
CKPT   = Path(f'{SLUG}.ckpt')

# Resume: 'until' is the oldest finalized_at we've written so far.
until = CKPT.read_text().strip() if CKPT.exists() else None
sess  = requests.Session()
sess.headers['Authorization'] = f'Bearer {KEY}'

with OUT.open('a') as f:
    while True:
        params = {'limit': LIMIT, 'only_finalized': 'true'}
        if until:
            params['until'] = until            # walk into OLDER history
        r = sess.get(f'{API}/v1-beta/games/{SLUG}/rounds', params=params, timeout=15)
        if r.status_code == 429:
            wait = int(r.headers.get('Retry-After', '5')) + 1
            print(f'rate-limit · sleeping {wait}s'); time.sleep(wait); continue
        r.raise_for_status()
        rows = r.json()                         # newest-first
        if not rows: break                      # reached the start of history
        for row in rows:
            f.write(json.dumps(row) + '\n')
        oldest = rows[-1]['finalized_at']       # last row = oldest in this page
        until = oldest                          # next page goes older still
        CKPT.write_text(until)
        if oldest <= END: break                 # hit our stop point
        time.sleep(0.5)                         # be polite
print('done')

5. Formati di storage

Per analisi: Parquet (colonnare, aggregazioni veloci). Per streaming downstream: JSONL (un round per riga). Per SQL: ingestione diretta con COPY in PostgreSQL/ClickHouse. Lo script qui sotto scrive JSONL — pipa con duckdb o polars per convertire.

6. Gestione rate-limit

Su 429, rispetta Retry-After (in secondi). Lo script qui sotto dorme per il valore che manda il server + 1s di jitter, poi riprende. Non insistere — backoff proper così la richiesta successiva passa pulita.

Dataset multi-TB?

Il tier Enterprise offre un dump one-shot via URL S3 firmate — molto più veloce che camminare /rounds per finestre grandi. Chiedicelo su Telegram.

Apri Telegram →