Custom Costs

Docs > Cloud Cost Management > Custom Costs

Join the Beta!

Custom Cost is in public beta.

Overview

Custom Costs allow you to upload any cost data source to Datadog, so that you can understand the total cost of your services.

Custom Costs accepts costs in pre-defined file structures (CSV or JSON). These files are aligned with the FinOps FOCUS specification, and you can upload multiple files in either format. For example, you can upload a mix of CSV or JSON files as desired with 1+ line items (rows for CSV or objects for JSON).

All line items must meet the following requirements and include the properties below:

All column names (CSV), property names (JSON), and values are UTF-8 encoded.
All required column names (CSV) or property names (JSON) are PascalCased. For example, you must use "ProviderName", not "providername" or "ProviderNAME".
All column names (CSV) and values or property names (JSON) and values have a maximum of 1,000 characters.
NULL or blank ("") parameter values are not accepted.

Additionally, all dates are transformed into UTC timestamps. For example, “2024-01-01” becomes “2024-01-01 00:00:00”.

Setup

To use Custom Costs in Datadog, you must configure Cloud Cost Management for either AWS, Azure, or Google Cloud.

Collect the required fields

Parameter	Description	Valid example	Invalid example	Additional Requirements
`ProviderName`	The service being consumed.	Snowflake	"" or NULL
`ChargeDescription`	Identifies what aspect of a service is being charged.	Database Costs	"" or NULL
`ChargePeriodStart`	Start day of a charge.	2023-09-01	2023-01-01 12:34:56	Formatted YYYY-MM-DD, where `ChargePeriodStart` <= `ChargePeriodEnd`.
`ChargePeriodEnd`	Last day of a charge (inclusive).	2023-09-30	01/01/2023	Formatted YYYY-MM-DD.
`BilledCost`	The amount being charged.	10.00	NaN	Number-based decimal.
`BillingCurrency`	Currency of billed cost.	USD	EUR	Must be USD.

Create a CSV or JSON file with required fields

You can upload multiple CSV and JSON files, in either or both formats. Ensure that you don’t upload the same file twice, since the cost will appear as doubled in the product.

The required fields must appear as columns in your CSV in the order listed above. You need to use a comma (,) as a separator for your CSV.

Example of a valid CSV:

ProviderName	ChargeDescription	ChargePeriodStart	ChargePeriodEnd	BilledCost	BillingCurrency
GitHub	User Costs	2023-01-01	2023-01-31	300.00	USD

Example of an invalid CSV (ChargePeriodStart is listed before ChargeDescription):

ProviderName	ChargePeriodStart	ChargeDescription	ChargePeriodEnd	BilledCost	BillingCurrency
GitHub	2023-01-01	User Costs	2023-01-31	300.00	USD

The required fields must appear within all objects of a JSON file adhering to the ECMA-404 standard and all objects must be encapsulated by an array.

Example of a valid JSON file:

[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD"
    }
]

Example of an invalid JSON file:

[
    {
        "providername": "Zoom",
        "chargedescription": "Video Usage",
        "chargeperiodstart": "2023-01-01",
        "chargeperiodend": "2023-12-31",
        "billedcost": 100.00,
        "billingcurrency": "USD"
    }
]

Add optional tags

You can optionally add any number of tags to CSV or JSON files to allocate costs after the required fields as additional columns.

For a CSV file, add a column per tag.

Example of a valid CSV file:

ProviderName	ChargePeriodStart	ChargeDescription	ChargePeriodEnd	BilledCost	BillingCurrency	team	service
GitHub	2023-01-01	User Costs	2023-01-31	300.00	USD	web	ops

In this example, the team and service columns are added after the BillingCurrency column, and appears as tags on this cost.

For a JSON file, add a Tags object property to encapsulate any desired tags associated to this cost.

Example of a valid JSON file:

[
    {
        "ProviderName": "Zoom",
        "ChargeDescription": "Video Usage",
        "ChargePeriodStart": "2023-01-01",
        "ChargePeriodEnd": "2023-12-31",
        "BilledCost": 100.00,
        "BillingCurrency": "USD",
        "Tags": {
            "team": "web",
            "service": "ops"
        }
    }
]

In this example, an additional Tags object property has been added with two key-value pairs to allocate team and service tags to this cost.

Configure Custom Costs

After your data is formatted to the requirements above, upload your CSV and JSON files to Cloud Cost Management on the Custom Costs Files page or programmatically by using the API.

In Datadog:

Navigate to Infrastructure > Cloud Costs > Settings > Custom Costs.
Click the + Upload Costs button.

To send a file programmatically, use the PUT api/v2/cost/custom_costs API endpoint.

For example, using cURL:

curl -L -X PUT "" \
-H "Content-Type: multipart/form-data" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-F "file=${file};type=text/json"

To send the content of the file programmatically, use the PUT api/v2/cost/custom_costs endpoint.

For example, using cURL:

curl -L -X PUT "" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d '${file_content}'

Cost data appears in Datadog after 24 hours.

Cost metric types

You can visualize your ingested data using the following cost types:

Cost Type	Description
`custom.cost.amortized`	Total cost of resources accrued over an interval.
`custom.cost.basis`	Total cost of resources allocated at the time of usage over an interval.

All costs submitted to Custom Costs appear in these metrics. For example, if a $4 purchase was made on September 1, over the September 1-4 period, the following costs are attributed to each metric:

Days	`custom.cost.basis`	`custom.cost.amortized`
September 1	$4	$1
September 2	-	$1
September 3	-	$1
September 4	-	$1

Use Custom Costs data

You can view custom costs data on the Cloud Costs Analytics page, the Cloud Costs Tag Explorer, and in dashboards, notebooks, or monitors. You can also combine Custom Cost metrics with other cloud cost metrics or observability metrics.