API pubblica di fatturazione

Interroga saldo account, utilizzo dei modelli e costi dai tuoi strumenti di fatturazione

L'API pubblica di fatturazione consente di leggere i dati di fatturazione Atlas Cloud da script, dashboard e sistemi finanziari.

Base URL: https://api.atlascloud.ai/public/v1

Endpoint

Endpoint	Descrizione
`GET /balance`	Saldo corrente dell'account e riepilogo dei crediti
`GET /model-usage`	Bucket giornalieri di utilizzo dei modelli
`GET /model-costs`	Bucket giornalieri dei costi dei modelli

Gli schemi completi sono disponibili nella reference API:

Autenticazione

Invia una API Key Atlas Cloud nell'header Authorization:

Authorization: Bearer apikey-...

Crea le chiavi da API Keys. La chiave segreta inizia con apikey-.

Alcune risposte e filtri usano un API Key public ID come ak_.... Questo ID può essere mostrato nei report, ma non è una credenziale.

Permessi

/model-usage e /model-costs usano scope=self di default e restituiscono l'uso attribuito all'utente autenticato, incluse le API Key che possiede.

Usa scope=account per interrogare utilizzo e costi dell'intero account. Questo richiede account-level model billing read permission. /balance usa sempre account scope e richiede account balance read permission.

I proprietari di account personali possono leggere i propri dati. Per account team usa un ruolo Account Admin o Finance.

Interrogare il saldo

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

Gli importi sono restituiti come stringhe con sei decimali e valuta:

{
  "value": "125.500000",
  "currency": "usd"
}

Parametri di Utilizzo e Costi

start_date e end_date sono obbligatori, in UTC, nel formato YYYY-MM-DD. end_date è esclusivo e l'intervallo massimo è 180 giorni.

Parametri comuni per /model-usage e /model-costs. Omettere group_by[] restituisce i totali giornalieri:

Parametro	Descrizione
`start_date`	Data UTC di inizio inclusiva in formato `YYYY-MM-DD`
`end_date`	Data UTC di fine esclusiva in formato `YYYY-MM-DD`; l’intervallo può coprire al massimo 180 giorni
`scope`	`self` o `account`; default `self`
`group_by[]`	Raggruppamento opzionale. Set supportati: `model_type`, `model`, `api_key` oppure `model` più `api_key`; usa `group_by[]=model` per il dettaglio per modello
`model_types[]`	Ripeti con `text`, `image` o `video`
`model_ids[]`	Filtra per ID modello; massimo 100 valori
`api_key_ids[]`	Filtra per public ID `ak_...`; massimo 100 valori
`limit`	Righe per pagina, da 1 a 1000; default 100
`page`	Cursor opaco ricevuto in `next_page`

Usa parametri ripetuti per gli array. I valori separati da virgola vengono rifiutati.

Interrogare l'utilizzo

La risposta predefinita restituisce i totali giornalieri di utilizzo.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

Interrogare i Costi

/model-costs accetta lo stesso intervallo di date, scope, filtri, raggruppamento e parametri di paginazione di /model-usage. Omettere group_by[] restituisce i costi giornalieri totali.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

Paginazione

Quando has_more è true, invia next_page invariato come parametro page. Il cursor è opaco: non decodificarlo e non modificare gli altri parametri.

Errori e limiti

Gli errori usano un envelope stabile:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

Le risposte limitate restituiscono 429 rate_limit_error e possono includere un header Retry-After.

In questa pagina