Billing Usage API, gRPC: ConsumptionCoreService.GetSKUUsageReport
Returns aggregated usage report by SKU (Stock Keeping Unit)
under the specified billing account.
This method provides detailed usage and cost information grouped by SKUs
within the specified billing account. SKUs are specific billable product offerings
(such as specific VM types, disk types, or AI models) that belong to a parent service.
The data can be filtered by various entity types and aggregated at different time granularities.
Implementation details:
- Results are organized by SKU, with each SKU's usage, costs, and credits detailed
- If sku_ids are specified, only data for those SKUs is included (using OR logic)
- When no sku_ids are specified, data for all SKUs under the billing account is returned
- Other filters (cloud_ids, folder_ids, service_ids, resource_ids, labels) are always applied if present
- SKU data includes pricing quantity, unit of measurement, and translated display names
- Provides the most granular view of which specific product offerings are generating costs
Error handling:
- Returns INVALID_ARGUMENT if the request parameters fail validation
- Returns UNAUTHENTICATED if the user is not authenticated or the billing account does not exist
- Returns PERMISSION_DENIED if the user lacks required permissions
- Returns INTERNAL for internal server errors
gRPC request
rpc GetSKUUsageReport (UsageReportRequest) returns (SKUUsageReportResponse)
UsageReportRequest
{
"billing_account_id": "string",
"start_date": "google.protobuf.Timestamp",
"end_date": "google.protobuf.Timestamp",
"cloud_ids": [
"string"
],
"folder_ids": [
"string"
],
"service_ids": [
"string"
],
"sku_ids": [
"string"
],
"labels": "map<string, LabelList>",
"resource_ids": [
"string"
],
"aggregation_period": "TimeGrouping"
}
Request for retrieving usage report data.
This message defines the parameters for requesting usage reports across
all ConsumptionCoreService methods. It supports filtering by various
entity types and specifying the time range and aggregation period.
|
Field |
Description |
|
billing_account_id |
string Required field. Required. Billing account identifier. |
|
start_date |
Required field. Required. Inclusive start date for metrics selection (UTC). |
|
end_date |
Required field. Required. Inclusive end date for metrics selection (UTC). |
|
cloud_ids[] |
string Optional. List of cloud IDs to filter the data. |
|
folder_ids[] |
string Optional. List of folder IDs to filter the data. |
|
service_ids[] |
string Optional. List of Service IDs to filter the data. |
|
sku_ids[] |
string Optional. List of SKU (Stock Keeping Unit) IDs to filter the data. |
|
labels |
object (map<string, LabelList>) Optional. Filter by labels: key is label key (e.g., "env", "team", "region"), Example: To filter resources that have either (env=prod OR env=test) AND (team=finance), Note: The filter logic is (value1 OR value2 OR ...) for each key, |
|
resource_ids[] |
string Optional. List of resource IDs to filter the data. |
|
aggregation_period |
enum TimeGrouping Optional. Aggregation granularity for the report, controlling how data points are grouped
This setting affects the time series data returned in the periodic field of each entity.
|
LabelList
Represents a list of label values for filtering or grouping in usage reports.
For example, to filter resources with label key "env" that have value "prod" or "test",
a LabelList with values ["prod", "test"] would be used for the key "env".
|
Field |
Description |
|
values[] |
string List of label values associated with a specific label key. |
SKUUsageReportResponse
{
"currency": "Currency",
"cost": {
"value": "string"
},
"credit_details": {
"credit": {
"value": "string"
},
"monetary_grant_credit": {
"value": "string"
},
"volume_incentive_credit": {
"value": "string"
},
"cud_credit": {
"value": "string"
},
"free_credit": {
"value": "string"
}
},
"expense": {
"value": "string"
},
"entities_data": [
{
"cost": {
"value": "string"
},
"credit_details": {
"credit": {
"value": "string"
},
"monetary_grant_credit": {
"value": "string"
},
"volume_incentive_credit": {
"value": "string"
},
"cud_credit": {
"value": "string"
},
"free_credit": {
"value": "string"
}
},
"expense": {
"value": "string"
},
"pricing_quantity": {
"value": "string"
},
"sku": {
"id": "string",
"name": "string",
"ru_translation": "string",
"en_translation": "string",
"pricing_unit": "string",
"service_id": "string"
},
"periodic": [
{
"cost": {
"value": "string"
},
"credit_details": {
"credit": {
"value": "string"
},
"monetary_grant_credit": {
"value": "string"
},
"volume_incentive_credit": {
"value": "string"
},
"cud_credit": {
"value": "string"
},
"free_credit": {
"value": "string"
}
},
"expense": {
"value": "string"
},
"timestamp": "google.protobuf.Timestamp"
}
]
}
]
}
Response for usage report requests by SKU.
Contains aggregated usage, cost, and credit information organized by SKU (Stock Keeping Unit) entities,
with both summary totals and detailed breakdowns for each SKU. SKUs are specific billable offerings
(like particular VM types or disk types) that belong to a parent service.
The response includes:
- Overall totals for the entire period (cost, credits, expense)
- Entity-level totals for each SKU
- Time series breakdown for each SKU according to the requested aggregation period
|
Field |
Description |
|
currency |
enum Currency Currency code (e.g., "RUB", "USD") for all monetary values in the response.
|
|
cost |
Total usage cost for the selected time period. |
|
credit_details |
Total credits (monetary grants, volume incentives, committed use discounts, and free credits) applied in the selected period. |
|
expense |
Total expense (including cost and credit) for the selected time period. |
|
entities_data[] |
Detailed usage and billing data for each SKU entity.
|
StringDecimal
StringDecimal representation for financial values
Used to ensure precise handling of monetary values
|
Field |
Description |
|
value |
string String representation of the decimal value to avoid floating-point precision issues |
CreditDetails
Detailed breakdown of credits (discounts, incentives, grants, etc.) applied to an entity.
Credits reduce the effective cost that customers pay for cloud resources.
The 'credit' field is the total amount of credits (the sum of all credit types below).
This breakdown allows for detailed analysis of different discount types affecting billing.
|
Field |
Description |
|
credit |
Total amount of credits (sum of all credit types) applied to the entity. |
|
monetary_grant_credit |
Credits granted as a one-time monetary grant. |
|
volume_incentive_credit |
Credits given as a volume-based incentive. |
|
cud_credit |
Committed Use Discount credits. |
|
free_credit |
Credits provided as part of a 'free' program. |
SKUUsageReportEntityData
Usage and billing data for a SKU entity in the report.
This represents the second level in the response structure hierarchy (entity-level totals),
containing both summary data for the entity across the entire period and a time series breakdown.
|
Field |
Description |
|
cost |
Total cost associated with this entity. |
|
credit_details |
Total credits (discounts, grants, adjustments) applied to this entity. |
|
expense |
Total expense (including cost and credit) for this entity. |
|
pricing_quantity |
Total resource usage (pricing quantity) for this entity, measured in pricing units. |
|
sku |
Metadata for a product/SKU entity. |
|
periodic[] |
Time series with usage and billing details for each TimeGrouping period (e.g., daily). |
SKU
Represents a SKU (Stock Keeping Unit)
|
Field |
Description |
|
id |
string Unique identifier of the entity (SKU). |
|
name |
string Product (SKU) name. |
|
ru_translation |
string Russian-language display name |
|
en_translation |
string English-language display name |
|
pricing_unit |
string Unit of measurement for pricing (e.g., "hour", "byte", "1m*request"). |
|
service_id |
string The service ID this SKU belongs to; |
UsageReportPeriodicData
Represents usage and billing data for a specific aggregation period (e.g., a single day, month).
This message is part of the third level in the response structure hierarchy, providing the
time series breakdown for entities. It appears in the 'periodic' field of each entity data object,
containing financial metrics for each time interval within the requested date range.
|
Field |
Description |
|
cost |
Cost incurred during this specific period. |
|
credit_details |
Credits applied during this period. |
|
expense |
Total expense (including cost and credit) for this period. |
|
timestamp |
Timestamp indicating the beginning of the TimeGrouping period. |