Démarrage rapide de l'API

Ce guide vous accompagne dans l’API de Metronome pour configurer la facturation par programmation — depuis la création de votre première métrique facturable jusqu’à la visualisation d’une facture fonctionnelle. Vous cherchez le guide de l’interface utilisateur ? Si vous préférez configurer la facturation via le tableau de bord Metronome, consultez le démarrage rapide de l’interface utilisateur.

Prérequis

Un compte sandbox Metronome (inscrivez-vous ici)
Votre jeton d’API sandbox Metronome (Connexions → Jetons d’API et webhooks dans le tableau de bord)

Environnements et authentification

L’environnement est entièrement déterminé par votre jeton d’API. Un jeton sandbox ne fonctionne qu’avec les données sandbox ; un jeton de production ne fonctionne qu’avec les données de production. Toutes les requêtes nécessitent un jeton Bearer.

Étape 1 : Comprendre comment les pièces s’assemblent

Avant de construire quoi que ce soit, voici comment les objets centraux de Metronome se connectent :

Metronome sépare la mesure (ce que vous mesurez) de la tarification (ce que vous facturez). Vous pouvez changer la tarification sans changer votre instrumentation d’événements, et vice versa. Voici ce que fait chaque objet :

Événements d’utilisation — Enregistrements bruts de l’activité du client envoyés à Metronome (par exemple, « le client X a utilisé 1 500 tokens d’entrée sur le modèle gpt-5 à l’horodatage Z »)
Métriques facturables — Règles qui agrègent vos événements en quantités facturables (par exemple, « somme de la propriété input_tokens pour les événements de type llm_request »). C’est également là où vous définissez les clés de groupe — les propriétés que vous utiliserez pour tarifer ou afficher sur les factures.
Produits — Postes nommés sur une facture.
Cartes tarifaires — Un livre de prix centralisé attribuant un prix à chaque produit. Une seule carte tarifaire peut être partagée entre de nombreux clients, ce qui facilite le déploiement des mises à jour de tarification.
Contrats — Accords spécifiques au client référençant une carte tarifaire, définissant la période de facturation et incluant optionnellement des crédits, engagements ou remplacements.
Packages — Encode votre carte tarifaire et les détails du contrat dans un seul package à appliquer à de nouveaux clients.
Factures — Générées automatiquement à chaque période de facturation en fonction des frais récurrents et de l’utilisation d’un client, tarifées par rapport au contrat.

Ce que vous devez créer (dans cet ordre) :

Une métrique facturable
Un produit
Une carte tarifaire avec des taux pour chaque produit
Un client
Un contrat reliant le client à la carte tarifaire

Ensuite, vous envoyez des événements et Metronome s’occupe du reste.

Étape 2 : Concevoir votre schéma d’événements

Avant de créer quoi que ce soit, décidez à quoi ressemblent vos événements d’utilisation. Chaque événement envoyé à Metronome a cette structure :

{
  "transaction_id": "2026-03-09T14:30:00Z_req_abc123",
  "customer_id": "your-customer-uuid-in-metronome",
  "event_type": "llm_request",
  "timestamp": "2026-03-09T14:30:00Z",
  "properties": {
    "model": "gpt-5",
    "input_tokens": "1500",
    "output_tokens": "350",
    "provider": "openai",
    "region": "us-east-1",
    "user_id": "user_8f3a",
    "cost": "0.0042"
  }
}

Champs requis

transaction_id — Unique par événement pour l’idempotence. Si le même transaction_id est envoyé deux fois, Metronome déduplique. Conseil : combinez horodatage + ID de requête.
customer_id — UUID du client Metronome, ou un ingest_alias configuré sur le client (afin que vous puissiez utiliser votre propre ID interne).
event_type — Chaîne reliant cet événement à une métrique facturable. Doit correspondre exactement aux in_values du event_type_filter de la métrique facturable.
timestamp — Format ISO 8601. Doit être dans les 34 derniers jours (fenêtre de rétrodatation de Metronome). Les événements futurs sont rejetés.

Propriétés (dépendantes de la métrique)

properties — Paires clé-valeur. Toutes les valeurs doivent être des chaînes (même les nombres) — Metronome utilise des décimales de précision arbitraire en interne pour éviter les problèmes de virgule flottante. Metronome prend également en charge jusqu’à 2 000 propriétés par événement.

