byted-volcengine-finops

Volcengine Bill Skill

This Skill is used to query Cost Center bill data through the Volcengine Python SDK, and perform summary analysis around billing period, amortization month, date, instance, product, account, and split dimensions.

When to Use This Skill

When the user requests:

Analyzing Volcengine bills, costs, and consumption trends
Querying account-level bill overview information
Querying product-level cost distribution
Verifying bill details, instance fees, or bill types
Querying amortized costs, amortized cost bills, or cost bill details
Querying split bills, split item fees, or allocation results

Main Features

1. Account bill overview query

Use ListBillOverviewByCategory to query the account-level bill overview
Suitable for first viewing the overall monthly bill amount and overall trends

2. Product monthly bill query

Use ListBillOverviewByProd to query monthly bills for a single product, multiple products, or all products
Supports paginated retrieval of the complete product list
Suitable for identifying high-cost products and main sources of expenses

3. Bill details and split bill query

Use ListBillDetail to query bill details
Use ListAmortizedCostBillDetail to query cost bill details
Use ListSplitBillDetail to query split bills
Supports filtering by billing period, amortization month, date, product, account, instance, and split item

4. Configuration and invocation methods

Supports environment variable configuration AK/SK
Supports .env file configuration
Supports Python code invocation
Supports direct invocation through standalone scripts under scripts/ Supports paginated retrieval and local summary analysis
Supports JSON structured result processing
Processing logic

Bill query processing flow

Determine the interface according to the user's goal

Use
- for the overall bill ListBillOverviewByCategory
- Use ListBillOverviewByProd
- for monthly product bills ListBillDetail
- Use ListAmortizedCostBillDetail
- for detail verification ListSplitBillDetail
Determine the billing period and date range according to time requirements
- Prioritize determining BillPeriod
- For cost bills, prioritize determining AmortizedMonth
- Supplement with ExpenseDate
- when a detailed single-day check is needed AmortizedDay
- Cross-month queries need to be split into multiple billing periods and queried separately
Assemble SDK request parameters according to filter conditions
- For example, product, account, instance, bill type, split item, etc.
If it is a paginated interface, query in a loop
- Use Offset + Limit + NeedRecordNum to paginate and retrieve the full amount
- You can use common.py in fetch_all_pages utility function to automatically turn pages
Perform summary analysis on the results
- Output amounts, rankings, abnormal fluctuations, and items to be verified

Prerequisites

The Volcengine Python SDK needs to be installed:

pip install --upgrade "volcengine-python-sdk>=5.0.30"

Note:

It is recommended to use the latest 5.x version
Historical versions 4.0.1 ~ 4.0.42 have SDK retry defects, so try not to continue using them

Configuration method

The Volcengine Access Key and Secret Key need to be configured. One of the following two methods is recommended:

Method 1: Environment variables

export VOLCENGINE_AK="your-ak"
export VOLCENGINE_SK="your-sk"
export VOLCENGINE_REGION="cn-beijing"

Method 2:`.env` file

In ~/.openclaw/workspace/.env configure:

VOLCENGINE_AK=your-ak
VOLCENGINE_SK=your-sk
VOLCENGINE_REGION=cn-beijing

Billing parameter description

Core billing query parameters

BillPeriod: Billing period, in the format YYYY-MM
ExpenseDate: Bill date, in the format YYYY-MM-DD
AmortizedMonth: Allocation month, in the format YYYY-MM
AmortizedDay: Allocation day, in the format YYYY-MM-DD
Offset: Pagination offset
Limit: Number per page, range [1,300]
NeedRecordNum: Whether to return the total number of records,1 returns Total, otherwise it is usually -1
IgnoreZero: Whether to ignore data with a discounted price of 0,0 do not ignore,1 ignore
Product: Product filter condition. For optional product Codes, refer to references/product-code.md

Key parameter enumeration values

Parameter	Value	Meaning
`BillingMode`	`1`	Subscription
	`2`	Pay-as-you-go
	`3`	Contract billing
	`4`	Performance billing
`BillCategoryParent`	`consume`	Consumption
	`refund`	Refund
	`transfer`	Adjustment
`BillCategory`	`consume-use`	Consumption-Usage
	`consume-new`	Consumption-New purchase
	`consume-renew`	Consumption-Renewal
	`consume-formalize`	Consumption-Conversion to regular
	`consume-modify`	Consumption-Configuration change
	`consume-trial`	Consumption-Trial
	`refund-terminate`	Refund-Unsubscribe
	`refund-modify`	Refund-Configuration change
	`transfer-manual`	Adjustment-Manual
	`transfer-system`	Adjustment-System
`GroupTerm`	`0`	Billing item
	`1`	Instance
	`2`	Product
	`3`	Account
