APIs
The Billing Metrics API provides detailed insights into resource usage across Orgs (i.e. tenants). It aggregates usage data by compute instance and SKU (service profile) and calculates billable parameters such as storage usage. This data is essential for generating accurate billing reports.
This guide provides an overview of the Rafay PaaS Billing Metrics API, which enables you to retrieve usage data and calculate billable parameters for compute and service profiles. The examples below demonstrate how to use the API in real-world billing scenarios. This documentation is based on the Rafay PaaS Billing Metrics API Documentation and includes specific scenarios and examples.
Note
Usage units are expressed in decimal hours with a scale of 2. For example, if 100 GB of storage is used for 12 hours, the usage is calculated as 1200h.
Billable Parameters and Labels¶
Billable parameters are attributes that affect the cost calculation. Parameters are attributes/variables marked in the template as billable parameters. These attributes or variables can affect the billing. Each parameter can have labels that can affect the billing of the entities defined by the parameter. The parameters can also be labels, where the value is non-quantitative.
Examples:
Storage Parameters¶
A label can be storage_type and take values such as file, object, or block.
CPU Parameters¶
A label can be cpu_arch and take values such as x86, arm64, or amd64.
GPU Parameters¶
A label can be model of a GPU and accept values such as Nvidia H100, A100, or A40s.
Usage Units¶
Usage units are always in decimal hours with a scale of 2 (i.e., 0.01h = 36 seconds). The usage of parameters like storage_size, cpu_count, gpu_count, memory_size, etc., will represent the total usage of a single resource of the lowest unit.
Examples:
- If 100GB storage is used for 12 hours, the usage will be: 100GB x 12h = 1200h
- If 8GB RAM is used for 48 hours, the usage will be: 8GB x 48h = 384h
- If 2 instances of 2 GPUs (A100) each are used for 24 hours, the usage will be: 2 x 2 x 24h = 96h
API Endpoints¶
Instance Usage API (All Orgs)¶
This endpoint retrieves aggregate usage per compute instance across all orgs (tenants) along with associated billable parameters.
API Request:
GET https://{{controller-url}}/apis/billing.envmgmt.io/v1/metrics/partner/instance/kind/compute/usage?range_from=2025-01-18T00:00:00Z&range_to=2025-01-19T00:00:00Z&offset=0&limit=10
Sample Response:
{
"kind": "compute",
"partner_id": "4qkolkn",
"organization_id": "7w2lnkp",
"start_time": "2025-01-18T00:00:00Z",
"end_time": "2025-01-19T00:00:00Z",
"instance_usage_data": [
{
"instance_organization_id": "7dkgjkx",
"profile_id": "01943ac0-d90b-7357-91b9-14abfb99c14f",
"profile_name": "computeprofile-1",
"instance_id": "86209fbc-6caf-4560-a7be-46d1e7e381a6",
"instance_name": "computeinstance-1",
"usage": "24h",
"parameters": [
{
"name": "storage",
"usage": "2400h",
"labels": {
"storage_type": "file"
}
},
{
"name": "region",
"usage": "24h",
"is_label": true,
"value": "us-east"
}
]
}
// Additional instance data...
],
"count": 5,
"offset": 0,
"limit": 10
}
Instance Usage API for a Particular Org¶
Retrieve aggregate usage per instance for a specified org (tenant).
API Request:
GET https://{{controller-url}}/apis/billing.envmgmt.io/v1/metrics/partner/instance/kind/compute/usage?instance_organization_id=7dkgjkx&range_from=2025-01-18T00:00:00Z&range_to=2025-01-19T00:00:00Z&offset=0&limit=10
Sample Response:
{
"kind": "compute",
"partner_id": "4qkolkn",
"organization_id": "7w2lnkp",
"start_time": "2025-01-18T00:00:00Z",
"end_time": "2025-01-19T00:00:00Z",
"instance_usage_data": [
{
"instance_organization_id": "7dkgjkx",
"profile_id": "01943ac0-d90b-7357-91b9-14abfb99c14f",
"profile_name": "computeprofile-1",
"instance_id": "86209fbc-6caf-4560-a7be-46d1e7e381a6",
"instance_name": "computeinstance-1",
"usage": "24h",
"parameters": [
{
"name": "storage",
"usage": "2400h",
"labels": {
"storage_type": "file"
}
},
{
"name": "region",
"usage": "24h",
"is_label": true,
"value": "us-east"
}
]
}
// Additional instance data...
],
"count": 4,
"offset": 0,
"limit": 10
}
Usage of All SKUs Across All Orgs¶
Aggregate usage data per SKU (or compute profile) across all Orgs (tenants).
API Request:
GET https://{{controller-url}}/apis/billing.envmgmt.io/v1/metrics/partner/profile/kind/compute/usage?range_from=2025-01-18T00:00:00Z&range_to=2025-01-19T00:00:00Z&offset=0&limit=10
Sample Response:
{
"kind": "compute",
"partner_id": "4qkolkn",
"organization_id": "7w2lnkp",
"start_time": "2025-01-18T00:00:00Z",
"end_time": "2025-01-19T00:00:00Z",
"profile_usage_data": [
{
"instance_organization_id": "7dkgjkx",
"profile_id": "01943ac0-d90b-7357-91b9-14abfb99c14f",
"profile_name": "computeprofile-1",
"usage": "43.51h",
"parameters": [
{
"name": "storage",
"usage": "3375.5h",
"labels": {
"storage_type": "file"
}
},
{
"name": "storage",
"usage": "975.5h",
"labels": {
"storage_type": "object"
}
}
]
},
{
"instance_organization_id": "7dkgjkx",
"profile_id": "019472fe-4d64-7906-a451-64d529f96061",
"profile_name": "computeprofile-2",
"usage": "30.29h",
"parameters": [
{
"name": "storage",
"usage": "1514.5h",
"labels": {
"storage_type": "file"
}
}
]
}
// Additional SKU data...
],
"count": 3,
"offset": 0,
"limit": 10
}
Usage of All SKUs for a Particular Org¶
Aggregate usage data per SKU for a given Org (tenant).
API Request:
GET https://{{controller-url}}/apis/billing.envmgmt.io/v1/metrics/partner/profile/kind/compute/usage?instance_organization_id=7dkgjkx&range_from=2025-01-18T00:00:00Z&range_to=2025-01-19T00:00:00Z&offset=0&limit=10
Sample Response:
{
"kind": "compute",
"partner_id": "4qkolkn",
"organization_id": "7w2lnkp",
"start_time": "2025-01-18T00:00:00Z",
"end_time": "2025-01-19T00:00:00Z",
"profile_usage_data": [
{
"instance_organization_id": "7dkgjkx",
"profile_id": "01943ac0-d90b-7357-91b9-14abfb99c14f",
"profile_name": "computeprofile-1",
"usage": "43.51h",
"parameters": [
{
"name": "storage",
"usage": "3375.5h",
"labels": {
"storage_type": "file"
}
},
{
"name": "storage",
"usage": "975.5h",
"labels": {
"storage_type": "object"
}
}
]
},
{
"instance_organization_id": "7dkgjkx",
"profile_id": "019472fe-4d64-7906-a451-64d529f96061",
"profile_name": "computeprofile-2",
"usage": "30.29h",
"parameters": [
{
"name": "storage",
"usage": "1514.5h",
"labels": {
"storage_type": "file"
}
}
]
}
],
"count": 2,
"offset": 0,
"limit": 10
}