Check Remaining Quota for an Fishapi Cloud 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

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

  1. Log in to the Fishapi Cloud 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 Fishapi Cloud 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 there is no corresponding Application yet, please first read Create an Application.

Step 3: Query Details

Item Content
Method GET
URL https://fishapi.platform.acedata.cloud/api/v1/applications/{application_id}
Authentication Authorization: Bearer ${PLATFORM_TOKEN} 
curl --fail-with-body \
  "https://fishapi.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,
  "allow_overdraft": false,
  "expired_at": null,
  "service": {
    "id": "00000000-0000-4000-8000-000000000002",
    "title": "Example Service",
    "unit": "Credit"
  }
}
  • remaining_amount: The remaining quota for the current Application. A negative value indicates quota pending settlement.
  • allow_overdraft: Whether overdraft has been approved, defaulting to false. After an administrator enables it, metered (Usage) applications can still be called and billed normally when the balance is insufficient; top-ups will offset the negative balance, and accumulated usage will not be reset. This field is read-only and cannot be enabled by customers themselves. Disabling, expiration, and API credential limits still apply.
  • service.unit: The quota unit, such as Credit, Count, or Token; do not assume it is in US dollars.
  • disabled / expired_at: Even if the balance remains greater than zero, check whether the Application has been disabled or expired.

When proxy services suspend 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 URL, account token, and field names for balance queries 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://fishapi.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 not application.get("allow_overdraft", False) and float(remaining) < minimum_balance:
    raise RuntimeError(f"Application balance is insufficient: {remaining} {unit}")

Production monitoring should use reasonable frequencies and timeouts; do not poll at high frequency. To check multiple services at once, prioritize using user_id=me with List Applications to retrieve the list in one request, then let the monitoring program determine based on each service's unit and threshold, rather than requesting details one by one.

Frequently Asked Questions

HTTP / Status Cause Handling
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 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 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 Application has expired Renew before calling business APIs

Next Steps