Check the Remaining Balance of an qiyaov Application

This guide helps you complete the 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

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

  1. Log in to the qiyaov 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'

For complete instructions, see Manage qiyaov Platform Account Tokens. Account tokens are used for platform.acedata.cloud/api/v1/**; API credentials (Credentials) are used for calling api.acedata.cloud/** business APIs, and the two cannot be used interchangeably.

Do not write tokens into frontend code, logs, or public repositories; if leaked, 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 there is no corresponding Application yet, please first read Create a Service Application.

Step 3: Query Details

Item Content
Method GET
URL https://api17.platform.acedata.cloud/api/v1/applications/{application_id}
Authentication Authorization: Bearer ${PLATFORM_TOKEN} 
curl --fail-with-body \
  "https://api17.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 USD.
  • disabled / expired_at: Even if the balance is still greater than zero, check whether the Application has been disabled or expired.

For complete response fields and error models, see Application Details.

Python Low-Balance Check

import os
import requests

minimum_balance = 10
response = requests.get(
    f"https://api17.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"Insufficient Application balance: {remaining} {unit}")

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

Frequently Asked Questions

HTTP / Status Cause Resolution
401 Account Token is missing, invalid, or deleted Recreate the account token; do not replace it with a business Credential
403 The Application does not belong to the current account or access is denied Obtain the ID again from the current account's application list
404 The Application ID does not exist Check the environment variables and the copied ID
disabled=true The Application is 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