Retrieve Aggregated API Usage Statistics on the WorldAi Platform

Summarize the current account's request count and actual deducted quota by date and API, suitable for creating monthly reports, trend charts, and cost analysis. Use the Call Record List when troubleshooting item by item, and use Usage Export when complete offline details are needed.

The query range for call records and billing summaries is the most recent 60 days; request and response bodies are retained separately for the most recent 30 days. Body expiration does not change the actual charge, usage, or aggregate statistics of the record.

Preparations

  1. Log in to the WorldAi Platform.
  2. Create an account token in the Account Token Console, and save it immediately.
  3. To narrow the scope, obtain the corresponding ID from the Service Application List, API Credential List, or API List.

For complete token instructions, see Manage Account Tokens. This API uses an Account Token, not a business Credential.

export PLATFORM_TOKEN='your account token'

API Overview

Item Content
Method GET
URL https://worldai.platform.acedata.cloud/api/v1/usage/apis/aggregate/
Authentication Authorization: Bearer ${PLATFORM_TOKEN}
OAuth Scope usage:read (included by expansion of platform:read / platform)
Permission Scope Regular users are fixed to their own paid usage; administrators can pass user_id

Query Parameters

Parameter Type Required Default Description
created_at_from date / datetime No The first day of the current month in the selected timezone Start time, recommended parameter name
created_at_to date / datetime No Current time End time, recommended parameter name
timezone string No UTC IANA timezone, for example Asia/Shanghai; invalid values fall back to UTC
service_id UUID No — Filter by service; repeated parameters are supported
application_id UUID No — Filter by Application; repeated parameters are supported
api_id UUID No — Filter by API; repeated parameters are supported
credential_id UUID No — Filter by API credential; repeated parameters are supported
include_models boolean No false Whether to additionally calculate model-dimension aggregates; increases query cost
user_id UUID No Regular users are fixed to themselves; all accounts for administrators when not passed Only administrators can specify any account

start_time / end_time can still be used as backward-compatible aliases for older clients. New integrations should consistently use created_at_from / created_at_to. A date-form created_at_to includes that calendar day, using midnight of the next day as the boundary.

Request Examples

Query daily/API aggregates for the current month in Beijing time, with model dimensions included:

curl --get 'https://worldai.platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Query one week's usage for a specified Application:

export APPLICATION_ID='your Application ID'

curl --get 'https://worldai.platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Python example:

import os
import requests

response = requests.get(
    "https://worldai.platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])

Response Example

{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}

Response Fields

Field Description
items Grouped by date in the selected timezone and api_id; each row contains date, api_id, and amount
total Sum of deducted_amount within the query range
apis Mapping from API ID to title summary, for displaying items
requests Total number of requests within the query range
models Calculated only when include_models=true; each item contains model, amount, and requests

The quota unit depends on the service.unit of the associated Application. If the query includes services with different units, first calculate them separately by service_id or application_id to avoid directly comparing or adding them.

When the end time is not greater than the start time, the API returns a complete empty structure: items=[], total=0, apis={}, requests=0, models=[].

Error and Performance Recommendations

HTTP error Handling Method
400 usage_history_expired Adjust the time range to after available_from in the response
401 not_authenticated Check the Account Token; do not mistakenly use a business Credential
403 permission_denied Regular users cannot query other accounts
  • Do not enable include_models by default; enable it only when the report truly requires model breakdowns.
  • For large-range queries, prioritize separating them by service_id or application_id; this both avoids mixed units and reduces query cost.
  • Dates without calls are not automatically filled with zero; the client should fill in the date axis before charting.

Next Steps