Billing and usage metering

Every AI capability call — LLM completion, speech-to-text transcription, embedding, TTS synthesis, OCR, image generation, video analysis — produces a metered usage event. The billing.* API lets organisation admins query cost, token, run, and CO₂ estimates across any combination of workspace, team, user, capability, vendor, model, or region.

API overview

All billing.* methods are available on the Better Auth admin client (getAdminClient()) from @scrydon/multi-tenancy/auth/client.

Usage event fields

Each metered event captures:

Summary

Returns aggregate totals for the organisation over a date range, with an optional per-dimension breakdown.

const { data, error } = await getAdminClient().billing.summary({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  groupBy: "workspace",            // optional
  filters: { capability: "llm" }, // optional dimension filter
})

Request

UsageDimension is one of: workspace, team, user, source, capability, vendor, model, region.

Response (UsageSummary)

{
  costUsd: number,       // total cost over the range
  co2Grams: number,      // total CO₂ estimate (grams CO₂e)
  tokensIn: number,
  tokensOut: number,
  runs: number,          // total capability calls
  successes: number,
  groups: Array<{
    key: string,         // dimension value (e.g. workspace id)
    costUsd: number,
    co2Grams: number,
    tokens: number,
    runs: number,
  }>,
}

Timeseries

Returns a day-by-day series for charting consumption over time.

const { data, error } = await getAdminClient().billing.timeseries({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  granularity: "day",
  groupBy: "capability",  // optional
})

Request

Response

{
  points: Array<{
    bucket: string,      // ISO day (YYYY-MM-DD)
    costUsd: number,
    co2Grams: number,
    tokens: number,
    runs: number,
  }>,
}

Top-N

Returns the top N keys by a chosen metric over a date range — useful for identifying the highest-cost workspaces, models, or vendors.

const { data, error } = await getAdminClient().billing.topN({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  dimension: "model",
  metric: "cost_usd",
  limit: 10,
})

Request

Response

{
  rows: Array<{
    key: string,    // dimension value
    value: number,  // metric total
  }>,
}

Chargeback

Returns cost, CO₂, token, and run totals per key, plus each key's share of the organisation total. Use this for internal cost allocation.

const { data, error } = await getAdminClient().billing.chargeback({
  organizationId: "org_abc123",
  range: { from: "2026-06-01T00:00:00Z", to: "2026-07-01T00:00:00Z" },
  dimension: "workspace",
})

Response (ChargebackRow[])

Array<{
  key: string,        // dimension value (e.g. workspace id)
  costUsd: number,
  co2Grams: number,
  tokens: number,
  runs: number,
  share: number,      // 0..1 — fraction of org-total cost
}>

share values across all rows sum to approximately 1. Events with no value for the chosen dimension are grouped under "(unattributed)".

Carbon factors

Returns the full carbon-factor table used to compute co2Grams on every event. Intended for auditors and ESG reporting.

const { data, error } = await getAdminClient().billing.carbonFactors({
  organizationId: "org_abc123",
})

Response

{
  version: string,                    // e.g. "2026.06.0" — matches usage_event.carbon_version
  regionFallback: string,             // region used when vendor region is unknown
  gridGco2PerKwh: Record<string, number>,    // gCO₂e per kWh by region
  energyWhPer1k: Record<string, number>,     // Wh per 1k tokens/units by model class
  pue: number,                        // power-usage effectiveness multiplier
  citation: string,                   // provenance string for audit
}

Carbon methodology

Scrydon estimates AI-capability carbon footprint using a three-factor model:

CO₂ (g) = energy_per_1k_units_Wh × (total_tokens_or_units / 1000) × PUE × (grid_gco2_per_kwh / 1000)

• Energy per 1k tokens (Wh): Binned by model class (llm_large, llm_small, embedding, stt, etc.) using published per-token energy estimates. Non-token classes (STT, OCR, image, video) use per-audio-second, per-page, or per-image denominators.
• PUE (Power-Usage Effectiveness): A fixed multiplier of 1.12 — a mid-range value within the 1.1–1.2 range published by major hyperscalers.
• Grid carbon intensity (gCO₂e/kWh): Region-specific values from public electricity-grid carbon intensity databases. Requests without a known hosting region fall back to the global average (436 gCO₂e/kWh).

The factor table is versioned (carbon_version). Every usage_event row records the version in use at write time, so historical totals remain reproducible after factor updates. Retrieve the current table and its provenance string via billing.carbonFactors(...).

Required role

All billing.summary, billing.timeseries, billing.topN, billing.chargeback, and billing.carbonFactors calls require an org-admin session for the queried organizationId. A non-admin member receives a 403 Forbidden response.

billing.log is an internal M2M endpoint gated on the billing:admin capability. It is called by the capability runtime — not by product code or SDK consumers.

Related

• Platform admins and impersonation — how to confirm your org-admin role.
• Integrations — connecting vendors whose usage is metered here.
• Compliance — how usage metering maps to EU AI-Act Article 13 and ESG attestation requirements.