cc-switch/docs/user-manual/en/2-providers/2.5-usage-query.md

2.5 Usage Query

CC Switch's quota / balance display is split into two categories: Auto Query (official subscription types, works out of the box) and Manual Enable (built-in templates + custom scripts, requires user configuration before showing).

Category	Scope	User Enable Required
Auto Query	Claude / Codex / Gemini official subscriptions, GitHub Copilot, Codex OAuth reverse proxy	No (enabled by default)
Manual Enable (built-in templates)	Token Plan, third-party balance query	Yes (see below)
Manual Enable (custom script)	Proxies, private deployments, special APIs not covered by built-in templates	Yes (see below)

Auto Query (Official Subscription Types)

Starting from v3.13.0, the following three categories automatically display the quota at the bottom of the provider card after the provider is enabled — no additional configuration required:

Category	Covered Providers	Displayed Content
Official subscriptions	Claude / Codex / Gemini official login	Official subscription quota
GitHub Copilot	Copilot provider card	Premium interactions remaining
Codex OAuth	Codex OAuth reverse proxy card (Claude provider)	ChatGPT account Codex quota

These three share the common trait that their data source is unique and semantically unambiguous (the usage rate of an official subscription), so CC Switch directly calls the corresponding official or OAuth query endpoint.

Auto Query Interactions

• Card footer display: Usage percentage + reset countdown, colored by usage (< 70% green / 70–89% orange / ≥ 90% red)
• Manual refresh: Click the refresh icon on the card to re-query
• Simplified card: For these three types, the Health Check and Usage Query Config buttons are hidden to avoid interfering with the built-in display
• Session expired notice: If a token fails to refresh, the card shows a yellow "Session Expired" warning (Copilot / Codex OAuth)

---

Manual Enable (Built-in Templates + Custom Scripts)

Besides the three auto-query types above, all other providers (including Token Plan, third-party balance queries, and various proxy services) need to have the Usage Query switch manually turned on in the provider card before any quota is displayed.

Why do these need manual enabling?

One important reason: the same request URL (same vendor) may expose multiple query modes — for example, both plan-based quota queries and account-level balance queries. CC Switch cannot automatically infer which one you want, so the built-in query for such providers is disabled by default, leaving you to pick the right template.

Built-in Template Coverage

v3.13.0 provides ready-to-use built-in templates for the following categories — no script writing required:

Category	Covered Providers	Template Type
Token Plan	Kimi / Zhipu GLM / MiniMax	Plan quota (with usage progress)
Third-party balance	DeepSeek / StepFun / SiliconFlow / OpenRouter / Novita AI	Official balance query

Tip

: Beyond these built-in templates, for uncovered providers you can use the custom script approach (see below) to write your own query logic.

Enable Steps

