API di fatturazione

Porta l'uso e il costo del tuo workspace nei tuoi sistemi, senza aprire la console. Una chiave di fatturazione è una di sola lettura credenziale limitata a un solo workspace - può solo leggere i dati di fatturazione, nulla di più.

Creare una chiave di fatturazione

1. Apri Console → Chiavi API di fatturazione (solo proprietario del workspace). Assegnale un nome, limitala facoltativamente a una whitelist di IP o imposta una scadenza, poi copia la chiave - inizia con sk-syn-bill- e viene mostrata solo una volta.
2. Chiama gli endpoint sottostanti usandola come token Bearer. Revocala in qualsiasi momento dalla stessa pagina - la revoca la invalida immediatamente e non influisce su nulla altro nel workspace.
3. Una chiave è legata a chi l'ha creata: se questa persona non è più il proprietario del workspace, smette di funzionare e restituisce 403 key_owner_not_authorized.

Autenticazione

Ogni chiamata richiede Authorization: Bearer sk-syn-bill-... verso l'URL di base qui sotto. Una chiave di fatturazione funziona solo su questi endpoint, e questi endpoint accettano solo una chiave di fatturazione - qualsiasi altra combinazione restituisce 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

URL di base: https://synthorai.io/api/v1/billing

GET /usage - utilizzo aggregato

GET /usage

Righe pre-aggregate per ora o per giorno, pensate per fatturazione e dashboard. Provengono dall'aggregato orario più le richieste scritte dall'ultima ingestione, così i bucket recenti non restano indietro di un intero ciclo di ingestione.

In ogni riga, api_key_id e api_key_name compaiono solo quando group_by include api_key, e model solo quando include model. avg_latency_ms può essere null quando un bucket non ha campioni di latenza.

Esempio di richiesta

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - righe per richiesta

GET /records

Una riga per richiesta, pensata per la sincronizzazione incrementale nel tuo database. Sincronizza per cursor, mai per tempo, e deduplica le righe ricevute in base a record_id - vedi "Evitare i vuoti temporali" più sotto per il motivo.

Esempio di richiesta

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - esportazione in streaming

GET /records/export

Gli stessi filtri di /records, trasmessi in streaming come JSON delimitato da a-capo (application/x-ndjson) - pensato per un grande backfill invece di un elenco paginato. Per ogni workspace può essere in streaming una sola esportazione alla volta; una seconda riceve 429 too_many_concurrent_requests.

Esempio di richiesta

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

L'ultima riga dello stream è un _meta oggetto:

GET /summary - statistiche preliminari e anomalie

GET /summary

Totali, i modelli e le chiavi principali per costo, e un tasso di errore per l'intervallo, più una anomalies elenco (high_error_rate, rate_limited, data_not_final, rollup_delayed), ciascuna con una gravità info o warning e un messaggio leggibile. I numeri di un intervallo non ancora finalizzato possono ancora cambiare - vedi sotto.

models_count e keys_count forniscono i totali dietro top_models e top_keys, che elencano al massimo i primi 20 per costo. L'intervallo predefinito è i 30 giorni prima di end quando start viene omesso.

Esempio di richiesta

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - quanto sono completi i dati

GET /freshness

Restituisce data_complete_until, latest_recorded_at, safe_until e pipeline_lag_seconds - interrogalo prima di considerare definitivo un intervallo appena recuperato. safe_until è il recorded_at più recente che un chiamante può considerare completo; righe più recenti potrebbero essere ancora in arrivo.

Esempio di richiesta

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - quanto il workspace può spendere ora

GET /balance

Restituisce il saldo disponibile attuale del workspace, lo stesso importo mostrato in console. Pensato per interrogazioni periodiche: ogni 30-60 secondi è più che sufficiente. Ha un proprio limite di frequenza, quindi interrogarlo non consuma il budget degli endpoint dei dati, e risponde anche quando il saldo è zero.

Esempio di richiesta

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

Esempio di risposta

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

Errori

Ogni errore è {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

Limiti di frequenza e massimali

Non viene mai restituito: channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

Evitare i vuoti temporali

Le richieste vengono scritte nel log in modo asincrono dopo il loro completamento (di norma pochi secondi, più a lungo in caso di accumulo), e il rollup orario letto da /usage e /summary viene caricato in batch. Le ore più recenti sono sempre un po' incomplete. /usage e /summary aggiungono anche le richieste scritte dall'ultima ingestione (meta.live_tail è true); se l'aggregato è troppo indietro, meta.live_tail è false e i bucket recenti sono parziali.

data_complete_until è il più antico tra questi due punti: il livello di riferimento del rollup orario meno il suo ritardo di pipeline attuale, oppure la richiesta più vecchia non ancora inclusa nel rollup - meno un margine di sicurezza di 30 minuti, arrotondato all'ora inferiore.

Ogni riga di /usage porta un indicatore final : true , valido non appena il suo bucket termina prima o entro data_complete_until (valore di /freshness). Un bucket finale non cambia mai più.

• Dati aggregati: esegui l'upsert di ogni riga nel tuo archivio in base a (bucket_start, api_key_id, model), e recupera di nuovo qualsiasi bucket mentre è ancora final: false. Non calcolare mai un delta sottraendo un totale vecchio da uno nuovo.
• Righe grezze: sincronizza per cursor, mai per tempo. Conserva next_cursor e riprendi da lì alla chiamata successiva, e deduplica le righe ricevute in base a record_id (un id opaco stabile per riga) nel caso in cui una pagina ripetuta riconsegni la stessa riga. Le righe più recenti di circa 5 minuti vengono trattenute - safe_until è l'orario della riga registrata più di recente meno 5 minuti - così una riga ancora in fase di commit non può mai scivolare prima di una posizione di cursore già consegnata, e niente cade in un vuoto. Per contare le richieste, conta i request_id distinti.
• Finestra limitata: se interroghi un intervallo start/end invece di sincronizzare per cursor, considéralo completo solo quando window_final è true (è true solo se hai fornito un end ed è precedente o uguale a safe_until). Se window_final è false, richiama più tardi con lo stesso intervallo, oppure passa alla sincronizzazione per cursor. Una finestra deve iniziare al più tardi a safe_until; un inizio successivo restituisce 400 start_too_recent con un header Retry-After.

Integrazione consigliata

• Fatturazione notturna: chiama /usage una volta al giorno con granularity=day, e recupera di nuovo qualsiasi bucket che la tua ultima esecuzione vedeva ancora come final: false.
• Dettaglio per richiesta: chiama /records ogni ora con cursor impostato sull'ultimo next_cursor salvato, continua a paginare finché has_more è true, e deduplica le righe ricevute in base a record_id.
• Dashboard: chiama /summary per l'intervallo visibile invece di aggregare /records da solo - porta già l'elenco delle anomalie.

Devi generare o gestire chiavi API normali in modo programmatico invece di leggere dati di fatturazione? Vedi Chiavi di provisioning.