Token Balance Query

Query the quota information of the current API Key (token) or account. This interface is compatible with OpenAI billing API format, consisting of two endpoints: "subscription query" and "usage query". Together they allow you to calculate the remaining balance.

The currency unit of the quota is determined by site configuration (USD / CNY / Tokens). The *_usd fields represent "quota values converted according to the site's display unit".

Subscription Query (Total Quota)

Returns the token's quota limit and expiration time.

• Limited quota token: Returns the total quota of the token (remaining + used).
• Unlimited quota token: Returns the user's current wallet balance (available balance only, excluding consumed amount).

GET https://apione.org/dashboard/billing/subscription

Equivalent path: GET https://apione.org/v1/dashboard/billing/subscription

Request Example

curl "https://apione.org/dashboard/billing/subscription" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx"

Response Example

{
  "object": "billing_subscription",
  "has_payment_method": true,
  "soft_limit_usd": 100,
  "hard_limit_usd": 100,
  "system_hard_limit_usd": 100,
  "access_until": 0
}

Response Fields

Usage Query (Used Quota)

Returns the quota consumed by the token.

GET https://apione.org/dashboard/billing/usage

Equivalent path: GET https://apione.org/v1/dashboard/billing/usage

Request Example

curl "https://apione.org/dashboard/billing/usage" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxx"

Response Example

{
  "object": "list",
  "total_usage": 3500
}

Response Fields

Calculating Remaining Balance

Limited Quota Token

Total quota    = soft_limit_usd           (from subscription query)
Used quota     = total_usage / 100        (from usage query)
Remaining      = Total quota - Used quota

Example: soft_limit_usd = 100, total_usage = 3500

Used      = 3500 / 100 = 35
Remaining = 100 - 35   = 65

Unlimited Quota Token

soft_limit_usd directly returns the user's current wallet balance — no subtraction needed:

Remaining = soft_limit_usd               (use directly)

Example: soft_limit_usd = 178.3 → current available balance is 178.3.

Caching Recommendations

• Query on demand: Query when users enter the balance page or after a task completes — not on a timer loop.
• Local cache: Cache results for 30~60 seconds and reuse them to avoid repeated requests.
• Poll interval: If polling is needed, use an interval of ≥ 30 seconds; background monitors can be relaxed to several minutes.
• Avoid pre-call balance checks: Rely on insufficient quota errors from business APIs as a fallback — it's more efficient than "check balance then call".