1. Hover over the provider card to reveal action buttons
2. Click the Usage Query button (chart icon)
3. At the top of the configuration panel, toggle on Enable Usage Query
4. Select the right built-in template (e.g., Token Plan, third-party balance) or choose "Custom"
5. Fill in API Key / Base URL / Access Token as needed (most cases can be left blank, reusing the provider's own credentials)
6. Click Test Script to verify the query returns successfully
7. Save — next time the provider is activated, the quota will show up at the bottom of the card

⚠️ Note: The auto-refresh interval after enabling is controlled by the "Auto Query Interval" field (set to 0 to disable auto-refresh). Background queries only trigger when the provider is in "Currently Active" state.

---

Custom Script Query (Advanced)

Overview

When a provider is not covered by the built-in templates, you can write a custom JavaScript query script. Suitable for proxy services, private deployments, special API formats, etc.

Use cases:

• Check API account remaining balance
• Monitor plan usage
• Multi-plan balance summary display

Open Configuration

1. Hover over the provider card to reveal action buttons
2. Click the "Usage Query" button (chart icon)
3. Opens the usage query configuration panel

Enable Usage Query

At the top of the configuration panel, enable the "Enable Usage Query" toggle.

Preset Templates

CC Switch provides three preset templates:

Custom Template

Fully customizable request and extraction logic, suitable for special API formats.

Generic Template

Suitable for most providers with standard API formats:

({
  request: {
    url: "{{baseUrl}}/user/balance",
    method: "GET",
    headers: {
      "Authorization": "Bearer {{apiKey}}",
      "User-Agent": "cc-switch/1.0"
    }
  },
  extractor: function(response) {
    return {
      isValid: response.is_active || true,
      remaining: response.balance,
      unit: "USD"
    };
  }
})

Configuration parameters:

Parameter	Description
API Key	Authentication key (optional, uses provider's key if empty)
Base URL	API base URL (optional, uses provider's endpoint if empty)

New API Template

Designed specifically for New API-type proxy services:

({
  request: {
    url: "{{baseUrl}}/api/user/self",
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer {{accessToken}}",
      "New-Api-User": "{{userId}}"
    },
  },
  extractor: function (response) {
    if (response.success && response.data) {
      return {
        planName: response.data.group || "Default Plan",
        remaining: response.data.quota / 500000,
        used: response.data.used_quota / 500000,
        total: (response.data.quota + response.data.used_quota) / 500000,
        unit: "USD",
      };
    }
    return {
      isValid: false,
      invalidMessage: response.message || "Query failed"
    };
  },
})

Configuration parameters:

Parameter	Description
Base URL	New API service URL
Access Token	Access token
User ID	User ID

General Configuration

Timeout

Request timeout in seconds, default 10 seconds.

Auto Query Interval

Interval for automatically refreshing usage data (minutes):

• Set to 0 to disable auto query
• Range: 0-1440 minutes (up to 24 hours)
• Only effective when the provider is in "Currently Active" status

Extractor Return Format

The extractor function must return an object containing the following fields:

Field	Type	Required	Description
isValid	boolean	No	Whether the account is valid, defaults to true
invalidMessage	string	No	Message when invalid
remaining	number	Yes	Remaining balance
unit	string	Yes	Unit (e.g., USD, CNY, times)
planName	string	No	Plan name (supports multi-plan)
total	number	No	Total balance
used	number	No	Used amount
extra	object	No	Additional information

Test Script

After configuration, click the "Test Script" button to verify:

1. Sends a request to the configured URL
2. Executes the extractor function
3. Displays the returned result or error message

Display

After successful configuration, the provider card displays:

• Single plan: Directly shows remaining balance
• Multi-plan: Shows plan count, click to expand for details

Variable Placeholders

The following placeholders can be used in scripts and are automatically replaced at runtime:

Placeholder	Description
{{apiKey}}	Configured API Key
{{baseUrl}}	Configured Base URL
{{accessToken}}	Configured Access Token (New API)
{{userId}}	Configured User ID (New API)

Common Provider Configuration Examples

Troubleshooting

Auto Query Not Displayed (Official Subscription Types)

Check:

1. Confirm the provider is an official subscription type — Claude / Codex / Gemini official login, GitHub Copilot, or Codex OAuth reverse proxy
2. The provider is in "Currently Active" state (inactive providers do not trigger queries)
3. For OAuth types (Copilot / Codex OAuth), check whether the token is still valid; if the card shows "Session Expired", log in again in the OAuth Auth Center
4. Network access to the official quota endpoint

Manual Enable Still Not Showing Quota

Check:

1. Whether the Enable Usage Query toggle at the top of the "Usage Query" panel is on
2. Whether a suitable built-in template (Token Plan / third-party balance / custom) is selected
3. Click Test Script to see the specific error
4. Required fields such as API Key / Base URL are filled correctly
5. Network access to the provider's quota endpoint
6. Background auto-refresh only triggers when the provider is in "Currently Active" state

Query Failed

Check:

1. Is the API Key correct
2. Is the Base URL correct
3. Is the network accessible
4. Is the timeout sufficient

Empty Response Data

Check:

1. Does the extractor function have a return statement
2. Does the response data structure match the extractor
3. Use "Test Script" to view the raw response

Format Failed

When there is a script syntax error, clicking the "Format" button will indicate the error location.

Notes

• Usage queries consume a small amount of API request quota
• Set a reasonable auto query interval to avoid frequent requests
• Sensitive information (API Key, Token) is securely stored locally