Événements d'usage

L'écran Événements d'usage vous permet de parcourir les événements d'usage bruts de votre tenant, un par appel de passerelle, avec les unités consommées et le coût estimé, mesuré et facturé. Chemin dans le portail : /finops/usage (menu FinOps > Événements d'usage). Les analystes FinOps et les auditeurs l'utilisent pour expliquer une ligne de coût jusqu'à l'appel qui l'a produite.

Ce que montre l'écran

Zone	Contenu
Filtres	Fournisseur, Identifiant de modèle, Identifiant d'agent, Identifiant d'exécution (texte libre), Type d'usage (llm, embedding, image, audio, video, tool, gpu_local, rag), Statut (estimated, measured, billed), Du et Au (horodatage ISO 8601, par exemple 2026-01-01T00:00:00Z).
Tableau Événements d'usage	Colonnes : Date, Type d'usage, Fournisseur, Modèle, Identifiant d'agent, Jetons d'entrée, Jetons de sortie, Estimé, Mesuré, Facturé (chaque montant dans sa propre devise), Statut. Du plus récent au plus ancien, 50 lignes par page.
Panneau de détail	Un clic sur une ligne ouvre l'événement complet (unités, coût, identifiants) en JSON. Le panneau montre la ligne déjà chargée : aucun appel supplémentaire.
État vide	Aucun événement d'usage : chaque appel aux passerelles produit des événements.

Actions

Bouton ou action	Ce qu'il fait	Appel API	Rôles
Filtrer	Applique les filtres remplis (les filtres vides sont ignorés).	GET /v1/finops/usage (provider, model_id, agent_id, run_id, usage_type, status, from, to, limit, cursor)	Lecteurs de la section FinOps
Actualiser (icône flèche ronde)	Recharge la liste.	GET /v1/finops/usage	Lecteurs de la section FinOps
Charger plus	Charge la page suivante avec le curseur renvoyé par le serveur.	GET /v1/finops/usage (cursor)	Lecteurs de la section FinOps
Clic sur une ligne	Ouvre le panneau de détail de l'événement.	Aucun	Lecteurs de la section FinOps
Réessayer (encadré d'erreur)	Renvoie la requête de liste.	GET /v1/finops/usage	Lecteurs de la section FinOps

L'écran n'a pas de bouton de création : les événements sont écrits par les passerelles et le SDK (POST /v1/finops/usage, rôles finops, tenant_admin, agent, developer).

Rôles

Rôle	Accès
finops, tenant_admin, auditor	Ouvrent l'écran et lisent les événements (READ_ROLES de services/control-plane/src/eai/domains/finops/__init__.py).
platform_admin	Ouvre l'écran ; la route exige un contexte de tenant (sinon tenant_required).
developer, viewer, security_officer	Autorisés par l'API, mais la section FinOps du menu du portail ne s'ouvre pas pour eux.

Tâches courantes

Expliquer le coût d'une exécution

1. Copier l'identifiant d'exécution. Il relie tous les appels d'une exécution d'agent. Copiez-le depuis Exécutions. Résultat attendu : vous avez un identifiant tel que <run-id>. En cas d'échec : ouvrez l'exécution dans Agents > Exécutions et copiez l'identifiant depuis son détail.
2. Filtrer sur l'exécution. Collez l'identifiant dans Identifiant d'exécution et cliquez sur Filtrer. Résultat attendu : le tableau ne liste que les appels de cette exécution. En cas d'échec : si Aucun événement d'usage s'affiche, vérifiez que l'identifiant n'a pas d'espace et que l'exécution a appelé un modèle.
3. Ouvrir un événement. Cliquez sur une ligne pour lire les unités et le détail du coût. Résultat attendu : le panneau montre le JSON de l'événement, avec cost.estimated, cost.measured et cost.billed. En cas d'échec : fermez puis rouvrez le panneau, ou cliquez sur Actualiser.

Lister les appels d'un modèle pas encore rapprochés

1. Filtrer sur le modèle et le statut. Remplissez Identifiant de modèle et choisissez measured dans Statut, puis cliquez sur Filtrer. Les événements measured ont un coût mesuré mais pas encore de coût facturé. Résultat attendu : le tableau liste les appels de ce modèle en attente de rapprochement. En cas d'échec : une erreur validation_error sur Du ou Au signifie que l'horodatage n'est pas au format ISO 8601.
2. Les rapprocher. Importez l'export du fournisseur de la période dans Rapprochement. Résultat attendu : après le rapprochement, le même filtre avec billed liste les événements. En cas d'échec : voyez le dépannage de la page Rapprochement.

Dépannage

Symptôme	Cause	Correction
Erreur validation_error (HTTP 422) : « La requête n'a pas passé la validation. »	Du ou Au n'est pas un horodatage ISO 8601.	Écrivez la date sous la forme 2026-01-01T00:00:00Z.
Erreur forbidden (HTTP 403)	Aucun rôle de READ_ROLES.	Demandez le rôle finops.
Erreur tenant_required (HTTP 403)	Administrateur de plateforme sans tenant.	Connectez-vous à un tenant.
Aucun événement d'usage	Aucun appel ne correspond aux filtres, ou la passerelle n'a pas remonté d'usage.	Retirez des filtres ; vérifiez la passerelle dans Playground passerelle.
Colonne Facturé vide	L'événement n'a pas été rapproché avec un export fournisseur.	Lancez le rapprochement dans Rapprochement.

Pages liées

• Synthèse
• Rapprochement
• Grilles tarifaires
• Exécutions
• Brique registre des coûts
• Brique comptage des jetons