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é, compté avant le traitement de la requête — les réponses 4xx/5xx et les rejets de scope comptent donc aussi. Toujours `billable: 0`. `GET /v1/ping` n'est pas authentifié et n'est jamais compté, et les réponses servies depuis le cache (`X-Cache: HIT`) ne sont pas comptées non plus.
`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 est l'un des rares scopes que v1 applique réellement. Il est accordé par défaut sur chaque clé plateforme créée, il ne gêne donc que les clés que le support a émises avec un jeu de scopes réduit.

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, osr = 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))

Utilisation

GET /v1/usage

Réponse 200

Référence des champs

Groupes d'endpoints

GET /v1/usage/history

Paramètres de requête

Erreurs

Requête

Réponse 200

Conseils de visualisation