---
title: "Get Billing Status"
method: GET
path: "/billing/billing-status"
tags: ["billing"]
---

# Get Billing Status

`GET /billing/billing-status`

Get billing status for the authenticated user.

Returns:
    - Total token usage
    - Free tier remaining tokens
    - Whether user has exceeded free tier
    - Whether user has a payment method on file
    - Stripe customer ID
    - List of payment methods

## Response `200`

Successful Response

- BillingStatusResponse — Response model for billing status.
  - `team_id` string, nullable
  - `total_usage` number, required
  - `free_tier_remaining` number, required
  - `exceeds_free_tier` boolean, required
  - `has_payment_method` boolean, required
  - `card_verified` boolean
  - `stripe_customer_id` string, nullable
  - `payment_methods` PaymentMethodInfo[]
    - `id` string, required
    - `type` string
    - `brand` string, required
    - `last4` string, required
    - `exp_month` integer, nullable
    - `exp_year` integer, nullable
    - `billing_name` string, nullable
    - `billing_address` BillingAddress — Billing address on file for a payment method, as held by Stripe. All fields are optional because Stripe only returns the components the customer provided. The UI renders this read-only; it is never edited in Pioneer (changes are made in the Stripe customer portal).
      - `line1` string, nullable
      - `line2` string, nullable
      - `city` string, nullable
      - `state` string, nullable
      - `postal_code` string, nullable
      - `country` string, nullable
  - `payment_plan` string
  - `billing_activated` boolean — Authoritative inference-gate result computed from the same billing fields the request path reads. Frontend surfaces (paywall, upgrade CTA) MUST consume this field instead of re-deriving from ``payment_plan`` / ``card_verified``.
  - `credit_limit` number, required
  - `paid_credit_balance` number — Persistent paid credit wallet balance (credits).
  - `router_only_free_credits` boolean — Retired (ENG-5673). Always false — with no router left to fund, included plan credits fund every model. Kept so existing clients keep parsing the snapshot; do not branch on it.
  - `direct_model_inference_available` boolean — Retired (ENG-5673). Always true — the router-only restriction that could clear it no longer exists. Kept so existing clients keep parsing the snapshot; do not branch on it.
  - `current_period_start` string, nullable — ISO timestamp when the team's current billing period started (mirrors teams.current_period_start). None when the user has no active team.

---

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