Retrieve 灵蛇AI 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 an API across the entire platform, please use API Call Statistics.

Data Retention Scope

Call records and billing summaries are retained for the past 60 days; request and response bodies are retained for the past 30 days. Records from 30–60 days ago can still be queried for summaries such as trace, status, time, model, usage, and actual charges, but metadata.request and metadata.response in the details will no longer be returned. Summaries required for model aggregation and valid result statistics will be retained until the bodies expire. If you need to retain bodies long-term, please save them yourself when making calls.

Preparation

1. Create an Account Token

This endpoint is a platform management API and requires an Account Token:

  1. Log in to the 灵蛇AI 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 灵蛇AI Platform Account Tokens. Account tokens are used for platform.acedata.cloud/api/v1/**; API credentials (Credential) are used to call api.acedata.cloud/** business endpoints, and the two cannot be used interchangeably.

export PLATFORM_TOKEN='你的账户令牌'

Do not write tokens into frontend code, logs, or public repositories; if exposed, delete and recreate them immediately 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 passed explicitly, 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://opensnake.platform.acedata.cloud/api/v1/usage/apis/
Authentication Authorization: Bearer ${PLATFORM_TOKEN}
OAuth Scope usage:read (platform:read / platform may 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; supports repeated parameters
service_id UUID No — Filter by service; supports repeated parameters
application_id UUID No — Filter by Application; supports repeated parameters
api_id UUID No — Filter by API; supports repeated parameters
credential_id UUID No — Filter by API credential; supports repeated parameters
status_code integer No — Filter by HTTP status code; supports repeated or comma-separated values
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 Items per page, maximum 100
offset integer No 0 Pagination offset
ordering string No -created_at Descending order 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://opensnake.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://opensnake.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://opensnake.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 deduction
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 calculated for this call according to the original rules
original_amount The original usage before application discounts
deducted_amount The amount actually deducted in the end
remaining_amount The remaining Application quota after this deduction is completed
elapsed The call duration recorded by the server, in seconds
trace_id The trace 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 convenient display; may be empty when related objects no longer exist

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 without viewing permission Remove unauthorized user filter conditions
429 usage_query_in_progress An identical query is still in progress 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 a one-day or smaller window, and do not stack identical requests at fixed intervals.

Next Steps