Les propriétés servent à trois fins :

Agrégation — La valeur que vous additionnez, comptez ou maximisez (par exemple, input_tokens, duration_seconds)
Clés de groupe — Dimensions pour la tarification (par exemple, model, region) ou l’affichage de facture (par exemple, user_id, project_id). Doivent être définies sur la métrique facturable au préalable.
Métadonnées — Contexte pour les clients, analyse COGS, ou anticipation (par exemple, provider, cost, endpoint)

Envoyez plus de propriétés que vous ne pensez en avoir besoin. Vous pouvez toujours ignorer les propriétés inutilisées, mais vous ne pouvez pas ajouter rétroactivement des clés de groupe à une métrique facturable.

Schémas d’événements courants

Cas d’usage	`event_type`	Propriétés clés
API IA/LLM	`llm_request`	`model`, `input_tokens`, `output_tokens`, `provider`, `user_id`, `cost`
API générique	`api_call`	`endpoint`, `method`, `response_code`, `user_id`
Calcul	`compute_usage`	`instance_type`, `duration_seconds`, `region`, `user_id`
Stockage	`storage_snapshot`	`storage_gb`, `tier`, `user_id`
Sièges/Licences	`active_seat`	`user_id`, `role`, `plan`

Pour plus de schémas, consultez Schémas de conception d’événements.

Étape 3 : Créer une métrique facturable

Référence API : Créer une métrique facturable

Exemple — Compter les appels API (simple) :

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "aggregation_type": "count",
    "event_type_filter": {
      "in_values": ["api_call"]
    }
  }'

Exemple — Somme des tokens avec clés de groupe :

curl -X POST https://api.metronome.com/v1/billable-metrics/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "aggregation_type": "sum",
    "aggregation_key": "input_tokens",
    "event_type_filter": {
      "in_values": ["llm_request"]
    },
    "property_filters": [
      { "name": "model", "exists": true },
      { "name": "input_tokens", "exists": true },
      { "name": "user_id", "exists": true }
    ],
    "group_keys": [["model"], ["user_id"]]
  }'

Types d’agrégation

count | sum | unique | max | latest

count — Nombre d’événements correspondants (appels API, requêtes)
sum — Somme d’une propriété numérique (tokens, octets, secondes)
max — Valeur maximale dans une fenêtre (stockage de pointe, connexions simultanées)

Clés de groupe

Les clés de groupe déterminent ce que vous tarifez et affichez sur les factures. Elles fonctionnent comme GROUP BY en SQL. Définissez-les ici — elles ne peuvent pas être ajoutées plus tard. Pour les métriques facturables streaming, les propriétés utilisées comme clés de groupe doivent apparaître dans property_filters avec "exists": true.

Clé de groupe	Utilisation en aval	Exemple
`model`	Clé de groupe de tarification	Prix différent par modèle IA
`region`	Clé de groupe de tarification	Prix différent par région
`instance_type`	Clé de groupe de tarification	Prix différent par GPU
`user_id`	Clé de groupe de présentation	Ventilations de facture par utilisateur
`project_id`	Clé de groupe de présentation	Ventilations de facture par projet

Métriques facturables SQL

Pour des calculs complexes (moyennes quotidiennes, facturation basée sur des percentiles, formules pondérées), utilisez des métriques facturables SQL. Toute colonne renvoyée par votre requête SQL en dehors de value peut être utilisée comme clé de groupe. En savoir plus →

Les métriques facturables sont immuables après la créationVous ne pouvez pas ajouter ou modifier les clés de groupe, les filtres de propriétés ou les paramètres d’agrégation. Incluez les clés de groupe pour toute dimension par laquelle vous pourriez tarifer ou afficher à l’avenir.

Exemple — utilisateurs uniques par région :

SELECT count(DISTINCT properties.user_id) as value,
       properties.region
FROM events
WHERE event_type = 'api_request'
GROUP BY properties.region

Ici, region est renvoyé comme colonne et peut être utilisé comme clé de groupe de tarification sur le produit.

Étape 4 : Créer un produit

Référence API : Créer un produit

Exemple — Produit d’utilisation avec clés de groupe :

