Consulter l'usage et les quotas en temps réel

L'API Coffrify expose cinq endpoints en lecture seule permettant de connaître à tout moment la consommation de votre workspace : les plafonds du plan en cours, les pourcentages d'utilisation instantanés, les séries temporelles de bande passante et de stockage, le débit par minute et l'historique de facturation par période. Ces endpoints ne provoquent aucune écriture et retournent des données fraîches calculées en temps réel à partir des tables coffrify_bandwidth_daily, coffrify_storage_snapshots, coffrify_throughput_samples et coffrify_usage_billing_periods.

Authentification

Tous ces endpoints requièrent un token Bearer valide dans l'en-tête Authorization. Les endpoints /v1/quotas/* exigent le scope quotas:read ; l'endpoint /v1/billing/usage exige le scope billing:read. Les scopes plus larges workspace:billing, workspace:manage et workspace:read satisfont également ces exigences selon la hiérarchie de scopes de l'API. Utilisez une clé préfixée cof_live_…, cof_test_… ou cof_sandbox_… (selon votre environnement).

Appel des endpoints

Tous ces endpoints sont en lecture seule et renvoient du JSON immédiatement exploitable. Les exemples ci-dessous appellent /v1/quotas/check, le point d'entrée le plus utile pour un tableau de bord ou une sonde.

# Vérification instantanée des quotas
curl -s https://api.coffrify.com/v1/quotas/check \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"
 
# Bande passante sur les 30 derniers jours
curl -s "https://api.coffrify.com/v1/quotas/bandwidth?days=30" \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"
 
# Snapshots de stockage sur 90 jours
curl -s "https://api.coffrify.com/v1/quotas/storage?days=90" \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"
 
# Débit sur la dernière heure
curl -s "https://api.coffrify.com/v1/quotas/throughput?minutes=60" \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"
 
# Historique de facturation (12 dernières périodes)
curl -s "https://api.coffrify.com/v1/billing/usage?limit=12" \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"

Réponse : /v1/quotas/check

La réponse compare les plafonds du plan (caps) à la consommation courante et expose des booléens over_quota.*. Surveillez ces booléens : ce sont eux qui doivent déclencher une alerte ou une montée de plan.

{
  "plan": "pro",
  "caps": {
    "storage_bytes": 1099511627776,
    "bandwidth_bytes_per_month": 536870912000,
    "active_transfers": 25,
    "max_transfer_size_bytes": 107374182400
  },
  "consumption": {
    "storage_bytes": 42949672960,
    "storage_pct": 4,
    "bandwidth_bytes_last_30d": 107374182400,
    "bandwidth_pct": 20,
    "active_transfers": 7,
    "active_transfers_pct": 28
  },
  "over_quota": {
    "storage": false,
    "bandwidth": false,
    "active_transfers": false
  }
}

Réponse : /v1/quotas/bandwidth

Cet endpoint renvoie une série temporelle journalière (data), un point par jour. Idéal pour tracer une courbe de consommation ou détecter une tendance avant d'atteindre le plafond mensuel.

{
  "object": "list",
  "data": [
    { "day": "2026-05-07", "bytes_egress": 1073741824, "download_count": 38 },
    { "day": "2026-05-08", "bytes_egress": 2147483648, "download_count": 71 },
    { "day": "2026-06-06", "bytes_egress": 536870912, "download_count": 19 }
  ],
  "range_days": 30,
  "since": "2026-05-07",
  "totals": {
    "bytes_egress": 107374182400,
    "download_count": 1284
  }
}

Réponse : /v1/billing/usage

L'historique de facturation liste une entrée par période, avec la consommation, les éventuels dépassements et le statut de remontée vers Stripe. Utile pour réconcilier votre usage avec vos factures.

{
  "object": "list",
  "data": [
    {
      "id": "ubp_01jx4zk8m3p",
      "period_start": "2026-06-01T00:00:00Z",
      "period_end": "2026-07-01T00:00:00Z",
      "storage_gb_used": 40.0,
      "bandwidth_gb_used": 100.0,
      "storage_overage_gb": 0.0,
      "bandwidth_overage_gb": 0.0,
      "storage_overage_reported_to_stripe": false,
      "bandwidth_overage_reported_to_stripe": false,
      "stripe_invoice_id": null,
      "created_at": "2026-06-01T00:01:12Z",
      "updated_at": "2026-06-06T03:00:04Z"
    }
  ],
  "current_period": {
    "id": "ubp_01jx4zk8m3p",
    "period_start": "2026-06-01T00:00:00Z",
    "period_end": "2026-07-01T00:00:00Z",
    "storage_gb_used": 40.0,
    "bandwidth_gb_used": 100.0,
    "storage_overage_gb": 0.0,
    "bandwidth_overage_gb": 0.0,
    "storage_overage_reported_to_stripe": false,
    "bandwidth_overage_reported_to_stripe": false,
    "stripe_invoice_id": null,
    "created_at": "2026-06-01T00:01:12Z",
    "updated_at": "2026-06-06T03:00:04Z"
  }
}

Paramètres de requête

Chaque endpoint accepte un paramètre de fenêtre temporelle (days, minutes ou limit), avec une valeur par défaut et des bornes. Le tableau ci-dessous les récapitule.

Plafonds par plan

À titre indicatif, voici les plafonds appliqués par plan. Ce sont ces valeurs que renvoie le champ caps de /v1/quotas/check pour le plan actif de votre workspace.

Erreurs

Ces endpoints étant en lecture seule, les erreurs se limitent surtout à l'authentification et aux scopes. Un 403 signale un scope manquant (quotas:read ou billing:read selon l'endpoint appelé).

Voir aussi

• Référence : GET /v1/quotas/check
• Référence : GET /v1/billing/usage
• Gérer votre abonnement et vos alertes de dépassement
• Authentification et gestion des clés API
• Rate limits et codes d'erreur