vikia Documentation publique EN Tableau de bord

POUR LES COLLECTEURS ET LES AGENTS IA

Envoyer des métriques à Vikia

Cette page peut être partagée et lue sans compte ni JavaScript. Elle décrit l’ingestion uniquement ; elle ne contient aucune clé ni donnée privée.

1. Contrat essentiel

POST https://vikia.lafougere.dev/api/metrics
Content-Type: application/json
Authorization: Bearer <VIKIA_API_KEY>

Les exemples ci-dessous sont illustratifs, pas des tarifs fournisseurs réels. Les envoyer ajoute réellement des métriques : il n’existe pas de mode dry-run ni de suppression via l’API. Ne pas envoyer de fausses données pour « tester » la production.

2. Champs du relevé

Tous les champs sont obligatoires, sauf event_id, qui est fortement recommandé. Les noms sont sensibles à la casse ; tout champ inconnu est refusé.

Types JSON, contraintes et signification de chaque champ
ChampType JSONRègle
event_idchaîne facultative1 à 160 caractères imprimables. Identifiant unique dans toute l’instance, pas seulement par fournisseur. Exemple : source + période + fournisseur + modèle + devise + version du tarif.
datechaîneInstant RFC3339 avec fuseau, par exemple 2026-11-16T12:00:00Z ou 2026-11-16T13:00:00+01:00. Une date YYYY-MM-DD vaut minuit UTC. Utiliser une convention stable, par exemple la fin de période.
providerchaîne1 à 120 caractères imprimables. Nom du fournisseur, conservé tel quel.
modelchaîne1 à 180 caractères imprimables. Identifiant du modèle réellement utilisé.
currencychaîneExactement EUR ou USD. Les deux prix sont dans cette même devise. Les montants d’origine sont conservés ; ne pas convertir les relevés avant envoi.
input_price_per_millionchaîne décimalePrix d’un million de tokens d’entrée, entre "0" et "1000000000", jusqu’à 9 décimales.
output_price_per_millionchaîne décimaleMêmes contraintes, pour les tokens de sortie.
input_tokensentierDe 0 à 1000000000000000 inclus. Tokens d’entrée de ce relevé.
output_tokensentierMêmes bornes. Tokens de sortie de ce relevé.
requestsentierMêmes bornes. Nombre d’appels de ce relevé, pas le nombre de requêtes HTTP envoyées à Vikia.

Prix valides : "0", "0.15", "0.000000001". Prix invalides : 0.15 (nombre au lieu d’une chaîne), "1e-3", "0,15", "-1". Les compteurs doivent être des entiers JSON, pas des chaînes, flottants ou booléens. Pas de null, NaN, Infinity ou de membres JSON répétés.

Les dates sont normalisées en UTC à la microseconde ; une précision plus fine est tronquée. Le dashboard affiche ces instants en heure de Paris (Europe/Paris), avec passage automatique été/hiver. Le stockage, l’API et les bornes des filtres restent en UTC. Pas de date/heure sans fuseau ni de seconde intercalaire :60. Les caractères de contrôle sont interdits dans les identifiants et noms. Les relevés futurs sont acceptés mais n’apparaissent dans les agrégations qu’une fois leur date passée.

Précision des dépenses

coût = (input_price_per_million × input_tokens
      + output_price_per_million × output_tokens) / 1000000

Le serveur calcule et conserve ce montant exactement, sans flottant monétaire. Ne pas envoyer de champ cost : il serait refusé. Les totaux EUR et USD restent distincts. Le dashboard affiche en plus un total approximatif en euros : total EUR + total USD converti au dernier taux de référence de la BCE. Ce taux public est vérifié en arrière-plan toutes les 3 heures, sans clé ni abonnement. Il est généralement publié les jours ouvrés ; il ne s’agit pas d’un cours en temps réel ni d’une conversion historique. Le dernier taux connu est conservé en cas de panne et signalé comme ancien. Sans taux disponible, la conversion USD est indiquée comme indisponible. Aucun champ supplémentaire n’est à envoyer. Il s’agit d’une estimation au tarif fourni, pas d’une facture : pas de remises, taxes, cache ou facturation particulière déduits automatiquement. Si le tarif ou la consommation est inconnu, résoudre cette information avant d’envoyer ; ne pas inventer de prix ou remplacer une inconnue par zéro.

3. Exemples d’envoi

Un relevé

Enregistrer ce format dans metric.json, en remplaçant les valeurs d’illustration par les valeurs réelles :

