# Utilisation Deux endpoints pour voir ce que votre boutique a consommé et estimer ce dont vous aurez besoin le mois prochain. ## `GET /v1/usage`[​](#get-v1usage "Lien direct vers get-v1usage") Mois calendaire courant, groupé par type d'endpoint. **Auth :** clé plateforme avec `usage:read`. ### Réponse 200[​](#réponse-200 "Lien direct vers 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[​](#référence-des-champs "Lien direct vers 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..total` | Toutes les requêtes du groupe, y compris doublons / rejets. | | `usage..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[​](#groupes-dendpoints "Lien direct vers 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`[​](#get-v1usagehistory "Lien direct vers get-v1usagehistory") 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ètres-de-requête "Lien direct vers 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[​](#erreurs "Lien direct vers 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[​](#requête "Lien direct vers 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[​](#réponse-200-1 "Lien direct vers 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[​](#conseils-de-visualisation "Lien direct vers 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)) ```