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":   "enterprise",
    "usage": {
      "request": { "total": 31, "billable": 0 },
      "signup":  { "total": 3,  "billable": 2 }
    },
    "limits": {
      "requests_per_month":  -1,
      "signups_per_month":   -1,
      "webhooks_per_month":  -1,
      "requests_per_minute": 600
    }
  }
}

Référence des champs

Champ	Signification
period	Toujours YYYY-MM — le mois courant en heure Africa/Algiers (UTC+01:00, sans heure d'été). Les totaux sont ceux du mois en cours, comptés depuis le 1er à 00:00.
tier	Votre tier de limite de taux actuel — toujours enterprise (l'API est réservée à Enterprise).
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é.

usage est creux (sparse) — seuls les groupes ayant enregistré de l'activité dans le mois calendaire courant apparaissent (en pratique request, plus signup / event pour le trafic de clé publique). Si la boutique n'a aucune activité, usage est sérialisé en tableau JSON vide [], et non en objet. Mettez les groupes absents à zéro côté client et tolérez [] ; sinon un désérialiseur strictement typé échouera.

Groupes d'endpoints

Groupe	Ce qui compte
request	Chaque appel ayant passé l'authentification par clé et les limites de débit, compté avant le traitement de la requête : les réponses 4xx/5xx et les rejets de scope comptent donc aussi, mais pas les appels refusés avec 429 ou 402. Les appels faits sur votre boutique par Copilot, par un assistant IA connecté (Claude ou ChatGPT) ou par une application installée comptent aussi ici. Toujours billable: 0. GET /v1/ping n'est pas authentifié et n'est jamais compté.
signup	Chaque appel /v1/signups. Les doublons comptent dans total mais pas billable.
event	Chaque appel /v1/events. Seuls les événements nouvellement enregistrés sont comptés — les doublons (même boutique + nonce) sont écartés et n'apparaissent ni dans total ni dans billable. Cela diffère de signup.
webhook	Réservé. Les livraisons sortantes ne sont pas mesurées en v1, ce groupe n'apparaît donc jamais dans la réponse.

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. from est inclusif et to exclusif, et les deux sont arrondis au début de l'heure pour la requête uniquement — les valeurs from / to renvoyées dans la réponse sont vos entrées telles qu'analysées, sans arrondi. Les formats de date et de date-heure courants sont acceptés (2026-04-01, 2026-04-01T12:00:00Z, -7 days, …) ; une valeur non analysable ou un to antérieur à from renvoie 400 bad_request (« from/to must be valid date strings, to >= from »), et une plage de plus de 90 jours renvoie 400 (« range too large (max 90 days) »).

Les tranches period_hour sont des heures pleines, horodatées en heure d'Alger (UTC+01:00) au moment où chaque appel est comptabilisé.

Erreurs

HTTP	Code	Cause
400	bad_request	« from/to must be valid date strings, to >= from »
400	bad_request	« range too large (max 90 days) »
403	forbidden	« Missing scope: usage:read »

usage:read fait partie des scopes par défaut des clés que vous générez dans le tableau de bord. Une clé créée via POST /v1/keys ne le porte que si la clé appelante le porte, et le jeton d'une application installée ne peut jamais le porter : une application reçoit donc 403 sur ces deux endpoints et sur /v1/quotas.

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+01:00",
    "to":   "2026-05-01T00:00:00+01: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 les 10 premiers caractères de period_hour (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))