> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Récupérer la consommation
> Interrogez les données d’analyse de consommation des crédits ou des ACU avec des options flexibles de filtrage, de regroupement et de pagination.
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](#authentication) 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
```
La clé de service doit avoir l’autorisation **Analytics Read**. Créez-en une dans [Team Settings](https://windsurf.com/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égie | Champs renseignés | Description |
| --------- | -------------------------------- | ------------------------------ |
| `CREDITS` | `prompt_credits`, `flex_credits` | Teams Standard SaaS Enterprise |
| `ACU` | `billed_acus` | Teams 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.
## OpenAPI
````yaml fr/desktop/accounts/api-reference/analytics-v2-openapi.yaml GET /api/v2alpha/analytics/consumption
openapi: 3.1.0
info:
title: Devin Desktop Analytics API v2
version: 2.0.0
description: >
L’Analytics API v2 fournit des analyses de consommation de crédits et d’ACU
pour les Teams Enterprise.
Les données proviennent d’événements de Billing agrégés par heure et
prennent en charge un filtrage flexible, le regroupement
et la pagination par curseur.
servers:
- url: https://server.codeium.com
security:
- bearerAuth: []
paths:
/api/v2alpha/analytics/consumption:
get:
summary: Récupérer l’analyse de la consommation
description: "Interrogez les données de consommation de crédits ou d’ACU pour la Team authentifiée. Les résultats proviennent d’événements de Billing agrégés par heure et peuvent être filtrés par plage de dates, produit, modèle et groupe.\n\nLa structure de la réponse dépend de la stratégie de Billing de la Team\_:\n- Les Teams **basées sur les crédits** reçoivent `prompt_credits` et `flex_credits` dans chaque ligne.\n- Les Teams **basées sur les ACU** reçoivent `billed_acus` dans chaque ligne.\n\nLes réponses sont mises en cache pendant 1 heure. Utilisez `If-None-Match` avec un `ETag` précédemment renvoyé pour recevoir une réponse `304 Not Modified` lorsque les données n’ont pas changé.\n\nCes endpoints sont conçus pour le reporting périodique et l’export en masse. Ils ne sont **pas** destinés au suivi de l’utilisation en temps réel\_: les données sont agrégées par heure et la limite de débit est faible (10 requêtes par heure et par Team).\n"
operationId: getConsumption
parameters:
- name: start_date
in: query
required: true
schema:
type: string
format: date
description: Début de la plage de dates (inclus) au format `YYYY-MM-DD`.
example: '2026-01-01T00:00:00.000Z'
- name: end_date
in: query
required: true
schema:
type: string
format: date
description: >-
Fin de la plage de dates (incluse) au format `YYYY-MM-DD`. La plage
ne doit pas dépasser 90 jours.
example: '2026-01-31T00:00:00.000Z'
- name: product
in: query
required: true
schema:
type: string
enum:
- agent
description: Produit pour lequel interroger la consommation.
example: agent
- name: granularity
in: query
required: false
schema:
type: string
enum:
- daily
- monthly
description: >
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.
- name: group_by
in: query
required: false
schema:
type: string
description: "Liste des dimensions, séparées par des virgules, selon lesquelles regrouper les résultats. Dimensions prises en charge\_:\n- `user` — inclut `user_id` et `user_email` dans chaque ligne\n- `model_uid` — inclut `model_uid` dans chaque ligne\n- `ide` — inclut `ide` dans chaque ligne\n"
example: user,model_uid
- name: models
in: query
required: false
schema:
type: string
description: >-
Liste des UID de modèle, séparés par des virgules, auxquels filtrer
les résultats.
example: claude-4-sonnet,gpt-4.1
- name: group_id
in: query
required: false
schema:
type: string
description: >-
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.
- name: user_id
in: query
required: false
schema:
type: string
description: >-
Filtrez les résultats pour ne conserver qu’un user spécifique (UID
d’authentification).
- name: page_size
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
default: 1000
description: Nombre maximal de lignes à renvoyer par page.
- name: page_cursor
in: query
required: false
schema:
type: string
description: >-
Curseur opaque provenant de `pagination.next_page_cursor` dans une
réponse précédente, permettant de récupérer la page suivante.
- name: If-None-Match
in: header
required: false
schema:
type: string
description: >-
Valeur ETag provenant d’une réponse précédente. Si les données n’ont
pas changé, le serveur renvoie `304 Not Modified`.
responses:
'200':
description: Données de consommation renvoyées avec succès.
headers:
ETag:
schema:
type: string
description: >-
Balise d’entité pour la validation du cache. Transmettez-la sous
la forme de `If-None-Match` dans les requêtes suivantes.
Cache-Control:
schema:
type: string
description: "Directive de cache (p.\_ex.\_: `private, max-age=3600`)."
content:
application/json:
schema:
$ref: '#/components/schemas/ConsumptionResponse'
examples:
credits:
summary: Team basée sur des crédits avec granularité quotidienne
value:
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
acu:
summary: Team basée sur les ACU
value:
data:
- consumption:
billed_acus: 42.75
message_count: 310
pagination:
next_page_cursor: null
metadata:
billing_strategy: ACU
data_freshness: '2026-01-16T03:00:00.000Z'
query_time_ms: 892
team_id: team_def456
'304':
description: >-
Les données n’ont pas changé depuis l’ETag fourni dans
`If-None-Match`.
'400':
description: Paramètres de requête non valides.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_param:
value:
error: start_date is required
date_range:
value:
error: date range must not exceed 90 days
bad_product:
value:
error: 'unsupported product: foo (supported: agent)'
'401':
description: Échec de l’authentification ou autorisations insuffisantes.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
missing_auth:
value:
error: missing Authorization header
invalid_key:
value:
error: invalid service key
insufficient_permissions:
value:
error: insufficient permissions
'403':
description: >-
Le curseur de page fourni n’appartient pas à la Team authentifiée ni
au groupe demandé.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
cursor_team_mismatch:
value:
error: page cursor does not belong to this team
'405':
description: Méthode HTTP non autorisée (seul `GET` est pris en charge).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: >-
Limite de débit dépassée (10 requêtes par heure et par Team). La
pagination d’une requête précédente n’est pas comptabilisée dans
cette limite.
headers:
Retry-After:
schema:
type: string
description: Temps d’attente recommandé avant de réessayer.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
rate_limited:
value:
error: rate limit exceeded
'503':
description: "Le service d’analyse n’est pas disponible (p.\_ex. dans les déploiements self-hosted)."
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
security:
- bearerAuth: []
components:
schemas:
ConsumptionResponse:
type: object
required:
- data
- pagination
- metadata
properties:
data:
type: array
items:
$ref: '#/components/schemas/ConsumptionRow'
description: Tableau de lignes de données de consommation.
pagination:
type: object
properties:
next_page_cursor:
type:
- string
- 'null'
description: "Curseur opaque permettant de récupérer la page de résultats suivante. Transmettez cette valeur comme paramètre de requête `page_cursor`\ndans une requête suivante. `null` lorsqu’il n’y a plus de pages.\nLes curseurs de page expirent après 24\_heures.\n"
metadata:
type: object
properties:
billing_strategy:
type: string
enum:
- CREDITS
- ACU
description: "La stratégie de Billing de la Team authentifiée. Elle détermine quels champs de `consumption` sont renseignés\_:\n- `CREDITS` — `prompt_credits` et `flex_credits`\n- `ACU` — `billed_acus`\n"
data_freshness:
type: string
format: date-time
description: >-
Horodatage indiquant quand les données sous-jacentes ont été
actualisées pour la dernière fois (tronqué à l’heure).
query_time_ms:
type: integer
format: int64
description: Temps d’exécution de la requête côté serveur, en millisecondes.
team_id:
type: string
description: ID de la Team résolu à partir de la clé de service authentifiée.
group_id:
type: string
description: >-
ID du groupe auquel les résultats étaient limités. Présent
uniquement lorsque `group_id` a été fourni.
Error:
type: object
required:
- error
properties:
error:
type: string
description: Message d’erreur compréhensible par un humain.
ConsumptionRow:
type: object
required:
- consumption
properties:
timestamp:
type: string
description: "Tranche temporelle de la ligne. Le format dépend de `granularity`\_: `YYYY-MM-DD` pour le jour, `YYYY-MM` pour le mois.\nPrésent uniquement lorsque `granularity` est spécifié.\n"
examples:
- '2026-05-01T00:00:00.000Z'
- 2026-05
user_id:
type: string
description: >-
Identifiant de l’utilisateur (UID d’authentification). Présent
uniquement lorsque `group_by` inclut `user`.
user_email:
type: string
description: >-
Adresse e-mail de l’utilisateur. Présente uniquement lorsque
`group_by` inclut `user`.
examples:
- alice@example.com
model_uid:
type: string
description: >-
Identifiant du modèle. Présent uniquement lorsque `group_by` inclut
`model_uid`.
examples:
- claude-4-sonnet
ide:
type: string
description: Nom de l’IDE. Présent uniquement lorsque `group_by` inclut `ide`.
examples:
- windsurf
- jetbrains
consumption:
$ref: '#/components/schemas/Consumption'
Consumption:
type: object
description: >-
Métriques d’utilisation pour la ligne. Les champs sont renseignés en
fonction de la stratégie de Billing de la Team.
properties:
prompt_credits:
type: integer
format: int64
description: >-
Crédits de prompt consommés (Billing basé sur les crédits
uniquement).
flex_credits:
type: integer
format: int64
description: Crédits Flex consommés (Billing basé sur les crédits uniquement).
billed_acus:
type: number
format: double
description: ACU facturés consommés (Billing basé sur les ACU uniquement).
message_count:
type: integer
format: int64
description: >-
Nombre de messages (événements de Billing) dans cette ligne.
Toujours renseigné, quelle que soit la stratégie de Billing.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
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](https://windsurf.com/team/settings), dans la section
"Service Keys".
````