{
  "event_id": "exemple-collecteur:2026-11-16T12:00:00Z:modele-exemple:USD",
  "date": "2026-11-16T12:00:00Z",
  "provider": "Fournisseur exemple",
  "model": "modele-exemple",
  "currency": "USD",
  "input_price_per_million": "0.150000000",
  "output_price_per_million": "0.600000000",
  "input_tokens": 12000,
  "output_tokens": 2500,
  "requests": 8
}

cURL

Fournir VIKIA_API_KEY via l’environnement sécurisé du collecteur, sans la coder en dur, l’afficher ou l’enregistrer dans ses journaux. Le fichier doit déjà contenir un relevé réel validé.

curl --silent --show-error --fail-with-body \
  --connect-timeout 5 --max-time 30 \
  --request POST 'https://vikia.lafougere.dev/api/metrics' \
  --header "Authorization: Bearer ${VIKIA_API_KEY:?Clé d’ingestion manquante}" \
  --header 'Content-Type: application/json' \
  --data-binary @metric.json

Python, sans bibliothèque supplémentaire

Cet exemple effectue un seul envoi et conserve les codes d’erreur. La stratégie de renvoi est décrite ci-dessous ; le fichier et son identifiant doivent rester identiques en cas de résultat incertain.

import json
import os
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