curl -X POST https://api.metronome.com/v1/contract-pricing/products/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Input Tokens",
    "type": "usage",
    "billable_metric_id": "<your-billable-metric-id>",
    "pricing_group_key": ["model"],
    "presentation_group_key": ["user_id"]
  }'

Types de produits

usage — Tarifé de manière variable en fonction de l’utilisation du client (nécessite une métrique facturable)
subscription — Frais récurrents selon un calendrier (frais de plateforme, licences de sièges)
composite — Frais en pourcentage sur un produit d’utilisation
fixed — Frais ponctuels ou planifiés (engagements, crédits, frais ponctuels)

Attribution des clés de groupe

Je veux…	Champ	Notes
Prix différents par valeur de dimension	`pricing_group_key`	Chaque valeur obtient sa propre entrée de taux sur la carte tarifaire
Ventilations par poste sur la facture (même taux)	`presentation_group_key`	Regroupe les postes par cette dimension
Un prix fixe	Ne définissez ni l’un ni l’autre	Facturation simple

Les clés de groupe sur le produit doivent être un sous-ensemble des clés de groupe sur la métrique facturable sous-jacente. (Conversions optionnelles) Ajoutez une conversion de quantité — par exemple, envoyez des tokens individuels mais affichez et tarifez par million de tokens sur la facture. Ajoutez une conversion d’arrondi — par exemple, envoyez des secondes mais arrondissez et affichez à la minute la plus proche sur la facture.

Étape 5 : Créer une carte tarifaire

Référence API : Créer une carte tarifaire Bonne pratique : utilisez une carte tarifaire centralisée partagée entre les clients. Les mises à jour de taux se propagent à tous les contrats référents.

Créer la carte tarifaire :

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Standard Pricing"}'

Ajouter des taux :

curl --request POST \
  --url https://api.metronome.com/v1/contract-pricing/rate-cards/addRates \
  --header 'Authorization: Bearer $METRONOME_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '
{
  "rate_card_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",
  "rates": [
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 100,
      "pricing_group_values": {
        "region": "us-west-2",
        "cloud": "aws"
      }
    },
    {
      "product_id": "13117714-3f05-48e5-a6e9-a66093f13b4d",
      "starting_at": "2020-01-01T00:00:00.000Z",
      "entitled": true,
      "rate_type": "FLAT",
      "price": 120,
      "pricing_group_values": {
        "region": "us-east-2",
        "cloud": "aws"
      }
    }
  ]
}
'

Ajouter une tarification dimensionnelle (une entrée par valeur) :

curl -X POST https://api.metronome.com/v1/contract-pricing/rate-cards/rates/add \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_card_id": "<your-rate-card-id>",
    "product_id": "<your-product-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "rate_type": "flat",
    "price": 1.50,
    "entitled": true,
    "pricing_group_values": {
      "model": "gpt-5"
    }
  }'

Répétez avec différentes pricing_group_values pour chaque valeur de dimension (par exemple, gpt-5-mini à $0,30).

Fonctionnalités supplémentaires

Tarification par paliers — Paliers basés sur le volume via le champ tiers sur une entrée de taux
Unités de tarification personnalisées — Créez sous Offre → Unités de tarification dans l’interface utilisateur, puis référencez le credit_type_id sur la carte tarifaire pour la facturation basée sur les crédits. En savoir plus →
Taux d’engagement — Taux qui s’appliquent spécifiquement au tirage sur les engagements prépayés

Étape 6 : Créer un client et un contrat

Créer un client :

Référence API : Créer un client

curl -X POST https://api.metronome.com/v1/customers/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Customer",
    "ingest_aliases": ["my-internal-customer-id"]
  }'

Le champ ingest_aliases vous permet d’envoyer des événements indexés sur votre propre identifiant interne de client au lieu de l’UUID de Metronome. Vous pouvez mapper des sous-organisations à un seul client en utilisant plusieurs alias.

Créer un contrat :

Référence API : Créer un contrat

curl -X POST https://api.metronome.com/v1/contracts/create \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<your-customer-id>",
    "rate_card_id": "<your-rate-card-id>",
    "starting_at": "2026-03-01T00:00:00Z",
    "usage_statement_schedule": {
      "frequency": "MONTHLY"
    }
  }'

