Usage

This document describes the endpoint for retrieving your organization’s usage: subscription, structural quotas, and token consumption for the current month. Scoped to your organization via your x-api-key token (see Retrieving Your Authentication Token).

Prerequisites

• An active DIMARC account.
• Your authentication token x-api-key (see Retrieving Your Authentication Token)

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

Possible errors: 404 agent_not_found (organization not found).

subscription

Field	Type	Description
status	string | null	Synced Stripe subscription status (active, trialing, past_due, canceled…). null if there is no subscription.
billing_cycle	string | null	monthly or yearly.
current_period_end	string | null	End of the current Stripe billing period, ISO 8601 UTC.

quotas

Structural limits of your plan. limit: null means unlimited.

Field	Description
max_agents.limit / .used	Maximum number of active agents, and the number currently active.
max_documents_per_agent.limit	Maximum number of documents per Documentalist agent.
max_upload_mb.limit	Maximum size of an uploaded file, in MB.

usage

Token consumption for the current period (see period vs current_period_end below).

Field	Description
period	Month the consumption is reported for, format YYYY-MM, UTC.
api_tokens	Tokens consumed through the API (agents created/called via x-api-key).
billable_tokens	Billable tokens for the month: api_tokens + tokens from the public channel. Does not include in-app usage (covered by subscription seats).
included_api_tokens	Volume of tokens included in your subscription, if your plan defines one; null otherwise.
overage_tokens	max(0, billable_tokens - included_api_tokens). Always 0 when included_api_tokens is null.

Only completed processing is counted. Processing that fails, expires or is interrupted on our side is neither billed nor deducted from your quota: its tokens enter none of these fields, nor the spending limit.

storage

Field	Description
capacity_bytes	Document storage capacity in bytes: 2 GB per seat (2 GB minimum), plus 10 GB per pack and any volume included in your contract; an upload that would exceed it is refused with 403 storage_full.
used_bytes	Bytes currently used.
packs	Number of 10 GB storage packs subscribed.

Spending limit

Your organization can set a monthly overage cap, in euros, from its subscription settings. While overage_tokens stays under that cap, nothing changes. Once it is reached, the calls that consume tokens — extractor, documentalist, knowledge, classification and the OpenAI-compatible API — are refused with 429 and the code spending_limit_reached, until the next period or until the cap is raised.

Read calls are never refused by this cap: reading this usage endpoint, listing your agents or listing the models stays possible — otherwise you could not diagnose the refusal.

With no cap set, no amount limit applies and overage is billed on usage.

period vs current_period_end

These two fields answer different questions and do not share the same time reference:

• usage.period (YYYY-MM) is the UTC calendar month over which token consumption is aggregated. It changes on the 1st of each month at 00:00:00 UTC, regardless of your subscription date.
• subscription.current_period_end is the end date of the current Stripe billing cycle (monthly or yearly depending on billing_cycle), which depends on your subscription date and can fall on any day of the month.

These two notions generally do not line up: your subscription may renew on the 14th of the month while usage is always reported by calendar month (2026-07, 2026-08…).

Support and Assistance

For any questions regarding usage and billing, contact our support team at contact@dimarc.fr