---
title: "Usage snapshot (default) or billed-spend metering (with params)"
method: GET
path: "/v1/usage"
tags: ["Usage"]
---

# Usage snapshot (default) or billed-spend metering (with params)

`GET /v1/usage`

Dual-mode endpoint, selected by query params — fully backward
compatible:

**Without metering params (the default):** the plan / quota / usage
snapshot — plan name, billing period, limits, usage counts, access
state. Identical to `GET /v1/usage-stats`. Existing integrations keep
working unchanged.

**With `range`, `granularity`, `from`, or `to`:** usage METERING —
billed spend (USD) by product family (`accounts`, `numbers`, `calls`,
`sms`, `dlc`, `xApi`, `credits`, `other`) over the window, at
`day` / `month` / `total` granularity, from Metronome's invoice
breakdown (the CHARGE view — always reconciles with what gets billed).
Also served at `GET /v1/usage/daily`. Usage-based accounts only —
legacy Stripe accounts get `{ "supported": false, "days": [] }`.

For per-domain consumption *volumes* use `GET /v1/usage/calls` and
`GET /v1/usage/sms`. For the billing statement (balance, credits,
caps, payment status) use `GET /v1/billing`.

## Query parameters

- `reconcile` boolean
- `range` 'cycle' | 'prev-cycle' | '7d' | '14d' | '30d' | '3mo' | '12mo' | 'custom'
- `from` string, date
- `to` string, date
- `granularity` 'day' | 'month' | 'total'

## Response `200`

Snapshot (no metering params) or billed spend by product over the
window (with metering params).