Cela crée un contrat sans fournisseur de facturation — les factures seront générées dans Metronome et visibles dans le tableau de bord. Pour que les factures soient automatiquement envoyées à Stripe, ajoutez billing_provider_configuration :

"billing_provider_configuration": {
  "billing_provider": "stripe",
  "delivery_method": "direct_to_billing_provider"
}

Pour la configuration complète de Stripe (connexion au niveau du compte, configuration de facturation client, etc.), consultez le guide d’intégration Stripe.

Étape 7 : Envoyer vos premiers événements

Référence API : Ingérer des événements Regroupez jusqu’à 100 événements par requête. Metronome prend en charge environ 6,6 millions d’événements par minute avec le batching.

curl -X POST https://api.metronome.com/v1/ingest \
  -H "Authorization: Bearer $METRONOME_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
    "transaction_id": "test-001",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:00:00Z",
    "properties": {
      "model": "gpt-5",
      "input_tokens": "1500",
      "user_id": "user_1"
    }
  },
  {
    "transaction_id": "test-002",
    "customer_id": "<your-customer-id>",
    "event_type": "llm_request",
    "timestamp": "2026-03-09T12:01:00Z",
    "properties": {
      "model": "gpt-5-mini",
      "input_tokens": "800",
      "user_id": "user_2"
    }
  }]'

Comportements importants

Une réponse 200 signifie que les événements ont été acceptés pour ingestion. Vérifiez le corps de la réponse pour les erreurs par événement.
Notez que s’il n’y a pas de métrique facturable correspondante pour l’event_type ou si les propriétés requises ne sont pas incluses, les événements sont stockés mais peuvent ne pas apparaître dans les calculs d’utilisation. Assurez-vous de créer les métriques facturables avant d’envoyer des événements s’ils sont nécessaires pour la tarification.
Les événements peuvent être rétrodatés jusqu’à 34 jours. Les événements avec des horodatages futurs sont rejetés.
transaction_id est utilisé pour la déduplication. Envoyer le même ID deux fois ne facturera pas deux fois.
Seuls les événements du point de terminaison ingest sont mesurés. Les appels API pour gérer les clients, contrats, etc. ne sont pas facturables.

Vérifier vos événements

Accédez à Connexions → Événements dans le tableau de bord. Recherchez par transaction_id. Cliquez sur un événement individuel pour voir s’il correspond à une métrique facturable et à un client — c’est le diagnostic le plus rapide. Actualisez la page si les événements n’apparaissent pas immédiatement. Le « nombre total d’événements » agrégé peut être en retard.

Dépannage

Cliquez sur l’événement sur la page Événements — vérifiez qu’il correspond à une BM et à un client.
Vérifiez la réponse de l’API de votre appel ingest pour les erreurs par événement.
Si les événements correspondent à une BM + client mais n’apparaissent pas sur la facture : les valeurs de clés de groupe de tarification dans l’événement ne correspondent probablement à aucun taux sur la carte tarifaire. Par exemple, "model": "gpt-5" vs "model": "gpt5" (trait d’union manquant) échouera silencieusement à la tarification.
Vérifiez votre jeton d’API est pour le sandbox (pas la production, ou vice versa).

Étape 8 : Vérifier votre facture

Accédez à Clients → [Votre client] → Factures dans le tableau de bord. La facture brouillon devrait montrer votre utilisation et vos frais. Cycle de vie de la facture :

Brouillon — Accumule l’utilisation tout au long de la période de facturation (visible dans Metronome)
Finalisé — Verrouillé à la fin de la période de facturation. Il y a une période de grâce de 24 heures à la fin de la période de facturation avant que les factures ne soient finalisées pour apporter toute modification nécessaire à une facture.
Envoyé au fournisseur de facturation — Si Stripe est connecté, poussé dans environ une heure après la finalisation. Statut de paiement géré dans le tableau de bord de Stripe.
Payé / Échoué — Recouvrement géré par votre fournisseur de facturation

Vérifiez que la facture brouillon affiche des quantités et des frais d’utilisation corrects en fonction de votre ingestion d’événements et de la tarification de la carte tarifaire. Si vous voyez de l’utilisation (sous Connexions) mais aucun frais sur la facture, vérifiez que vos événements correspondent aux valeurs de clés de groupe de tarification sur votre carte tarifaire.

