Utilisation

Deux endpoints pour voir ce que votre boutique a consommé et estimer ce dont vous aurez besoin le mois prochain.

GET /v1/usage

Mois calendaire courant, groupé par type d'endpoint.

Auth : clé plateforme avec usage:read.

Réponse 200

{
  "data": {
    "period": "2026-04",
    "tier":   "pro_plus",
    "usage": {
      "request": { "total": 31, "billable": 0 },
      "signup":  { "total": 3,  "billable": 2 },
      "event":   { "total": 0,  "billable": 0 },
      "webhook": { "total": 0,  "billable": 0 }
    },
    "limits": {
      "requests_per_month":  5000000,
      "signups_per_month":   50000,
      "webhooks_per_month":  500000,
      "requests_per_minute": 1200
    }
  }
}

Référence des champs

Champ	Signification
period	Toujours YYYY-MM. Reset le 1er de chaque mois à 00:00 UTC.
tier	Votre tier de limite de taux actuel.
usage.<group>.total	Toutes les requêtes du groupe, y compris doublons / rejets.
usage.<group>.billable	Seulement les requêtes facturables (par ex. les inscriptions doublon ne facturent pas).
limits	Limites effectives — tier_limits surchargé par d'éventuels overrides par boutique. -1 = illimité.

Groupes d'endpoints

Groupe	Ce qui compte
request	Chaque appel API authentifié avec succès.
signup	Chaque appel /v1/signups. Les doublons comptent dans total mais pas billable.
event	Chaque appel /v1/events.
webhook	Chaque tentative de livraison d'un webhook sortant (succès ou 4xx ; chaque retry 5xx compte).

GET /v1/usage/history

Agrégats horaires sur une plage de dates — utile pour graphiques et analyse de tendance.

Auth : clé plateforme avec usage:read.

Paramètres de requête

Param	Type	Défaut	Notes
from	ISO date	il y a 7 jours	Inclus
to	ISO date	maintenant	Exclus

Plage maximale : 90 jours.

Requête

curl 'https://api.dzbuild.app/v1/usage/history?from=2026-04-01&to=2026-05-01' \
  -H "Authorization: Bearer $DZ_KEY"

Réponse 200

{
  "data": {
    "from": "2026-04-01T00:00:00+00:00",
    "to":   "2026-05-01T00:00:00+00:00",
    "rows": [
      { "period_hour": "2026-04-30 19:00:00", "endpoint_group": "request", "count": 26, "billable_count": 0 },
      { "period_hour": "2026-04-30 20:00:00", "endpoint_group": "request", "count": 5,  "billable_count": 0 },
      { "period_hour": "2026-04-30 20:00:00", "endpoint_group": "signup",  "count": 3,  "billable_count": 2 }
    ]
  }
}

Les lignes sont retournées par period_hour ascendant. Les heures sans usage dans un groupe sont omises (sparse).

Conseils de visualisation

• Agrégats journaliers : groupez par LEFT(period_hour, 10) (préfixe de date).
• Aire empilée : groupez par endpoint_group, puis par heure sur l'axe X.
• Vitesse de consommation du quota : divisez signup.billable_count cumulé par la fraction écoulée du mois, projetez à la fin du mois.

Exemple Python simple :

import collections, datetime, requests, os

r = requests.get('https://api.dzbuild.app/v1/usage/history',
    params={'from': '2026-04-01', 'to': '2026-05-01'},
    headers={'Authorization': f"Bearer {os.environ['DZ_KEY']}"})
rows = r.json()['data']['rows']

by_day = collections.defaultdict(lambda: collections.Counter())
for row in rows:
    day = row['period_hour'][:10]
    by_day[day][row['endpoint_group']] += row['count']

for day, counts in sorted(by_day.items()):
    print(day, dict(counts))