Get AceDataCloud Platform API Call Volume Aggregation Statistics

Aggregate statistics of the current account's API call volume and consumption by time dimension (daily, weekly, monthly) — suitable for billing charts, monthly reports, and usage trend analysis. Much faster than querying /usages/ one by one and summing it yourself.

ℹ️ This interface belongs to the AceDataCloud Platform Management API, with a unified prefix of https://platform.acedata.cloud/api/v1/.

Interface Overview

Item Content
Method GET
URL https://platform.acedata.cloud/api/v1/usages/aggregate/
Authentication ✅ Requires account token

Authentication Instructions (How to Obtain Account Token)

Request Header:

Authorization: Bearer platform-v1-92eb****629c

For obtaining the token, see Manage AceDataCloud Platform Account Token.

Required Query Parameters

⚠️ Must include ?user_id=<your_user_id>.

To get user_id: Open https://auth.acedata.cloud/user/profile.

Query Parameters

Parameter Type Required Default Description
user_id UUID ✅ — Current account user ID
granularity string No day Aggregation granularity: hour / day / week / month
start_at datetime No — Start time (ISO8601 string)
end_at datetime No — End time (ISO8601 string)
application_id UUID No — Filter by Application
service_id UUID No — Filter by service
api_id UUID No — Filter by API
group_by string No time Grouping dimension: time / service / application / credential

Request Examples

cURL

USER_ID=89518d07-5560-4b05-92c1-667f3ddf6a4b
# Daily aggregation for the last 30 days
curl "https://platform.acedata.cloud/api/v1/usages/aggregate/?user_id=${USER_ID}&granularity=day&start_at=2026-03-26T00:00:00Z&end_at=2026-04-26T00:00:00Z" \
  -H 'authorization: Bearer platform-v1-92eb****629c'

# Grouped by service (to see which service is the most expensive)
curl "https://platform.acedata.cloud/api/v1/usages/aggregate/?user_id=${USER_ID}&group_by=service&start_at=2026-04-01T00:00:00Z" \
  -H 'authorization: Bearer platform-v1-92eb****629c'

Python

import requests

PLATFORM_TOKEN = "platform-v1-92eb****629c"
USER_ID = "89518d07-5560-4b05-92c1-667f3ddf6a4b"

# Monthly report: from April 1 to 26, grouped by service
resp = requests.get(
    "https://platform.acedata.cloud/api/v1/usages/aggregate/",
    headers={"authorization": f"Bearer {PLATFORM_TOKEN}"},
    params={
        "user_id": USER_ID,
        "group_by": "service",
        "start_at": "2026-04-01T00:00:00Z",
        "end_at": "2026-04-26T23:59:59Z",
    },
    timeout=20,
)
data = resp.json()
for row in data["items"]:
    print(f"  {row.get('service_title', row.get('service_id', '?')):30s}  "
          f"Calls {row['count']:>6,}  Cost {row['total_consumption']:>10.4f}")

Node.js

const USER_ID = '89518d07-5560-4b05-92c1-667f3ddf6a4b'
const url = new URL('https://platform.acedata.cloud/api/v1/usages/aggregate/')
url.searchParams.set('user_id', USER_ID)
url.searchParams.set('granularity', 'day')

const r = await fetch(url, {
  headers: { authorization: 'Bearer platform-v1-92eb****629c' },
})
console.log(await r.json())

Response Example

Aggregated by Time (group_by=time, default)

{
  "count": 30,
  "items": [
    {
      "time": "2026-04-01",
      "count": 1245,
      "total_consumption": 8.4521,
      "success_count": 1230,
      "failed_count": 15
    },
    {
      "time": "2026-04-02",
      "count": 902,
      "total_consumption": 6.1234,
      "success_count": 901,
      "failed_count": 1
    }
  ]
}

Aggregated by Service (group_by=service)

{
  "count": 5,
  "items": [
    {
      "service_id": "38ecf158-36f2-42f2-8e7f-6786cdfc2452",
      "service_title": "OpenAI",
      "count": 8203,
      "total_consumption": 142.3456,
      "success_count": 8190,
      "failed_count": 13
    },
    {
      "service_id": "5d732942-4d44-48be-958e-dd8474d8aa8d",
      "service_title": "Midjourney",
      "count": 432,
      "total_consumption": 78.9012,
      "success_count": 432,
      "failed_count": 0
    }
  ]
}

Response Field Descriptions

Each items element:

Field Type Description
time string Exists only when group_by=time, format depends on granularity
service_id / application_id / credential_id UUID Exists only when corresponding to group_by
service_title string Service name (localized) only when group_by=service
count integer Total number of calls
total_consumption number Total cost
success_count integer Number of 2xx calls
failed_count integer Number of 4xx + 5xx calls

Error Handling

HTTP Code Meaning
400 invalid Invalid value for granularity / group_by
401 not_authenticated Missing account token
403 permission_denied ?user_id= not provided or provided another's user_id

Practical Tips

  • Commonly used dashboard queries:
    • Daily trend for this month: ?granularity=day&start_at=beginning of this month
    • Service ranking for this month: ?group_by=service&start_at=beginning of this month
    • Credential consumption for this month: ?group_by=credential&start_at=beginning of this month — used to identify which credential is the most costly
  • Granularity hour only supports the last 7 days: Exceeding this will be limited to day.
  • Data has a 1-2 minute delay: The aggregation table is refreshed in batches, and the latest 1-2 minutes of calls may not yet be included.
  • Empty time periods will return an empty array: Time periods with no calls will not fill in 0 rows. The front-end drawing needs to fill in itself.