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

# 2.5 Usage Query

## Overview

The usage query feature allows you to configure custom scripts to query a provider's remaining balance, used amount, and other information in real time.

**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

### 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