Passer au contenu principal
GET
/
api
/
v2alpha
/
analytics
/
consumption
Récupérer l’analyse de la consommation
curl --request GET \
  --url https://server.codeium.com/api/v2alpha/analytics/consumption \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "timestamp": "2026-01-15T00:00:00.000Z",
      "user_id": "user_abc123",
      "user_email": "alice@example.com",
      "consumption": {
        "prompt_credits": 1250,
        "flex_credits": 340,
        "message_count": 87
      }
    },
    {
      "timestamp": "2026-01-15T00:00:00.000Z",
      "user_id": "user_def456",
      "user_email": "bob@example.com",
      "consumption": {
        "prompt_credits": 980,
        "flex_credits": 150,
        "message_count": 52
      }
    }
  ],
  "pagination": {
    "next_page_cursor": null
  },
  "metadata": {
    "billing_strategy": "CREDITS",
    "data_freshness": "2026-01-16T03:00:00.000Z",
    "query_time_ms": 1423,
    "team_id": "team_abc123"
  }
}
Il s’agit d’un endpoint v2 qui utilise l’authentification par jeton Bearer et des paramètres de requête, contrairement à l’Analytics API v1, qui utilise des clés de service dans le corps de la requête. Consultez Authentification ci-dessous.
Cet endpoint n’est pas conçu pour le suivi de l’utilisation en temps réel. Les données sont agrégées à l’heure, et la limite de débit est basse (10 requêtes par heure et par Team). Utilisez-le pour les rapports périodiques et les exportations en masse.

​
Authentification

Cet endpoint utilise une authentification par Bearer token. Incluez votre clé de service dans l’en-tête Authorization : 
Authorization: Bearer <your_service_key>
La clé de service doit avoir l’autorisation Analytics Read. Créez-en une dans Team Settings, sous “Service Keys”.

​
Stratégie de facturation

La structure de la réponse dépend de la stratégie de facturation de votre Team :
StratégieChamps renseignésDescription
CREDITSprompt_credits, flex_creditsTeams Standard SaaS Enterprise
ACUbilled_acusTeams facturées en ACU
Le champ message_count (dans consumption) est toujours renseigné, quelle que soit la stratégie de facturation.

​
Regroupement et granularité

Utilisez granularity et group_by pour contrôler la structure des données renvoyées :
  • Aucune granularité ni aucun regroupement — renvoie une seule ligne agrégée pour l’ensemble de la plage de dates
  • granularity=daily — chaque ligne inclut un timestamp au format YYYY-MM-DD
  • granularity=monthly — chaque ligne inclut un timestamp au format YYYY-MM
  • group_by=user — chaque ligne inclut un user_id et un user_email
  • group_by=user,model_uid — chaque ligne inclut user_id, user_email et model_uid
  • group_by=ide — chaque ligne inclut un ide
Les résultats sont paginés, avec une taille de page par défaut de 1 000 lignes (max. 10 000). Lorsque d’autres résultats sont disponibles, la réponse inclut un next_page_cursor dans l’objet pagination. Passez-le comme paramètre de requête page_cursor pour récupérer la page suivante. Les curseurs de page expirent au bout de 24 heures. Une requête pour une page suivante n’est pas comptabilisée comme une nouvelle requête dans votre limite de débit.

​
Mise en cache

Les réponses contiennent un en-tête ETag. Pour éviter un transfert de données inutile, incluez l’en-tête If-None-Match avec la valeur ETag précédente — le serveur renverra 304 Not Modified si les données n’ont pas changé.

​
Limites de débit

Cet endpoint est soumis à une limite de 10 requêtes par heure par Team. Si vous dépassez cette limite, le serveur renvoie 429 Too Many Requests avec un en-tête Retry-After. La pagination d’une requête antérieure (en suivant un next_page_cursor) n’est pas décomptée de cette limite — seule la requête initiale de chaque rapport l’est. Cette faible limite s’explique par le fait que cet endpoint est destiné à des rapports périodiques, et non au suivi de l’utilisation en temps réel.

Autorisations

​
Authorization
string
header
requis

Une clé de service disposant de l’autorisation Analytics Read, transmise comme jeton Bearer dans l’en-tête Authorization.

Créez une clé de service dans les paramètres de votre Team, à l’adresse team settings, dans la section "Service Keys".

En-têtes

​
If-None-Match
string

Valeur ETag provenant d’une réponse précédente. Si les données n’ont pas changé, le serveur renvoie 304 Not Modified.

Paramètres de requête

​
start_date
string<date>
requis

Début de la plage de dates (inclus) au format YYYY-MM-DD.

​
end_date
string<date>
requis

Fin de la plage de dates (incluse) au format YYYY-MM-DD. La plage ne doit pas dépasser 90 jours.

​
product
enum<string>
requis

Produit pour lequel interroger la consommation.

Options disponibles:
agent
​
granularity
enum<string>

Granularité temporelle pour regrouper les résultats. Lorsqu’elle est spécifiée, chaque ligne inclut un champ timestamp. Si elle est omise, les résultats sont agrégés sur l’ensemble de la plage de dates.

Options disponibles:
daily,
monthly
​
group_by
string

Liste des dimensions, séparées par des virgules, selon lesquelles regrouper les résultats. Dimensions prises en charge :

  • user — inclut user_id et user_email dans chaque ligne
  • model_uid — inclut model_uid dans chaque ligne
  • ide — inclut ide dans chaque ligne
​
models
string

Liste des UID de modèle, séparés par des virgules, auxquels filtrer les résultats.

​
group_id
string

Filtrez les résultats pour ne conserver que les users d’un groupe spécifique. La clé de service doit avoir accès à ce groupe.

​
user_id
string

Filtrez les résultats pour ne conserver qu’un user spécifique (UID d’authentification).

​
page_size
integer
défaut:1000

Nombre maximal de lignes à renvoyer par page.

Plage requise: 1 <= x <= 10000
​
page_cursor
string

Curseur opaque provenant de pagination.next_page_cursor dans une réponse précédente, permettant de récupérer la page suivante.

Réponse

Données de consommation renvoyées avec succès.

​
data
object[]
requis

Tableau de lignes de données de consommation.

​
pagination
object
requis
​
metadata
object
requis