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:

```javascript
({
  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:

```javascript
({
  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