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:

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

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