GET /billing/usage

L’endpoint billing/usage te retourne la consommation du mois calendaire courant pour un tenant donné. C’est ce que le dashboard utilise pour afficher la jauge “X / Y tickets utilisés” et estimer la prochaine facture.

GET https://actero.fr/api/billing/usage?client_id=<id>

Authentification

Authorization: Bearer <jwt> ou Bearer <ak_…>. L’utilisateur doit être :

Admin Actero (équipe interne, accès à tous les tenants), ou
Membre du client_id (présent dans la table client_users).

Sinon → 403 Acces refuse.

Query params

string

required

ULID du tenant. Si absent → 400 Missing client_id.

Headers

Header	Valeur	Requis
`Authorization`	`Bearer <token>`	Oui

Response — `200 OK`

{
  "plan": "pro",
  "period": "2026-04",
  "tickets_used": 1247,
  "tickets_limit": 5000,
  "voice_minutes_used": 38,
  "voice_minutes_limit": 0,
  "overage_tickets": 0,
  "overage_cost": 0,
  "trial_ends_at": null,
  "next_billing_date": "2026-05-01"
}

enum

free, starter, pro, enterprise. Lu depuis clients.plan.

string

Mois calendaire au format YYYY-MM. Tous les compteurs ci-dessous sont strictement sur ce mois — ils repassent à 0 le 1er du mois suivant.

integer

Nombre de tickets traités par l’agent ce mois (passage Brain + Executor, peu importe le résultat).

integer

Quota du plan. Vaut -1 si illimité (Enterprise).

number

Minutes consommées par l’agent vocal. Toujours 0 — l’agent vocal n’est pas encore disponible.

number

Quota minutes vocales du plan. Toujours 0 tant que l’agent vocal n’est pas lancé.

integer

Déprécié — toujours 0. Aucun plan ne facture de dépassement (plafond strict).

number

Déprécié — toujours 0.

boolean

true quand le quota mensuel est atteint : l’agent est en pause jusqu’à l’achat de crédits ou un upgrade.

integer

Crédits disponibles. Consommés automatiquement (1 crédit = 1 ticket) au-delà du quota.

string|null

ISO timestamp de fin de période d’essai. null si le tenant n’est pas en trial.

string

Date approximative de prochain prélèvement Stripe (1er du mois suivant). Format YYYY-MM-DD.

Response — autres cas

`400 Bad Request`

{ "error": "Missing client_id" }

`401 Unauthorized`

{ "error": "Non autorise." }

`403 Forbidden`

{ "error": "Acces refuse." }

`404 Not Found`

{ "error": "Client introuvable." }

`405 Method Not Allowed`

Cet endpoint accepte uniquement GET. Tout autre verbe renvoie 405.

`500 Internal Server Error`

{ "error": "Erreur interne." }

Dépassement de quota

Plan	Tickets inclus	Au-delà du quota
Free	50	Bloqué (crédits/upgrade)
Starter	1 000	Bloqué (crédits/upgrade)
Pro	5 000	Bloqué (crédits/upgrade)
Enterprise	Illimité	—

Les price_ids Stripe ne sont pas exposés via l’API publique — ils restent server-side. Aucun dépassement n’est facturé : surveille quota_reached et credits_balance pour savoir si l’agent est en pause.

Exemples

curl "https://actero.fr/api/billing/usage?client_id=$ACTERO_CLIENT_ID" \
  -H "Authorization: Bearer $ACTERO_API_KEY"

const url = new URL('https://actero.fr/api/billing/usage')
url.searchParams.set('client_id', process.env.ACTERO_CLIENT_ID)

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ACTERO_API_KEY}` },
})
const usage = await res.json()

const pct = (usage.tickets_used / usage.tickets_limit) * 100
console.log(`${usage.tickets_used}/${usage.tickets_limit} tickets (${pct.toFixed(1)}%)`)

if (usage.quota_reached) {
  console.warn(`Quota atteint — agent en pause. Crédits restants : ${usage.credits_balance}`)
}

import os, requests

res = requests.get(
    "https://actero.fr/api/billing/usage",
    params={"client_id": os.environ["ACTERO_CLIENT_ID"]},
    headers={"Authorization": f"Bearer {os.environ['ACTERO_API_KEY']}"},
)
usage = res.json()

if usage["tickets_limit"] != -1:
    pct = usage["tickets_used"] / usage["tickets_limit"] * 100
    print(f"{usage['tickets_used']}/{usage['tickets_limit']} tickets ({pct:.1f}%)")

Polling vs webhook

Pour suivre la consommation en temps réel sans poller cet endpoint en continu, abonne-toi à l’événement usage.threshold_reached via un webhook sortant. Tu reçois un POST quand le tenant franchit 80 % puis 100 % de son quota mensuel — utile pour :

Notifier l’équipe finance avant le hard cap (Free).
Déclencher un upgrade automatique côté ton CRM.
Pause-r ton crawl/import si tu sais que chaque event = 1 ticket.

Rate limit

60 requêtes / minute / user. Largement suffisant pour un polling raisonnable (1× par heure suffit dans 99 % des cas).

Référence

Endpoints

GET /billing/usage

Authentification

Query params

Headers

Response — `200 OK`

Response — autres cas

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`405 Method Not Allowed`

`500 Internal Server Error`

Dépassement de quota

Exemples

Polling vs webhook

Rate limit

​Authentification

​Query params

​Headers

​Response — 200 OK

​Response — autres cas

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​405 Method Not Allowed

​500 Internal Server Error

​Dépassement de quota

​Exemples

​Polling vs webhook

​Rate limit

Authentification

Query params

Headers

Response — `200 OK`

Response — autres cas

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`405 Method Not Allowed`

`500 Internal Server Error`

Dépassement de quota

Exemples

Polling vs webhook

Rate limit