Documentation développeur•stable•Mis à jour 2026-07-08

Ingestion directe

Envoyer des événements d’usage IA normalisés à Kadryn sans router le trafic provider via Gateway.

L’ingestion directe permet à votre backend ou pipeline d’envoyer des événements d’usage IA à Kadryn après l’exécution provider.

Utilisez-la lorsque Kadryn n’est pas dans le chemin runtime de la requête, mais doit tout de même fournir visibilité des coûts, allocation, reporting et santé des données.

Quand utiliser l’ingestion directe

Utilisez l’ingestion directe lorsque :

votre application appelle les providers directement;
une autre gateway ou proxy gère déjà le trafic runtime;
vous devez backfiller de l’usage historique;
les exports provider sont traités par un worker;
vous voulez de la visibilité des coûts avant d’adopter Gateway;
le blocage runtime n’est pas requis.

Utilisez Gateway plutôt lorsque Kadryn doit appliquer policies avant exécution provider.

Endpoint de requête

POST https://api.kadryn.com/v1/usage/events

Authentification

Authorization: Bearer $KADRYN_API_KEY
Content-Type: application/json

Utilisez une clé API Kadryn côté serveur.

Événement minimal

curl "$KADRYN_API_BASE_URL/usage/events" \
  -H "Authorization: Bearer $KADRYN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: usage-event-001" \
  -d '{
    "timestamp": "2026-07-06T12:00:00.000Z",
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "inputTokens": 1200,
    "outputTokens": 300,
    "costCents": "4",
    "project": "prod-api",
    "feature": "support-agent",
    "environment": "prod"
  }'

Champs d’événement recommandés

Champ	Description
`timestamp`	Moment où la requête provider a eu lieu.
`provider`	provider IA.
`model`	Nom du modèle utilisé par la requête.
`inputTokens`	Nombre de tokens en entrée.
`outputTokens`	Nombre de tokens en sortie.
`costCents`	Coût en centimes, encodé comme chaîne.
`project`	Slug ou ID du projet.
`feature`	Feature, workflow ou agent.
`environment`	Environnement runtime.
`traceId`	Identifiant de trace si disponible.
`requestGroupId`	Regroupe les événements liés dans une opération métier.

Valeurs de coût

Envoyez les coûts en centimes sous forme de chaînes.

Bon :

{
  "costCents": "4"
}

Évitez les valeurs de coût en nombres flottants :

{
  "costUsd": 0.04
}

Les centimes sous forme de chaînes évitent les problèmes d’arrondi et s’alignent avec le modèle de coût interne de Kadryn.

Idempotence

Chaque événement retryable doit utiliser une idempotency key stable.

-H "Idempotency-Key: usage-event-prod-api-2026-07-06-001"

Utilisez la même clé lorsque vous retryez le même événement logique.

Ne générez pas une nouvelle clé à chaque retry.

Batchs

Si votre worker envoie beaucoup d’événements, préférez de petits batchs bornés.

Pattern recommandé :

gardez des batchs assez petits pour être retryés en sécurité;
utilisez une idempotency key de batch;
incluez des IDs source stables par événement lorsque possible;
logguez les comptes acceptés et rejetés;
retryez seulement les erreurs retryables.

Valider l’ingestion

Ouvrir :

Developers → Logs & Traces

Filtrez ensuite par :

source;
provider;
model;
projet;
environnement;
tentatives invalides;
tentatives rejetées;
événements synthétiques.

Utilisez Diagnostics si les événements acceptés n’apparaissent pas dans Costs.

Échecs fréquents

Échec	Cause	Correction
Erreur d’authentification	Clé API Kadryn manquante ou invalide.	Vérifiez `Authorization`.
Erreur de validation	Payload invalide ou forme de champ non prise en charge.	Corrigez le schéma de l’événement.
Événement dupliqué	Même idempotency key ou provider request ID réutilisé incorrectement.	Vérifiez idempotency logique.
Coût manquant	Aucun coût ou métadonnée de pricing.	Envoyez `costCents` ou assurez la couverture de pricing.
Coût non alloué	Métadonnées projet, feature ou owner manquantes.	Améliorez les métadonnées.