External Costs API

Note: External Costs can only be queried after you have configured at least one external service with Kubecost. You can learn how to integrate Datadog through this method in our External Costs doc.

External Costs API summary query

Using the External Costs API

GET http://<your-kubecost-address>/model/customCost/timeseries

Samples costs of connected third party services.

Table 1. Path Parameters
Name Required Type Description
window true string Duration of time over which to query. Accepts multiple different formats of time (see this Using the window parameter section for more info).
aggregate false string Field by which to aggregate the results. Accepts: zone, accountName, chargeCategory, description, resourceName, resourceType, providerId, usageUnit, domain, and costSource. Supports multi-aggregation using comma-separated lists. Example: aggregate=zone,description
accumulate false boolean When set to false, this endpoint returns daily time series data vs cumulative data. Default value is false.
filter false string Filter your results by any category which you can aggregate by, can support multiple filterable items in the same category in a comma-separated list. For example, to filter results by charge categories usage and billing, use filter=chargeCategory:usage,billing See our Filter Parameters doc for a complete explanation of how to use filters and what categories are supported.
Table 2. Responses
Code Description Example
200 OK 
{
  "code": 200,
  "data": {
    "window": {
      "start": "2024-04-07T00:00:00Z",
      "end": "2024-04-09T00:00:00Z"
    },
    "timeseries": [
      {
        "window": {
          "start": "2024-04-07T00:00:00Z",
          "end": "2024-04-07T01:00:00Z"
        },
        "totalBilledCost": 0,
        "totalListCost": 0,
        "customCosts": [
          {
            "id": "",
            "zone": "",
            "account_name": "",
            "charge_category": "",
            "description": "",
            "resource_name": "",
            "resource_type": "",
            "provider_id": "",
            "billedCost": 0,
            "listCost": 0,
            "list_unit_price": 0,
            "usage_quantity": 0,
            "usage_unit": "",
            "domain": "datadog",
            "cost_source": "observability",
            "aggregate": "__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/datadog/observability"
          }
        ]
      }
    ]
  }
}

External Costs API total query

Using the External Costs API total query

GET http://<your-kubecost-address>/model/customCost/total

Samples costs of connected third party services, but summarizes subwindows into singular window of total cost. Can be compared to /topline endpoint of other APIs.

Table 3. Path Parameters
Name Required Type Description
window true string Duration of time over which to query. Accepts multiple different formats of time (see theUsing the window parameter section for more info).
aggregate false string Field by which to aggregate the results. Accepts: zone, accountName, chargeCategory, description, resourceName, resourceType, providerId, usageUnit, domain, and costSource. Supports multi-aggregation using comma-separated lists. Example: aggregate=zone,description
accumulate false boolean When set to false, this endpoint returns daily time series data vs cumulative data. Default value is false.
filter false string Filter your results by any category which you can aggregate by, can support multiple filterable items in the same category in a comma-separated list. For example, to filter results by charge categories usage and billing, use filter=chargeCategory:usage,billing See our Filter Parameters doc for a complete explanation of how to use filters and what categories are supported.
Table 4. Responses
Code Description Example
200 OK 
{
  "code": 200,
  "data": {
    "window": {
      "start": "2024-04-07T00:00:00Z",
      "end": "2024-04-09T00:00:00Z"
    },
    "totalBilledCost": 0,
    "totalListCost": 0,
    "customCosts": [
      {
        "id": "",
        "zone": "",
        "account_name": "",
        "charge_category": "",
        "description": "",
        "resource_name": "",
        "resource_type": "",
        "provider_id": "",
        "billedCost": 0,
        "listCost": 0,
        "list_unit_price": 0,
        "usage_quantity": 0,
        "usage_unit": "",
        "domain": "datadog",
        "cost_source": "observability",
        "aggregate": "__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/__unallocated__/datadog/observability"
      }
    ]
  }
}