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
    }
  }
}

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.

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