request = Request(
    "https://vikia.lafougere.dev/api/metrics",
    data=Path("metric.json").read_bytes(),
    headers={
        "Authorization": "Bearer " + os.environ["VIKIA_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urlopen(request, timeout=30) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print("HTTP", error.code, "Retry-After:", error.headers.get("Retry-After"))
    print(error.read().decode("utf-8", errors="replace"))
    raise SystemExit(1)
except (URLError, TimeoutError):
    raise SystemExit("Résultat incertain : conserver le même relevé pour le renvoi.")

Plusieurs relevés en une requête

Un lot contient de 1 à 500 relevés dans un objet {"metrics": [...]}, jamais un tableau seul. Ne pas ajouter d’autre champ à la racine. Envoyer le fichier du lot avec la même méthode et les mêmes en-têtes.

{
  "metrics": [
    {
      "event_id": "exemple-lot:2026-11-16:modele-a:USD",
      "date": "2026-11-16",
      "provider": "Fournisseur exemple",
      "model": "modele-a",
      "currency": "USD",
      "input_price_per_million": "0.15",
      "output_price_per_million": "0.60",
      "input_tokens": 1000,
      "output_tokens": 200,
      "requests": 2
    },
    {
      "event_id": "exemple-lot:2026-11-16:modele-b:USD",
      "date": "2026-11-16",
      "provider": "Fournisseur exemple",
      "model": "modele-b",
      "currency": "USD",
      "input_price_per_million": "1.25",
      "output_price_per_million": "5",
      "input_tokens": 500,
      "output_tokens": 100,
      "requests": 1
    }
  ]
}

4. Doublons, conflits et renvois

Stratégie conseillée au collecteur

  1. Découper la consommation en périodes non chevauchantes, avec un identifiant stable par relevé. Enregistrer localement les relevés en attente avant tout appel réseau.
  2. Sur 200 ou 201, vérifier le corps JSON ; inserted + duplicates doit correspondre au nombre de relevés envoyés, puis confirmer le lot localement.
  3. Sur 429, attendre le nombre de secondes indiqué par Retry-After, puis renvoyer le même lot. Sur coupure, timeout ou 5xx, le résultat peut être incertain : appliquer un délai croissant avec aléa et un nombre de tentatives borné, sans changer les identifiants ni le contenu.
  4. Sur 400, 401, 409, 413 ou 415, arrêter les renvois aveugles et résoudre la cause. Pour scinder un lot trop gros, conserver chaque identifiant.

5. Réponses et limites

201 : {"inserted": 1, "duplicates": 0}
200 : {"inserted": 0, "duplicates": 1}
409 : {"error": "event_id conflict"}
HTTPSignificationAction
201Au moins un nouvel ajout.Confirmer le lot, y compris ses doublons éventuels.
200Tous les relevés existaient déjà.Considérer le lot comme reçu, ne rien dupliquer.
400JSON, champs, formats ou limites de valeurs invalides.Corriger le collecteur. Le corps JSON contient un champ error.
401Clé absente ou incorrecte.Vérifier la clé d’ingestion et la forme exacte de l’en-tête Bearer.
405Méthode non autorisée.Utiliser POST, pas GET.
409Identifiant déjà associé à un contenu différent.Diagnostiquer sans créer un doublon. Aucun ajout partiel du lot.
413Corps trop volumineux.Scinder le lot ; conserver les identifiants.
415Content-Type non JSON.Utiliser application/json.
429Quota atteint.Respecter Retry-After, exprimé en secondes.
5xxErreur serveur ou proxy.Résultat potentiellement incertain : renvoi borné, identifiants inchangés.

Limites actuelles de l’ingestion : 500 relevés par lot, 1 048 576 octets (1 Mio) par corps HTTP, 120 requêtes par minute et par IP, et plafond global de 2 000 requêtes par minute. Les erreurs et tentatives sans clé comptent aussi dans les quotas. Un lot de 500 relevés compte comme une requête. Un lot trop nombreux est refusé en 400 ; un corps trop volumineux en 413.

Les réponses 429 de l’application incluent Retry-After, RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (délai en secondes). Les erreurs applicatives sont JSON ; un rejet par le proxy peut produire du texte ou du HTML, donc vérifier le Content-Type avant de décoder une erreur.

La clé d’ingestion autorise uniquement l’écriture, pas la lecture du dashboard. L’historique n’expire pas automatiquement. Le contrôle public GET https://vikia.lafougere.dev/healthz renvoie {"status":"ok"} ; il ne valide ni la clé ni un relevé. Aucun accès aux métriques n’est public et aucune route d’export ou de lecture par clé API n’est proposée.

6. API v2 : demandes et appels

POST https://vikia.lafougere.dev/api/v2/usage — même clé Bearer d’ingestion, uniquement en HTTPS, sans cookie ni redirection suivie. Les lectures et /usage nécessitent une session du tableau de bord ; la clé d’ingestion ne donne aucun droit de lecture.

Le corps contient exactement {"events": [...]} : 1 à 100 événements, 0 à 128 appels par événement, au plus 12 800 appels et 1 Mio par lot. Les quotas et réponses décrits plus haut s’appliquent aussi à cette route (par route). Les erreurs et essais non authentifiés comptent.

Champs obligatoires exacts de chaque événement : event_id, application, request_id, date, request_type, status, calls. Identifiants imprimables non vides : event_id et request_id ≤160 caractères, application ≤120. event_id est globalement unique en v2 ; request_id est unique par application. request_type vaut message, callback, command ou system ; status vaut success, error ou cancelled.

Champs obligatoires exacts de chaque appel : call_id, date, provider, model, currency, input_tokens, output_tokens, cost, cost_source, status, input_price_per_million, output_price_per_million. call_id est unique par application (≤160 caractères), provider ≤120, model ≤180, tous imprimables non vides. currency vaut EUR ou USD ; status vaut success, error ou unknown. Chaque tentative HTTP réelle du modèle est un appel, y compris une tentative facturée en échec, jamais un message Telegram.

Exemple illustratif uniquement, à ne jamais envoyer en production :

{
  "events": [{
    "event_id": "example-v2-event",
    "application": "example-app",
    "request_id": "example-v2-request",
    "date": "2026-11-16T11:00:00Z",
    "request_type": "message",
    "status": "error",
    "calls": [{
      "call_id": "example-v2-call",
      "date": "2026-11-16T11:00:01Z",
      "provider": "Example provider",
      "model": "example-model",
      "currency": "USD",
      "input_tokens": null,
      "output_tokens": null,
      "cost": null,
      "cost_source": "unavailable",
      "status": "unknown",
      "input_price_per_million": null,
      "output_price_per_million": null
    }]
  }]
}

Enregistrer les identifiants et le contenu avant le premier envoi. Même événement et contenu normalisé (dates, décimales, ordre des appels) : doublon. Un event_id modifié, une collision application/request_id ou application/call_id donne 409 et annule tout le lot. Sur 200/201, vérifier inserted + duplicates = nombre d’événements avant de confirmer localement ; sur erreur incertaine, renvoyer le même lot.

Compatibilité et lecture privée

/api/metrics et les totaux v1 restent inchangés : estimations historiques non attribuées uniquement. Ne pas envoyer la même consommation aux deux versions. Aucun ancien coût réel ni coût n8n n’est reconstruit ou importé. /usage présente séparément les demandes v2, filtrables par application, et le détail fournisseur/modèle de chaque tentative, avec montants déclarés, estimés et indisponibles distincts. Les totaux v1 ne sont jamais ajoutés aux totaux v2, ni les EUR aux USD. Les conversions d’affichage ne changent pas les montants d’origine.

Lectures de session : GET /api/v2/dashboard?range=30d&application=example-app, GET /api/v2/requests?range=all&limit=50&offset=0, GET /api/v2/request?event_id=example-v2-event. Périodes : 24h, 7d, 30d, month, year, all ; bornes UTC, fin exclue. limit 1..100, offset 0..10^9. Les coûts et compteurs de consommation sont des chaînes exactes en lecture ; null reste inconnu dans les appels. Les données ne sont jamais publiques.