Billing queries and export

Select a period, inspect consumption statistics, and export Excel billing records.

Billing statistics aggregate model usage, call counts, and amounts by time interval. Excel records are for saving and offline review.

Prepare an access token

Create an access token under “Security” on your profile, then enter it in Try It for Query billing statistics or Export billing records.

Choose the period and filters

Select the interval, such as “Day” for daily totals.
Enter start/end Unix timestamps in seconds, or use the date picker on the right. It converts browser-local dates; for full days, check that the end time includes the entire day.
Fill in a name only to filter a specific API Key or model; leave both fields empty to include all matching records.

Filter	Required	Usage
Interval `type`	Yes	1=minute, 2=hour, 3=day, 4=week, 5=month
Start and end	Yes	`startTime`, `endTime` in seconds; end cannot precede start
API Key name `tokenName`	No	Name, not a secret Key or access token; omit to avoid name filtering
Model name `modelName`	No	Actual model name; omit to avoid model filtering

Query and inspect statistics

Submit filters in Try It for Query billing statistics. Body code=200 indicates business success; data is an array of aggregate records, not individual call logs.

time, timeGroup: record time and second-based grouping timestamp.
callCount, totalUseTime: call count and total duration.
totalPromptTokens, totalCompletionTokens, and cache fields: input, output, and cache usage.
totalAmount: amount consumed. See the Reference for fields and complete examples; Token usage is not a monetary amount.

code: 200 with data: [] means the query succeeded but no records match the period and filters.

Some optional fields may be null; do not treat them as 0.

Export Excel billing records

Submit the same filters in Try It for Export billing records. After a successful file response:

Verify the export period shown in the result.
Keep the generated period-based filename or edit “File name”; the .xlsx extension is retained automatically.
Click “Download Excel billing records” to save locally.

Filename dates use the browser's local timezone. The platform generates Excel contents and columns; renaming does not change them. Use identical periods, intervals, and name filters when comparing statistics with exports.

HTTP 200 does not guarantee export success: handle JSON business errors first; do not save them as .xlsx.

Troubleshooting

Symptom	Action
Successful query without records	Check timestamp units and dates, then clear name filters
Business `code: 401`, authentication failed	Check the access token; contact support if a valid token still fails
Export business `code: 400`, parameter validation failure	Check the interval and both timestamps
Export business `code: 500`, `ERROR`	Check JSON syntax and parameter types; contact an administrator if correct input still fails
Download cannot open in Excel	Check Content-Type; ensure a JSON business error was not saved as Excel

These export business errors may use HTTP 200; do not rely on HTTP status alone. See the corresponding Reference for complete examples.

See current model prices in the model marketplace.

Call from your application

The Bash example requires curl and jq, covering authentication, statistics, and saving Excel.

Combine the following three blocks in order into one .sh file. Replace the access token and period, then run with bash; do not paste the blocks separately into an interactive terminal.

The example covers 2026-10-10 00:00:00 through 2026-10-20 23:59:59, Beijing time, grouped by day with no name filters. Replace with your required period.

1. Obtain billing authentication

Call GET /api/user/self using the access token, parse token from data.remark, then use it for billing on the same site. The access token authenticates the first step with Bearer; it cannot directly replace the billing token Header.

set -euo pipefail

ACCESS_TOKEN='your-user-token'

BILLING_TOKEN=$(curl --fail --silent --show-error "https://api.agtcloud.cn/api/user/self" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" | \
  jq -er '
    select(.success == true)
    | .data.remark | fromjson | .token
    | select(type == "string" or type == "number")
    | tostring | select(length > 0)
  ')

2. Query statistics

curl --fail-with-body "https://api.agtcloud.cn/bill/stats" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "type": 3,
    "startTime": 1791561600,
    "endTime": 1792511999
  }'

Read JSON code to determine business success, not just cURL's exit status. Root timestamp is in milliseconds, unlike the second-based query times.

3. Validate and save Excel

Success must be an application/vnd.openxmlformats-officedocument.spreadsheetml.sheet stream, not a JSON business error.

The following writes to a temporary file first. It saves as bill_export.xlsx only for HTTP 200, Excel Content-Type, and nonempty contents. An existing file is never overwritten.

response_file=$(mktemp './.bill_export.XXXXXX')
[[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]] || exit 1
trap 'if [[ "$response_file" == ./.bill_export.* && -f "$response_file" && ! -L "$response_file" ]]; then rm -f -- "$response_file"; fi' EXIT

response_meta=$(curl --silent --show-error "https://api.agtcloud.cn/bill/excel" \
  -X POST \
  -H "token: ${BILLING_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
  "type": 3,
  "startTime": 1791561600,
  "endTime": 1792511999
}' \
  --output "$response_file" \
  --write-out '%{http_code}\n%{content_type}')

http_status=${response_meta%%$'\n'*}
content_type=${response_meta#*$'\n'}
if [[ "$http_status" != 200 || "${content_type%%;*}" != application/vnd.openxmlformats-officedocument.spreadsheetml.sheet || ! -s "$response_file" ]]; then
  printf 'Export failed: HTTP %s (%s)\n' "$http_status" "$content_type" >&2
  if [[ "${content_type%%;*}" == application/json ]]; then
    jq '{code, message}' "$response_file" >&2
  fi
  exit 1
fi

if [[ -e bill_export.xlsx || -L bill_export.xlsx ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
mv -n -- "$response_file" bill_export.xlsx
if [[ -e "$response_file" ]]; then
  printf 'bill_export.xlsx already exists; choose another filename.\n' >&2
  exit 1
fi
printf 'Saved bill_export.xlsx\n'