> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Consulter les dépenses et l’utilisation > - Consulter les dépenses et les appels sur une période donnée - Filtrer par modèle et regrouper par modèle ou jour calendaire - Consulter la clé API actuelle ou l’ensemble du compte - Obtenir les montants en USD, crédits, appels et tokens Utilisez une API Key pour consulter les dépenses sur une période donnée, avec filtrage par modèle et regroupement par modèle, jour calendaire ou les deux. Le résultat agrégé est renvoyé directement : aucune création de tâche ni interrogation de son statut n’est nécessaire. ```bash cURL theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'group_by=model' ``` ```python Python theme={null} import requests response = requests.get( "https://api.apimart.ai/v1/usage", headers={"Authorization": "Bearer "}, params={ "start": "2026-09-01T00:00:00+08:00", "end": "2026-09-08T00:00:00+08:00", "group_by": "model", }, timeout=30, ) payload = response.json() if not response.ok or not payload.get("success"): message = payload.get("error", {}).get("message", "Échec de la requête d’utilisation") raise RuntimeError(f"HTTP {response.status_code}: {message}") print(payload["data"]["total"]) print(payload["data"]["items"]) ``` ```javascript JavaScript theme={null} const url = new URL("https://api.apimart.ai/v1/usage"); url.search = new URLSearchParams({ start: "2026-09-01T00:00:00+08:00", end: "2026-09-08T00:00:00+08:00", group_by: "model", }).toString(); const response = await fetch(url, { headers: { Authorization: "Bearer " }, }); const payload = await response.json(); if (!response.ok || !payload.success) { throw new Error( `HTTP ${response.status}: ${payload.error?.message ?? "Échec de la requête d’utilisation"}`, ); } console.log(payload.data.total); console.log(payload.data.items); ``` ```json 200 theme={null} { "success": true, "data": { "scope": "key", "start": 1788192000, "end": 1788796800, "tz": "Asia/Shanghai", "group_by": "model", "total": { "amount_usd": 12.3456, "credits": 123.456, "requests": 1834, "prompt_tokens": 902311, "completion_tokens": 215044 }, "items": [ { "model": "gpt-5.6-luna", "amount_usd": 9.1271, "credits": 91.271, "requests": 1520, "prompt_tokens": 880120, "completion_tokens": 201300 }, { "model": "sora-2", "amount_usd": 3.2185, "credits": 32.185, "requests": 314, "prompt_tokens": 22191, "completion_tokens": 13744 } ] } } ``` ```json 400 theme={null} { "success": false, "error": { "code": "range_too_large", "message": "Time range must not exceed 31 days.", "type": "usage_query_error" } } ``` ## Authentification Utilisez la même API Key que pour les appels aux modèles, avec une authentification Bearer Token. Obtenez votre clé sur la [page de gestion des API Keys](https://apimart.ai/keys). ``` Authorization: Bearer YOUR_API_KEY ``` La requête fonctionne même avec un solde de 0. Le solde n’est pas vérifié, mais le statut et l’expiration de la clé, la liste des IP autorisées et le statut du compte le sont. ## Points de terminaison ```text theme={null} GET /v1/usage GET /usage ``` Les deux points de terminaison sont équivalents et prennent en charge CORS. Protégez votre API Key et ne l’exposez pas dans du code frontend public. ## Paramètres de requête Tous les paramètres sont transmis dans la chaîne de requête de l’URL. Début de la période, inclus. Accepte un timestamp Unix en secondes ou une chaîne RFC3339 avec fuseau horaire, par exemple `2026-09-01T00:00:00+08:00`. Par défaut : 24 heures avant `end`. Les timestamps sont en secondes, pas en millisecondes. Fin de la période, exclue. Même format que `start` ; par défaut, l’heure actuelle. Doit être après `start` et `end - start` ne doit pas dépasser 31 jours. Nom du modèle. Si omis, tous les modèles sont inclus. Séparez les modèles par des virgules, avec un maximum de `50`. Correspondance exacte, insensible à la casse. Les caractères génériques ne sont pas pris en charge. Exemple : `gpt-5.6-luna,sora-2` Regroupement : * `none` : total uniquement ; `items` est un tableau vide * `model` : par modèle * `date` : par jour calendaire * `model,date` : par modèle et jour calendaire Nom de fuseau horaire IANA. Par défaut : `Asia/Shanghai`. Affecte uniquement les limites des jours lorsque `group_by` contient `date`, sans modifier les instants de début et de fin. Les dates RFC3339 sont interprétées selon leur propre fuseau horaire. Périmètre des statistiques : * `key` : API Key actuelle uniquement (par défaut) * `account` : toutes les API Keys du compte auquel appartient la clé actuelle La période est `[start, end)` : début inclus, fin exclue. Utilisez le même instant pour `end` de la requête précédente et `start` de la suivante afin d’éviter un double comptage à la limite. Si vous construisez l’URL manuellement, encodez le `+` de RFC3339 en `%2B`. Les exemples avec cURL `--data-urlencode`, Python `params` et JavaScript `URLSearchParams` le font automatiquement. ## Exemples de requête ### Dépenses de l’API Key actuelle sur les dernières 24 heures Sans paramètres de requête, la période, le périmètre et le regroupement par défaut s’appliquent. ```bash theme={null} curl 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' ``` ### Dépenses quotidiennes du compte pour des modèles précis Consulter les dépenses du 11 au 18 septembre 2026, heure de Pékin, sans inclure le 18 septembre. ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=1789056000' \ --data-urlencode 'end=1789660800' \ --data-urlencode 'model=gpt-5.6-luna' \ --data-urlencode 'group_by=date' \ --data-urlencode 'scope=account' \ --data-urlencode 'tz=Asia/Shanghai' ``` ### Regroupement par modèle et jour calendaire ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'model=gpt-5.6-luna,sora-2' \ --data-urlencode 'group_by=model,date' \ --data-urlencode 'tz=Asia/Shanghai' ``` Chaque élément de `items` contient alors à la fois `model` et `date`. ## Champs de réponse Réussite de la requête : `true` en cas de succès, `false` en cas d’erreur de consultation de l’utilisation. En cas de succès, renvoie le périmètre, le total et les détails regroupés. Périmètre : `key` ou `account`. Début effectif sous forme de timestamp Unix en secondes, inclus. Fin effective sous forme de timestamp Unix en secondes, exclue. Fuseau horaire utilisé pour les jours calendaires. Regroupement : `none`, `model`, `date` ou `model,date`. Total de la période. Voir les champs statistiques ci-dessous. Détails regroupés, triés par `amount_usd` décroissant. Tableau vide si `group_by=none`. Chaque élément contient les champs statistiques du tableau ci-dessous. * Si `group_by` contient `model`, l’élément contient `model` * Si `group_by` contient `date`, l’élément contient `date` au format `YYYY-MM-DD` ; les jours sont délimités selon `tz` `data.total` et `data.items[]` partagent les champs statistiques suivants : | Champ | Type | Description | | ------------------- | ------- | --------------------------------------------------------------------------------------------------- | | `amount_usd` | number | Montant en USD, arrondi à 6 décimales | | `credits` | number | Crédits du service : `amount_usd × 10`, même unité que sur le site | | `requests` | integer | Nombre d’appels facturés avec succès | | `prompt_tokens` | integer | Tokens d’entrée ; généralement 0 pour les modèles image et vidéo facturés par appel ou par seconde | | `completion_tokens` | integer | Tokens de sortie ; généralement 0 pour les modèles image et vidéo facturés par appel ou par seconde | En cas d’erreur de consultation, contient `code`, `message` et `type`, où `type` vaut `usage_query_error`. Les erreurs d’authentification 401 / 403 proviennent de la couche d’authentification. ## Limites et cache * Maximum `60` requêtes par minute et par API Key ; les limites globales de l’API s’appliquent aussi * Les résultats avec les mêmes paramètres sont mis en cache pendant `60` secondes ; l’en-tête `X-Usage-Cache` vaut `hit` ou `miss` * Les dépenses sont généralement visibles sous 1 seconde, mais la dernière minute peut être incomplète et le cache peut ajouter un délai * Intervalle recommandé : au moins 1 minute ; ne pas utiliser comme notification de facturation en temps réel ## Règles de comptabilisation * Basé sur les appels facturés avec succès, avec les mêmes données que le tableau de bord du site * Les appels échoués et les tâches remboursées après échec sont exclus : aucun ajustement manuel nécessaire. Les lots d’images partiellement réussis sont facturés selon les images réellement livrées * La date retenue est celle de la comptabilisation. Les tâches image et vidéo asynchrones sont comptabilisées à la fin, non à la soumission ; celles qui passent minuit relèvent du jour de fin * Une API Key recréée après suppression est une nouvelle clé. Sa requête `scope=key` n’inclut pas l’historique de l’ancienne * Les ajustements manuels de solde ne sont pas des dépenses d’appels et sont exclus * Les données postérieures au 27 avril 2026 sont disponibles ## Gestion des erreurs | Statut HTTP | `error.code` | Description | | ----------- | ------------------------------- | --------------------------------------------------------------------- | | 400 | `invalid_start` / `invalid_end` | Format de début ou de fin invalide | | 400 | `invalid_range` | `end` n’est pas après `start` | | 400 | `range_too_large` | Plus de 31 jours ; divisez la période en plusieurs requêtes | | 400 | `invalid_tz` | Fuseau horaire IANA inconnu | | 400 | `invalid_group_by` | Regroupement invalide | | 400 | `invalid_scope` | Périmètre invalide | | 400 | `too_many_models` | Plus de 50 modèles | | 401 / 403 | — | API Key invalide ou expirée, IP non autorisée ou compte désactivé | | 429 | — | Plus de 60 requêtes par clé et par minute, ou limite globale de l’API | | 503 | `usage_unavailable` | Données temporairement indisponibles ; réessayez plus tard | `503 usage_unavailable` ne renvoie aucun montant. La requête est indisponible, ce qui ne signifie pas que les dépenses sont nulles. Ne convertissez pas une erreur en montant nul et n’écrasez pas un résultat réussi précédent. ## Comparaison avec les autres points de terminaison | Point de terminaison | Fonction | | --------------------------------- | ------------------------------------------------------------------------------------ | | `GET /v1/dashboard/billing/usage` | Total cumulé uniquement ; aucun filtre par modèle ou période | | `POST /v1/logs/export` | Export asynchrone des détails d’appels (CSV / XLSX) ; agrégation à votre charge | | `GET /v1/usage` | Recherche par période et modèle avec retour direct du total et des détails regroupés | Pour le quota restant, utilisez [Consulter le solde du token](/fr/api-reference/account/token-balance) ou [Consulter le solde utilisateur](/fr/api-reference/account/user-balance).