Query Usage and Balance with an API Key

MuskAI lets you use an existing API key to query that key's usage and the available balance. You do not need a separate profile key.

The query does not create a model request or incur model usage charges. Using a separate API key for each project makes usage tracking and troubleshooting easier.

Quick query

Replace YOUR_API_KEY with an API key created in the MuskAI dashboard:

curl -sS "https://api.muskapi.cc/v1/usage" \
  -H "Authorization: Bearer YOUR_API_KEY"

You can store the key in an environment variable so that it does not have to be repeated in commands:

export MUSKAI_API_KEY="YOUR_API_KEY"

curl -sS "https://api.muskapi.cc/v1/usage" \
  -H "Authorization: Bearer $MUSKAI_API_KEY"

:::tip API endpoint If the recommended API address shown on the API Keys page differs from this example, use the address from your dashboard. The query path is always /v1/usage. :::

Response fields

The response depends on the billing and limits configured for the API key:

Field	Description
mode	unrestricted for wallet or subscription billing; quota_limited when the key has its own quota or rate limits
balance / remaining	Available wallet balance, subscription allowance, or key allowance
quota	Key-level monetary quota with limit, used, remaining, and unit
request_quota	Request-based quota with total, used, and remaining requests
rate_limits	Five-hour, daily, or seven-day key limits and reset times
usage.today	Requests, tokens, and cost for this key today
usage.total	Lifetime requests, tokens, and cost for this key
daily_usage	Daily usage for the requested number of days
model_stats	Usage grouped by model for the selected date range

Example of a shortened wallet-mode response:

{
  "mode": "unrestricted",
  "isValid": true,
  "balance": 18.52,
  "remaining": 18.52,
  "unit": "USD",
  "usage": {
    "today": {
      "requests": 12,
      "input_tokens": 42000,
      "output_tokens": 3500,
      "actual_cost": 0.42
    },
    "total": {
      "requests": 186,
      "actual_cost": 7.81
    }
  }
}

Read the response from a script

The following example requires jq:

curl -sS "https://api.muskapi.cc/v1/usage" \
  -H "Authorization: Bearer $MUSKAI_API_KEY" |
  jq '{
    remaining: (.balance // .remaining // .quota.remaining // .request_quota.remaining),
    unit: (.unit // .quota.unit // .request_quota.unit),
    today: .usage.today,
    total: .usage.total
  }'

Read only the remaining balance or quota:

REMAINING=$(curl -sS "https://api.muskapi.cc/v1/usage" \
  -H "Authorization: Bearer $MUSKAI_API_KEY" |
  jq -r '.balance // .remaining // .quota.remaining // .request_quota.remaining')

echo "Remaining: $REMAINING"

Query daily and model usage

curl -sS \
  "https://api.muskapi.cc/v1/usage?days=30&timezone=Asia%2FShanghai&start_date=2026-07-01&end_date=2026-07-18" \
  -H "Authorization: Bearer $MUSKAI_API_KEY"

Parameters:

• days: Number of days returned in daily_usage, from 1 to 90.
• timezone: Time zone used for daily boundaries, such as Asia/Shanghai.
• start_date and end_date: Date range for model_stats, in YYYY-MM-DD format.

Model statistics default to the most recent 30 days when no dates are supplied.

Web query

If you prefer not to use the command line, open the API Key Usage page and paste your key to view its balance, quota, daily usage, and model statistics.

Query scope

• Usage is scoped to the API key used for authentication. It is not automatically aggregated across every key in the account.
• Wallet balance is shared by the user account, so wallet-mode keys belonging to the same user show the same balance.
• Use a different API key for each project when you need separate usage totals.
• A key with an exhausted quota or an expired key can still attempt to query its own usage. Disabled, deleted, or invalid keys return an authentication error.

Security recommendations

• Send the API key only in the Authorization header. Never put it in the URL query string.
• Do not commit a complete key to a repository or include it in logs, screenshots, or support tickets.
• Use environment variables or a secrets manager for server-side scripts.
• Disable or delete a key immediately if you believe it has been exposed, then create a replacement.

The most common missing-key response is:

{
  "code": "API_KEY_REQUIRED",
  "message": "API key is required in Authorization header (Bearer scheme), x-api-key header, or x-goog-api-key header"
}

Make sure the request header uses this format:

Authorization: Bearer YOUR_API_KEY