Prêt pour plus ?

Tableaux de bord client intégrables — Visibilité en libre-service de l’utilisation pour vos clients
Webhooks — Cycle de vie des factures, alertes de solde, événements de paiement
Alertes et notifications — Seuils de dépense, notifications de solde
Crédits et engagements — Soldes prépayés, engagements entreprise
Intégration Stripe — Recouvrement automatisé des paiements
Reconnaissance des revenus — ASC 606 / IFRS 15
Liste de vérification de production — Quand vous êtes prêt à passer en production (nouveau jeton d’API, même URL de base, clés Stripe live)

DÉMARRER

IMPLÉMENTER METRONOME

ÉVÉNEMENTS

TARIFICATION ET PACKAGING

CLIENTS ET FACTURATION

FACTURATION

RAPPORTS ET ANALYSES

CONFIGURATION DE LA PLATEFORME

Démarrage rapide de l'API

Prérequis

Environnements et authentification

Étape 1 : Comprendre comment les pièces s’assemblent

Étape 2 : Concevoir votre schéma d’événements

Champs requis

Propriétés (dépendantes de la métrique)

Schémas d’événements courants

Étape 3 : Créer une métrique facturable

Exemple — Compter les appels API (simple) :

Exemple — Somme des tokens avec clés de groupe :

Types d’agrégation

Clés de groupe

Métriques facturables SQL

Étape 4 : Créer un produit

Exemple — Produit d’utilisation avec clés de groupe :

Types de produits

Attribution des clés de groupe

Étape 5 : Créer une carte tarifaire

Créer la carte tarifaire :

Ajouter des taux :

Ajouter une tarification dimensionnelle (une entrée par valeur) :

Fonctionnalités supplémentaires

Étape 6 : Créer un client et un contrat

Créer un client :

Créer un contrat :

Étape 7 : Envoyer vos premiers événements

Comportements importants

Vérifier vos événements

Dépannage

Étape 8 : Vérifier votre facture

Prêt pour plus ?

​Prérequis

​Environnements et authentification

​Étape 1 : Comprendre comment les pièces s’assemblent

​Étape 2 : Concevoir votre schéma d’événements

​Champs requis

​Propriétés (dépendantes de la métrique)

​Schémas d’événements courants

​Étape 3 : Créer une métrique facturable

​Exemple — Compter les appels API (simple) :

​Exemple — Somme des tokens avec clés de groupe :

​Types d’agrégation

​Clés de groupe

​Métriques facturables SQL

​Étape 4 : Créer un produit

​Exemple — Produit d’utilisation avec clés de groupe :

​Types de produits

​Attribution des clés de groupe

​Étape 5 : Créer une carte tarifaire

​Créer la carte tarifaire :

​Ajouter des taux :

​Ajouter une tarification dimensionnelle (une entrée par valeur) :

​Fonctionnalités supplémentaires

​Étape 6 : Créer un client et un contrat

​Créer un client :

​Créer un contrat :

​Étape 7 : Envoyer vos premiers événements

​Comportements importants

​Vérifier vos événements

​Dépannage

​Étape 8 : Vérifier votre facture

​Prêt pour plus ?

Prérequis

Environnements et authentification

Étape 1 : Comprendre comment les pièces s’assemblent

Étape 2 : Concevoir votre schéma d’événements

Champs requis

Propriétés (dépendantes de la métrique)

Schémas d’événements courants

Étape 3 : Créer une métrique facturable

Exemple — Compter les appels API (simple) :

Exemple — Somme des tokens avec clés de groupe :

Types d’agrégation

Clés de groupe

Métriques facturables SQL

Étape 4 : Créer un produit

Exemple — Produit d’utilisation avec clés de groupe :

Types de produits

Attribution des clés de groupe

Étape 5 : Créer une carte tarifaire

Créer la carte tarifaire :

Ajouter des taux :

Ajouter une tarification dimensionnelle (une entrée par valeur) :

Fonctionnalités supplémentaires

Étape 6 : Créer un client et un contrat

Créer un client :

Créer un contrat :

Étape 7 : Envoyer vos premiers événements

Comportements importants

Vérifier vos événements

Dépannage

Étape 8 : Vérifier votre facture

Prêt pour plus ?