docs/user-manual/en/2-providers/2.5-usage-query.md
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) |
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.
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.
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.
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.
⚠️ Note: The auto-refresh interval after enabling is controlled by the "Auto Query Interval" field (set to
0to disable auto-refresh). Background queries only trigger when the provider is in "Currently Active" state.
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:
At the top of the configuration panel, enable the "Enable Usage Query" toggle.
CC Switch provides three preset templates:
Fully customizable request and extraction logic, suitable for special API formats.
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) |
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 |
Request timeout in seconds, default 10 seconds.
Interval for automatically refreshing usage data (minutes):
0 to disable auto queryThe 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 |
After configuration, click the "Test Script" button to verify:
After successful configuration, the provider card displays:
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) |
Check:
Check:
Check:
Check:
return statementWhen there is a script syntax error, clicking the "Format" button will indicate the error location.