Retrieve qiyaov Platform API Call Records

Query detailed business API call records for the current account from the past 60 days, suitable for verifying charges, locating failed requests, and troubleshooting by service, Application, API, or credential.

This page queries the account's own call records. If you only want to view public call statistics for a specific API across the entire platform, please use API Call Statistics.

Preparation

1. Create an Account Token

This endpoint is a platform management API 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.

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

export PLATFORM_TOKEN='你的账户令牌'

Do not write the token into frontend code, logs, or public repositories; if it is leaked, immediately delete and recreate it in the console.

2. Prepare Filter IDs (Optional)

You can view records that the current account has permission to view without passing filter conditions. To narrow the scope:

Regular users do not need to pass user_id; if explicitly passed, it must match the current account, otherwise 403 is returned. Administrators can use this parameter to filter across accounts.

Endpoint Overview

Item Content
Method GET
URL https://api17.platform.acedata.cloud/api/v1/usage/apis/
Authentication Authorization: Bearer ${PLATFORM_TOKEN}
OAuth Scope usage:read (platform:read / platform can expand to include it)
Pagination count + items, 10 items per page by default

Query Scope

perspective Meaning
both Default value; returns records paid for or actually called by the current account
billing Returns only records paid for by the current account
actor Returns only records actually called by the current account

Query Parameters

Parameter Type Required Default Description
perspective string No both billing, actor, or both
user_id UUID No — Only administrators can filter by user; repeated parameters supported
service_id UUID No — Filter by service; repeated parameters supported
application_id UUID No — Filter by Application; repeated parameters supported
api_id UUID No — Filter by API; repeated parameters supported
credential_id UUID No — Filter by API credential; repeated parameters supported
status_code integer No — Filter by HTTP status code; repeated or comma-separated values supported
created_at_from datetime No — Lower bound of creation time, ISO 8601
created_at_to datetime No — Upper bound of creation time, ISO 8601
limit integer No 10 Number of items per page, maximum 100
offset integer No 0 Pagination offset
ordering string No -created_at Descending by creation time

When the request time is earlier than the past 60 days, the endpoint returns a 400 field validation error, indicating that complete call details are retained for only 60 days.

Request Examples

Query the latest 100 records:

curl --get 'https://api17.platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Filter by time, Application, and failure status:

export APPLICATION_ID='你的 Application ID'

curl --get 'https://api17.platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"

Python pagination example:

import os
import requests

url = "https://api17.platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])

Response Example

{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}

Key Fields

Field Description
user_id The account responsible for this charge
actor_user_id The account that actually initiated the call; may differ from user_id when authorizing others to use credentials
used_amount The usage for this call calculated according to the original rules
original_amount The original usage before application discounts
deducted_amount The final amount actually deducted
remaining_amount The remaining Application quota after this charge is completed
elapsed The call duration recorded by the server, in seconds
trace_id The tracing identifier used when investigating a single request
metadata Public metadata; the list does not return complete request or response content
api / service / credential Summaries of related objects for display; may be empty if the related object no longer exists

The quota unit is determined by the corresponding Application's service.unit and should not be assumed to be US dollars by default.

Errors and Retries

HTTP error Meaning Handling
400 Field validation error The query range is earlier than the 60-day retention period Adjust the start time to within the most recent 60 days
401 not_authenticated The account token is missing or invalid Check the Account Token; do not mistakenly use a business Credential
403 permission_denied The request includes records that you do not have permission to view Remove unauthorized user filter conditions
429 usage_query_in_progress An exactly identical query is still executing Retry with backoff after waiting for Retry-After
503 usage_query_timeout The query exceeds the server-side safety time limit Retry after narrowing the time range or adding filter conditions

At most one in-flight request is maintained for the same set of query parameters. For large-range queries, prioritize using windows of one day or less, and do not stack identical requests at fixed intervals.

Next Steps