Lire ses consommations par jour, numéro ou projet

Avant de commencer

Une clé de test fictive : tq_test_EXEMPLE.
Une période : deux dates au format AAAA-MM-JJ.
Le regroupement voulu : day, number, project, country ou service.

Version de démonstration. Conception susceptible d’évoluer. Les données renvoyées sont simulées, aucune API de production n’est ouverte.

Interroger la consommation

Appelez GET /usage avec from et to, les bornes de la période.
Ajoutez group_by pour choisir l’axe de lecture : jour, numéro, projet, pays ou service.
Lisez le champ provisional. Il passe à true quand des événements peuvent encore arriver en retard : le total n’est alors pas définitif.

Exemple fictif : lecture par jour sur un mois de démonstration.

curl "https://api.example.test/v1/usage?from=2026-10-01&to=2026-10-31&group_by=day" \
  -H "Authorization: Bearer tq_test_EXEMPLE"

Exemple de réponse

Chaque ligne donne une clé de regroupement (key), un service, un sens, une unité et une quantité. Les unités changent selon le service : durée pour la voix, segments pour les SMS. Ne les additionnez pas entre elles.

Exemple fictif de réponse. Valeurs inventées, sans montant.

{
  "data": [
    { "key": "2026-10-01", "service": "voice", "direction": "outbound", "unit": "second", "quantity": 5400 },
    { "key": "2026-10-01", "service": "sms", "direction": "outbound", "unit": "segment", "quantity": 120 }
  ],
  "provisional": false
}

Points de vigilance

Un appel peut générer plusieurs lignes de consommation, par exemple quand il comporte plusieurs segments techniques. Une ligne n’est pas toujours un appel.
Un SMS long compte plusieurs segments : la quantité SMS est un nombre de segments, pas un nombre de messages.
Séparez le sens entrant et le sens sortant : les unités et les règles contractuelles peuvent différer.
La durée facturable (billable_seconds dans le journal d’appels) n’est pas la durée de sonnerie ni forcément la durée de conversation.
La réponse porte des quantités. Les montants, quand ils existent, relèvent de votre contrat et s’affichent dans la console.

Erreurs fréquentes

Symptôme	Cause probable	Que faire
400 invalid_request	Date mal formée, from postérieure à to, group_by inconnu.	Utilisez AAAA-MM-JJ et l’une des valeurs listées.
Total qui change entre deux lectures	provisional est à true : des événements arrivent encore.	Relisez plus tard pour une période close.
Écart avec le journal d’appels	Unités différentes (secondes de consommation et durée de conversation).	Comparez sur la même unité et le même sens.

Ce que ce guide ne fait pas

Il ne calcule aucun coût : aucun tarif n’est public, tout est sur devis.
Il ne remplace pas le rapprochement avec les documents contractuels et la facturation.
Il ne prétend pas que des volumes réels existent : l’exemple est fictif.

Décrire votre volume dans une demande de devis API voix