API publique de facturation

Interroger le solde du compte, l'utilisation des modèles et les coûts depuis vos outils de facturation

L'API publique de facturation permet de lire les données de facturation Atlas Cloud depuis des scripts, tableaux de bord et systèmes financiers.

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

Endpoints

Endpoint	Description
`GET /balance`	Solde actuel du compte et résumé des crédits
`GET /model-usage`	Buckets quotidiens d'utilisation des modèles
`GET /model-costs`	Buckets quotidiens des coûts des modèles

Les schémas complets sont disponibles dans la référence API :

Authentification

Envoyez une clé API Atlas Cloud dans le header Authorization :

Authorization: Bearer apikey-...

Créez vos clés dans API Keys. La clé secrète commence par apikey-.

Certaines réponses et certains filtres utilisent un public ID de clé API comme ak_.... Cet ID peut être affiché dans les rapports, mais ce n'est pas un credential.

Permissions

/model-usage et /model-costs utilisent scope=self par défaut et retournent l'usage attribué à l'utilisateur authentifié, y compris ses clés API.

Utilisez scope=account pour interroger l'utilisation et les coûts du compte entier. Ce scope exige la permission account-level model billing read. /balance utilise toujours le scope account et exige la permission account balance read.

Les propriétaires de comptes personnels peuvent lire leurs propres données. Pour les comptes d'équipe, utilisez un rôle Account Admin ou Finance.

Interroger le solde

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

Les montants sont retournés sous forme de chaîne à six décimales avec une devise :

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

Paramètres d'utilisation et de coûts

start_date et end_date sont requis, en UTC, au format YYYY-MM-DD. end_date est exclusif et la plage maximale est de 180 jours.

Paramètres communs pour /model-usage et /model-costs. Omettre group_by[] retourne les totaux quotidiens :

Paramètre	Description
`start_date`	Date UTC de début incluse au format `YYYY-MM-DD`
`end_date`	Date UTC de fin exclue au format `YYYY-MM-DD`; la plage peut couvrir au plus 180 jours
`scope`	`self` ou `account`; défaut `self`
`group_by[]`	Regroupement optionnel. Ensembles pris en charge : `model_type`, `model`, `api_key`, ou `model` plus `api_key`; utilisez `group_by[]=model` pour le détail par modèle
`model_types[]`	Répéter avec `text`, `image` ou `video`
`model_ids[]`	Filtrer par ID de modèle; jusqu'à 100 valeurs
`api_key_ids[]`	Filtrer par public ID `ak_...`; jusqu'à 100 valeurs
`limit`	Lignes par page, de 1 à 1000; défaut 100
`page`	Cursor opaque reçu dans `next_page`

Utilisez des paramètres répétés pour les tableaux. Les valeurs séparées par virgule sont rejetées.

Interroger l'utilisation

La réponse par défaut retourne les totaux quotidiens d'utilisation.

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

Interroger les Coûts

/model-costs accepte la même plage de dates, le même scope, les mêmes filtres, regroupements et paramètres de pagination que /model-usage. Omettre group_by[] retourne les coûts quotidiens totaux.

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-..."

Pagination

Quand has_more vaut true, renvoyez next_page tel quel dans le paramètre page. Ne décodez pas le cursor et gardez les autres paramètres identiques.

Erreurs et limites

Les erreurs utilisent une enveloppe stable :

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

Les réponses limitées retournent 429 rate_limit_error et peuvent inclure un header Retry-After.

Sur cette page