- union
  - UsageStats — Plan and usage stats. The response shape depends on `billingSystem`: * Stripe users (default): per-period counters like `usage.uploads` and `usage.profiles` are returned, scoped by the plan's `limits`. * Metronome users (usage-based): `limits` are unlimited (-1). The `usage` block carries connected-account and per-X-operation counts, and the `spend` block carries current-period costs plus the X cap.
    - `billingSystem` 'stripe' | 'metronome' — Which billing system the account is on. Shape of `usage`/`spend` differs.
    - `planName` string
    - `billingPeriod` 'monthly' | 'yearly'
    - `signupDate` string, date-time
    - `billingAnchorDay` integer — Day of month (1-31) when the billing cycle resets
    - `hasAccess` boolean — True if the account is in good standing. False for past-due/unpaid/paused subscriptions.
    - `customerId` string, nullable — Stripe customer ID, when present.
    - `isInvitedUser` boolean — True if this is a team member; limits/usage reflect the account owner.
    - `autoUpgradeEnabled` boolean — Stripe-only. Always false for Metronome users.
    - `limits` object — Plan limits. For Metronome users both fields are `-1` (unlimited).
      - `uploads` integer
      - `profiles` integer
    - `usage` object — Per-period usage counts. Fields present depend on `billingSystem`: Stripe returns `uploads` / `profiles` / `lastReset`; Metronome returns `connectedAccounts` / `xApiCalls` / `xApiCallsByOperation`.
      - `uploads` integer — Stripe users only. Uploads consumed in the current period.
      - `profiles` integer — Stripe users only. Profiles currently owned.
      - `lastReset` string, date-time — Stripe users only.
      - `connectedAccounts` integer — Metronome users only. Accounts currently connected across the team.
      - `xApiCalls` object — **Deprecated.** Legacy 3-tier aggregate. Operations outside the three historical prices ($0.005/$0.010/$0.015) — notably the $0.200 "Posts with URL" tier added April 2026 — are silently excluded from this shape. Use `xApiCallsByOperation` instead; it captures every tier and is the source of truth for per-operation call counts.
        - `x_api_005` integer — Calls at $0.005 per call (reads, lists, bookmarks, content manage, etc.)
        - `x_api_010` integer — Calls at $0.010 per call (user reads, DM reads, follow reads, trends, list create, privacy update)
        - `x_api_015` integer — Calls at $0.015 per call (posts/replies, DM sends, user interactions)
      - `xApiCallsByOperation` object — Metronome users only. Per-operation X API call counts keyed by operation (e.g. `posts_read`, `content_create`, `content_create_with_url`). Resolve each key to price and metadata via `GET /v1/billing/x-pricing`. This is the canonical source — covers every price tier including the $0.200 URL tier that `xApiCalls` excludes.
    - `spend` object — Metronome users only. Current-period spend summary.
      - `currentPeriodCents` integer — Total current-period spend in cents (all products combined).
      - `creditsRemainingCents` integer — Free-tier credit remaining in cents. Applied before any charge.
      - `xSpendCents` integer — Current-period X/Twitter API spend in cents, summed from `xApiCallsByOperation` × per-operation prices. Tier-agnostic (covers every price including the $0.200 URL tier). Rounded up for conservative enforcement against `xSpendLimitCents`.
      - `xSpendLimitCents` integer, nullable — Monthly X spend cap set by the account owner, or null if no cap. When current X spend hits this cap, analytics and inbox sync are auto-paused for X accounts. Publishing is never blocked by this cap.
  - UsageMetering — Billed spend by product family over a window, from Metronome's invoice breakdown (the CHARGE view). Returned by `GET /v1/usage`.
    - `supported` boolean — False for legacy Stripe accounts (no Metronome invoice to split); `days` and `totals` are then empty/zero.
    - `granularity` 'day' | 'month' | 'total'
    - `days` object[] — One row per bucket. Empty when `granularity=total`. `date` is a UTC date (month buckets use the 1st).
      - `date` string, date
      - `accounts` number
      - `numbers` number
      - `calls` number
      - `sms` number
      - `dlc` number — 10DLC registration (brand + campaign) fees.
      - `xApi` number
      - `credits` number — Applied credits/discounts (negative).
      - `other` number
    - `totals` object — Sum of each product over the whole window (USD), plus `total`. Unaffected by `granularity`.
      - `accounts` number
      - `numbers` number
      - `calls` number
      - `sms` number
      - `dlc` number
      - `xApi` number
      - `credits` number
      - `other` number
      - `total` number
    - `lineItems` object[] — Per-invoice-line-item rows (largest spend first) for a detailed breakdown.
      - `name` string
      - `product` 'accounts' | 'numbers' | 'calls' | 'sms' | 'dlc' | 'xApi' | 'credits' | 'other'
      - `totalUsd` number
      - `quantity` number
    - `peaks` object — Peak counts over the window (Metronome COUNT metrics + live active-number count).
      - `accounts` integer
      - `numbers` integer
    - `callUsage` object — Billable call volumes over the window.
      - `whatsapp` object
        - `count` integer
        - `minutes` integer
      - `pstn` object
        - `count` integer
        - `minutes` integer
    - `period` object
      - `start` string, date-time
      - `end` string, date-time
      - `source` 'cycle' | 'window' — `cycle` = a real billing period resolved; `window` = trailing/custom window (or cycle fallback).
    - `tax` object, nullable — Estimated tax on the window's net `totals.total`, computed with Stripe Tax against the billing address (the same engine the real invoice uses; invoices apply exclusive tax, so the card is charged total + tax). Null when the account has no billing address on file, the total is zero or negative, or the estimate failed.
      - `taxUsd` number — Estimated tax in USD, added on top of `totals.total`.
      - `ratePercent` number, nullable — Combined rate percentage, e.g. 21.
      - `jurisdictionLabel` string, nullable — Human jurisdiction label, e.g. "ES VAT" or "WA sales tax".
      - `reverseCharge` boolean — True for EU/UK B2B reverse charge (0 tax added by design).

## Other responses

- `400` — Invalid query parameter
- `401` — Unauthorized
- `404` — Resource not found

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/f81ca70ea6b9/schema)