`GroupPeriod`	`0`	Billing period
	`1`	Daily
	`2`	Details
`AmortizedType`	`1`	Performance billing allocation
	`2`	Contract billing allocation
	`3`	Pay-as-you-go billing allocation
	`4`	New purchase allocation
	`5`	Configuration change allocation
	`6`	Renewal allocation
	`7`	Unsubscribe allocation
	`8`	Reserved instance adjustment allocation
	`9`	Trial allocation
	`10`	Conversion to regular allocation
`SplitDimension`	JSON string	Split dimension, such as `{"ark_bd":"apikey_id"}`, an error will be reported if the product does not support multi-dimensional splitting

Time parameter description

BillPeriod is the core time parameter for bill queries, queried by month
AmortizedMonth is the core time parameter for cost bill queries, queried by month
If a single-day filter is not specified, the query is performed by the whole month by default
To query a certain day within a single month, you can add ExpenseDate
To query the cost allocation for a certain day within a single month, you can add AmortizedDay
If the user provides a cross-month date range, it needs to be split into multiple BillPeriod for separate queries and then aggregated
If the user provides a cross-month cost range, it needs to be split into multiple AmortizedMonth for separate queries and then aggregated

Pagination parameter description

ListBillOverviewByProd
ListBillDetail
ListAmortizedCostBillDetail
ListSplitBillDetail

The above four interfaces should all be handled with pagination.

Recommended strategy:

Offset starts from 0 Start
Limit prefer 100 or 300
NeedRecordNum set to 1
After each query completes, use Offset += Limit to continue fetching
If the number returned is less than Limit, or the cumulative count covers Total, then end pagination
You can directly use common.py the fetch_all_pages tool function to automatically paginate

fetch_all_pages Usage example:

from common import build_billing_api, fetch_all_pages
import volcenginesdkbilling

api = build_billing_api()

# 自动拉取全量账单明细
rows = fetch_all_pages(
    api_instance=api,
    request_cls=volcenginesdkbilling.ListBillDetailRequest,
    list_method_name="list_bill_detail",
    raw_kwargs={"BillPeriod": "2025-05"},
    limit=100,
)
print(f"共拉取 {len(rows)} 条记录")

Returned fields quick reference

The return structure of all APIs is Result.List + Result.Total(paginated APIs); for complete field definitions, see references/billing-api-notes.md. The following are the most commonly used business fields for each API:

Common amount fields (ListBillOverviewByCategory / ListBillOverviewByProd / ListBillDetail)

Field	Description	Common scenarios
`PayableAmount`	Amount payable	Cost ranking, general ledger reconciliation
`OriginalBillAmount`	Original price	Amount before discount
`DiscountBillAmount`	Discounted price	Post-discount basis
`PreferentialBillAmount`	Discount amount	Discounts excluding vouchers
`CouponAmount`	Voucher deduction	View separately from discount amount
`PaidAmount`	Amount paid	Reconciliation
`UnpaidAmount`	Outstanding amount	Identify unsettled amounts

Common dimension fields (ListBillDetail / ListSplitBillDetail / ListAmortizedCostBillDetail)

Field	Description	Common scenarios
`Product` / `ProductZh`	Product English / Chinese name	Aggregation by product dimension
`Region` / `RegionCode`	Region	Regional cost analysis
`Zone` / `ZoneCode`	Availability zone	Availability zone-level attribution
`InstanceNo` / `InstanceName`	Instance ID / name	Single-instance troubleshooting
`Project` / `ProjectDisplayName`	Project information	Cost attribution
`Tag`	Tag JSON	Tag attribution
`BillCategory`	Bill type	Distinguish consumption/refund/adjustment
`BillingMode`	Billing mode	Distinguish subscription/pay-as-you-go
`ConfigName`	Configuration name	SKU description

ListSplitBillDetail-specific fields

Field	Description	Remarks
`SplitItemID` / `SplitItemName`	Split item ID / name	Split billing primary key
`SplitItemAmount` / `SplitItemRatio`	Split item usage / proportion	Meaningful in detail mode
`CouponDeductionAmount`	Voucher deduction	Note: not `CouponAmount`

ListAmortizedCostBillDetail-specific fields

Field	Description	Remarks
`AmortizedMonth` / `AmortizedDay`	Allocation month / allocation day	Cost attribution time
`AmortizedType`	Allocation type	New purchase/renewal/configuration change, etc.
`DailyAmortizedPayableAmount`	Daily allocated amount payable	Main field for cost analysis
`DailyAmortizedDiscountBillAmount`	Daily allocated discounted price	Post-discount basis
`DailyAmortizedOriginalBillAmount`	Daily allocated original price	Original price basis

Core API description

For the complete request parameter and response parameter definitions of each API, see references/billing-api-notes.md; the following are the minimal parameter templates.