Usage

Ce document décrit l’endpoint de consultation de l’usage de votre organisation : abonnement, quotas structurels et consommation de tokens du mois en cours. Scopé à votre organisation via votre token x-api-key (voir Récupération de votre Token d’Authentification).

Prérequis

• Un compte DIMARC actif.
• Votre token d’authentification x-api-key (voir Récupération de votre Token d’Authentification)

Consulter l’usage

GET /v2/organization/usage

curl 'https://api.dimarc.ai/v2/organization/usage' \
  --header 'x-api-key: <your_api_key>'

{
  "status": "success",
  "data": {
    "subscription": {
      "status": "active",
      "billing_cycle": "monthly",
      "current_period_end": "2026-08-01T00:00:00.000Z"
    },
    "quotas": {
      "max_agents": { "limit": 10, "used": 4 },
      "max_documents_per_agent": { "limit": 500 },
      "max_upload_mb": { "limit": 60 }
    },
    "usage": {
      "period": "2026-07",
      "api_tokens": 128000,
      "billable_tokens": 154000,
      "included_api_tokens": 100000,
      "overage_tokens": 54000
    },
    "storage": {
      "capacity_bytes": 16000000000,
      "used_bytes": 3200000000,
      "packs": 0
    }
  }
}

Erreurs possibles : 404 agent_not_found (organisation introuvable).

subscription

Champ	Type	Description
status	string | null	Statut Stripe synchronisé de l’abonnement (active, trialing, past_due, canceled…). null si aucun abonnement.
billing_cycle	string | null	monthly ou yearly.
current_period_end	string | null	Fin de la période de facturation Stripe en cours, ISO 8601 UTC.

quotas

Limites structurelles de votre plan. limit: null signifie illimité.

Champ	Description
max_agents.limit / .used	Nombre maximum d’agents actifs, et nombre actuellement actifs.
max_documents_per_agent.limit	Nombre maximum de documents par agent Documentaliste.
max_upload_mb.limit	Taille maximale d’un fichier uploadé, en Mo.

usage

Consommation de tokens pour la période en cours (voir period vs current_period_end ci-dessous).

Champ	Description
period	Mois de la consommation reportée, format YYYY-MM, en UTC.
api_tokens	Tokens consommés via l’API (agents créés/appelés via x-api-key).
billable_tokens	Tokens facturables du mois : api_tokens + tokens du canal public. N’inclut pas l’usage in-app (couvert par les sièges de l’abonnement).
included_api_tokens	Volume de tokens inclus dans votre abonnement, si votre plan en définit un ; null sinon.
overage_tokens	max(0, billable_tokens - included_api_tokens). Toujours 0 si included_api_tokens est null.

Seuls les traitements aboutis sont comptés. Un traitement en échec, expiré ou interrompu de notre fait n’est ni facturé ni décompté de votre quota : ses tokens n’entrent dans aucun de ces champs ni dans le plafond de dépense.

storage

Champ	Description
capacity_bytes	Capacité de stockage documentaire en octets : 2 Go par siège (2 Go au minimum), plus 10 Go par pack et le volume éventuellement inclus dans votre contrat ; un dépôt qui la dépasserait est refusé 403 storage_full.
used_bytes	Octets actuellement utilisés.
packs	Nombre de packs de stockage de 10 Go souscrits.

Plafond de dépense

Votre organisation peut fixer, depuis son espace d’abonnement, un plafond mensuel de dépassement exprimé en euros. Tant que overage_tokens reste sous ce plafond, rien ne change. Le plafond atteint, les appels qui consomment des tokens — extracteur, documentaliste, connaissance, classification et l’API compatible OpenAI — sont refusés en 429 avec le code spending_limit_reached, jusqu’à la période suivante ou jusqu’au relèvement du plafond.

Les appels de lecture ne sont jamais refusés par ce plafond : consulter cet endpoint d’usage, lister vos agents ou lister les modèles reste possible, sans quoi vous ne pourriez pas diagnostiquer le refus.

Sans plafond posé, aucune limite de montant ne s’applique et le dépassement est facturé à l’usage.

period vs current_period_end

Ces deux champs répondent à des questions différentes et ne partagent pas le même référentiel de temps :

• usage.period (YYYY-MM) est le mois calendaire UTC sur lequel la consommation de tokens est agrégée. Il change le 1ᵉʳ de chaque mois à 00:00:00 UTC, indépendamment de votre date de souscription.
• subscription.current_period_end est la date de fin du cycle de facturation Stripe en cours (mensuel ou annuel selon billing_cycle), qui dépend de votre date de souscription et peut tomber n’importe quel jour du mois.

Ces deux notions ne s’alignent en général pas : votre abonnement peut se renouveler le 14 du mois tandis que l’usage est toujours reporté par mois calendaire (2026-07, 2026-08…).

Support et assistance

Pour toute question concernant l’usage et la facturation, contactez notre équipe de support à l’adresse contact@dimarc.fr