Check Remaining Balance of an 灵蛇AI Application

This guide helps you complete a balance check for a single Application from scratch: create an account token, find the Application ID, request details, and read remaining_amount. It is suitable for health checks and low-balance alerts; see Application Details for the complete field contract.

Step 1: Create an Account Token

Querying the balance is a platform management operation and requires an Account Token:

  1. Log in to the 灵蛇AI Platform.
  2. Open the Account Token Console.
  3. Click "Create" and immediately save the token to a password manager or Secret Manager.
export PLATFORM_TOKEN='your account token'

See Manage 灵蛇AI Platform Account Tokens for complete instructions. Account tokens are used for platform.acedata.cloud/api/v1/**; API credentials (Credential) are used to call api.acedata.cloud/** business APIs, and the two cannot be used interchangeably.

Do not write tokens into frontend code, logs, or public repositories; if exposed, delete and recreate them immediately.

Step 2: Find the Application ID

An Application represents an account's application or subscription relationship for a service. You can:

export APPLICATION_ID='your Application ID'

If you do not yet have a corresponding Application, first read Create an Application.

Step 3: Query Details

Item Content
Method GET
URL https://opensnake.platform.acedata.cloud/api/v1/applications/{application_id}
Authentication Authorization: Bearer ${PLATFORM_TOKEN} 
curl --fail-with-body \
  "https://opensnake.platform.acedata.cloud/api/v1/applications/${APPLICATION_ID}" \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Step 4: Read the Balance and Unit

{
  "id": "00000000-0000-4000-8000-000000000001",
  "remaining_amount": 98.75,
  "used_amount": 21.25,
  "disabled": false,
  "expired_at": null,
  "service": {
    "id": "00000000-0000-4000-8000-000000000002",
    "title": "Example Service",
    "unit": "Credit"
  }
}
  • remaining_amount: The remaining balance of the current Application.
  • service.unit: The balance unit, such as Credit, Count, or Token; do not assume it is in US dollars.
  • disabled / expired_at: Even when the balance remains greater than zero, check whether the Application has been disabled or expired.

When proxy services pause balance synchronization or synchronization times out, the most recently saved balance will be returned. This value does not represent the service's current availability; please also check the service status. The balance query URL, account token, and field names remain unchanged.

See Application Details for complete response fields and error models.

Python Low-Balance Check

import os
import requests

minimum_balance = 10
response = requests.get(
    f"https://opensnake.platform.acedata.cloud/api/v1/applications/{os.environ['APPLICATION_ID']}",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    timeout=10,
)
response.raise_for_status()
application = response.json()

remaining = application.get("remaining_amount")
unit = application.get("service", {}).get("unit", "unknown")
if remaining is None:
    raise RuntimeError("Application did not return an available balance; please check its type and status")
if float(remaining) < minimum_balance:
    raise RuntimeError(f"Application balance is insufficient: {remaining} {unit}")

Production monitoring should use reasonable intervals and timeouts; do not poll at high frequency. To check multiple services at once, prioritize using user_id=me in the Application List to retrieve the list in one request, then have the monitoring program determine based on the unit and threshold of each service, rather than requesting details individually.

Frequently Asked Questions

HTTP / Status Cause Handling
401 Account Token is missing, invalid, or deleted Create a new account token; do not replace it with a business Credential
403 The Application does not belong to the current account or there is no access permission Retrieve the ID again from the current account's application list
404 The Application ID does not exist Check the environment variable and copied ID
disabled=true The Application has been disabled Check the service status in the console or contact support
expired_at has expired The subscription-based Application has expired Renew before calling the business API

Next Steps