---
title: "Get plan and usage snapshot (plan, limits, payment status)"
method: GET
path: "/v1/usage-stats"
tags: ["Usage"]
deprecated: true
---

# Get plan and usage snapshot (plan, limits, payment status)

`GET /v1/usage-stats`

> **Deprecated.**

The plan / quota / payment-status snapshot: current plan name, billing
period, plan limits, usage counts, and access state. Identical to a
bare `GET /v1/usage` call (this path is its deprecated alias). For
billed spend by product, call `GET /v1/usage` with `range` /
`granularity` params. The statement view (balance, credits, caps,
payment status) lives at `GET /v1/billing`.

The response shape depends on the account's `billingSystem`:
  * Stripe users: per-period `usage.uploads` / `usage.profiles` counters.
  * Metronome (usage-based) users: `usage.connectedAccounts`,
    `usage.xApiCallsByOperation` (per-operation X API call counts —
    resolve keys via `GET /v1/billing/x-pricing`), plus a `spend`
    block with `currentPeriodCents`, `xSpendCents`, and
    `xSpendLimitCents`. The legacy `usage.xApiCalls` 3-tier
    aggregate is still emitted for back-compat but excludes the
    $0.200 URL tier and any future tiers — new clients should
    consume `xApiCallsByOperation` only.

## Query parameters

- `reconcile` boolean

## Response `200`

Usage stats

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

## 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/versions/51932b099b2f/schema)