Sign in

v5

latestOpenAPI 3.1.02026-08-025631,1012.8 MB
Organization Billing

Get Usage Breakdown

Get detailed usage breakdown.

Returns usage breakdown by operation type and extractor for the specified billing period.

Query Parameters:

  • billing_month: Month to query (YYYY-MM format, defaults to current)

Requirements:

  • Read permission

Example:

# Current month
response = await client.get("/v1/organizations/billing/usage/breakdown")

# Specific month
response = await client.get(
    "/v1/organizations/billing/usage/breakdown",
    params={"billing_month": "2025-11"}
)
get/v1/organizations/billing/usage/breakdown

Query parameters

billing_monthstring nullable

Billing month in YYYY-MM format (defaults to current month)

Example:2025-12

Billing month in YYYY-MM format (defaults to current month)

Response

Successful Response

billing_monthstring required

Billing month (YYYY-MM)

total_creditsinteger required

Total credits consumed

total_cost_usdnumber required

Total cost in USD

by_operationobject required

Credits consumed by operation type

by_extractorobject required

Credits consumed by extractor

by_namespaceobject

Credits consumed by namespace (SP-242 — chargeback / cost-allocation for multi-namespace orgs). Keyed by namespace_id; excludes namespace-less consumption. Empty for older usage recorded before per-namespace attribution.

by_retrieverobject

Credits consumed by retriever (per-product query-cost attribution for chargeback). Keyed by retriever_id (resource_type='retriever' charges: queries, enrichment). Empty when no retriever-attributed usage.

pending_creditsnumber

Unflushed sub-credit usage accrued but not yet committed to by_operation. Micro-priced per-op usage (e.g. MVS writes/queries at ~0.001 credit each) accumulates here and rolls into by_operation in whole credits as it crosses 1 — so real activity is visible immediately, before a whole credit accrues (BACKE-790).

pending_by_operationobject

Unflushed fractional credits by operation type.

period_startstring date-time required

Start of billing period

period_endstring date-time required

End of billing period

Example response

{
  "billing_month": "2025-12",
  "total_credits": 23450,
  "total_cost_usd": 23.45,
  "by_operation": {
    "batch": 2450,
    "extractor": 15000,
    "search": 1000,
    "upload": 5000
  },
  "by_extractor": {
    "multimodal_extractor": 10000,
    "text_extractor": 5000
  },
  "by_namespace": {
    "ns_clientA": 18000,
    "ns_clientB": 5450
  },
  "by_retriever": {
    "ret_search_prod": 4200,
    "ret_support_bot": 900
  },
  "pending_credits": 0.014,
  "pending_by_operation": {
    "mvs_query": 0.004,
    "mvs_write": 0.01
  }
}