Today, Vantage announces the ability to manage and import business metrics via the API. Users can now automate the creation and ingestion of business metrics into Vantage, which can then be used for calculating unit costs on reports.
Previously, customers could import metrics from Amazon CloudWatch or by manually uploading a CSV; however, metrics are commonly stored in spreadsheets or external systems that Vantage does not natively integrate with. This process added a manual step for the user, who had to download the metrics to a CSV and log in to Vantage to upload the data. This manual step made it difficult to keep the metrics up to date.
Now, customers can create business metrics via the API and write a script to automate new data imports, on a daily basis. With the new /business_metrics endpoint, users can create, update, and delete business metrics. After creating a business metric, users can upload data and assign these business metrics to Cost Reports. Once assigned to underlying costs, this feature allows users to see the unit cost for the metric, such as Cost per Daily Active User or Cost per Request.
curl --request POST \
--url https://api.vantage.sh/v2/business_metrics \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"title": "Monthly Active Users",
"cost_report_tokens_with_metadata": [
{
"unit_scale": "per_unit",
"cost_report_token": "rprt_12abc345def678gh"
}
],
"values": [
{
"date": "2024-02-01",
"amount": 1512
}
]
}
'
This feature is now available for all users. To get started, navigate to the Business Metrics section of the API documentation. For more information about how to create and use unit costs and business metrics, see the product documentation.
Frequently Asked Questions
1. What is being launched today?
Today, Vantage is launching the ability to import time-series metrics, from arbitrary data sources, as business metrics using the Vantage API. These business metrics can be assigned to Cost Reports to visualize costs per unit.
2. Who is the customer?
The customer is any Vantage user who has time-series data in spreadsheets or external systems that they want to import into Vantage as a business metric.
3. How much does this cost?
This feature is free to all users.
4. What are business metrics, and how do I use them?
A business metric is any source of time-series data that you want to visualize on top of cost data to understand the “cost per” a given metric. An example of a business metric is daily active users or load balancer requests per second. When you create a Cost Report that’s filtered to a specific set of costs that correlate with a business metric, you can use this visualization to understand unit costs.
5. What is a unit scale?
A unit scale can be Per Unit, Per Hundred, Per Thousand, Per Million, or Per Billion. When you add a business metric to a report, you can select one of the above options as the business metric scale. The scale is used to divide the business metric before calculating the cost per unit. This scale allows you to create a per unit cost, such as Per Thousand Requests. If you select Per Unit, no division will take place, and the base metric number is used.
6. How do I create a business metric via the API?
Send a POST request to the /business_metrics endpoint. An example request that creates a new metric with two values is provided below. See the API documentation for more information.
curl --request POST \
--url https://api.vantage.sh/v2/business_metrics \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"title": "Monthly Active Users",
"cost_report_tokens_with_metadata": [
{
"unit_scale": "per_unit",
"cost_report_token": "rprt_12abc345def678gh"
}
],
"values": [
{
"date": "2024-02-01",
"amount": 1512
},
{
"date": "2024-02-05",
"amount": 1816
},
{
"date": "2024-02-10",
"amount": 1920
}
]
}
'
7. How do I upload new data via the API?
There are two methods to upload new data for a business metric.
To add new data, such as new values, send a PUT request to the /business_metrics/{business_metric_token} endpoint using the business metric’s token (in this example, bsnss_mtrc_123456789). The below example shows two new values added to an existing business metric. See the API documentation for more information.
curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_123456789 \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"values": [
{
"date": "2024-03-09",
"amount": 345
},
{
"date": "2024-03-10",
"amount": 356
}
]
}
'
You can also upload data via a CSV. Send a PUT request to the /business_metrics/{business_metric_token}/values.csv endpoint using the business metric’s token (in this example, bsnss_mtrc_123456789).
curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_123456789/values.csv \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: multipart/form-data' \
--form 'csv=@<PATH_TO_CSV>'
8. Can I overwrite existing data via the API?
Yes, you can send a PUT request to the /business_metrics/{business_metric_token} endpoint using the business metric’s token. To overwrite the amount for a particular date, include the new amounts in the values object. In the below example, the previous amount for a particular metric was 356. Here, it is updated to 359. The title is also updated. See the API documentation for more information.
curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_123456789 \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"title": "Daily Active Users",
"values": [
{
"date": "2024-03-10",
"amount": 359
}
]
}
'
9. Can I remove already imported data via the API?
You can completely delete a business metric by sending a DELETE request to the /business_metrics/{business_metric_token} endpoint using the business metric’s token. See the API documentation for more information.
If you want to remove values for certain dates, you can pass an empty value as the amount for that date. Send a PUT request to the /business_metrics/{business_metric_token} endpoint using the business metric’s token (in this example, bsnss_mtrc_123456789). In the below example, the existing amount is removed for March 10th.
curl --request PUT \
--url https://api.vantage.sh/v2/business_metrics/bsnss_mtrc_123456789 \
--header 'accept: application/json' \
--header 'authorization: Bearer <ACCESS_TOKEN>' \
--header 'content-type: application/json' \
--data '
{
"values": [
{
"date": "2024-03-10",
"amount": null
}
]
}
'
