Report API

Summary

The report endpoint replaces functions earlier split across a variety of container APIs. This provides a singular view of the data powering the container insights.

This endpoint allows analysis of data by specifying aggregated metrics combined with groups and filters for gathering cost.

End point

/containers/report

Query Parameters

Request Body

The report request body is a JSON object consisting of:

Supported Cost Types

Supported Metric Values

Request-table fields

Supported Widget Types

Supported Group, Count and Filter Values

Groups, Counts, and Filters share a overlapping set of accessible data, which can be utilized as:

• Groups returning results aggregated by unique values in that field. For example, grouping by cluster would return a result set that is isolated by cluster.
• Counts returning a result section identifying the number of unique entries. For example, a count of namespaces would return the total number of namespaces within the selection.
• Filters allowing a user to limit the result set to a subset of results. For example, supplying a filter of workload_type==deployment would only return results for workloads identified as being owned by a deployment.

Using Filters

Filters can be configured by:

• Filtered Attribute: Any value denoted as filterable in the table.
• Operator
  • ==Equals (case sensitive)
  • []=One of (case sensitive)
• Filtered Value: Values that the user wants to filter upon.

Examples: namespace==kube-system filters results to only show data for kube-system.

workload_type[]=cronjob,job filters results to only show data for cronjobs or jobs,

Supported Sort Configurations

The sort feature sorts out data by the first specified metric column in descending order by default. You can set this up to ensure pagination is always possible.

You can sort values in any order, specifying the requested metric value.

The example below sorts rows by efficiency in descending order, and then by total_cost in descending order.

[
  {
    "sortMetric": "total_cost_efficiency",
    "sortOrder": "desc"
   },
   {
     "sortMetric": "total_cost",
     "sortOrder": "desc"
   }
 ]

Pagination

If the above data for pagination indicates that another page is available for consumption, then the value in nextToken can be passed back into the API via the pagination Token parameter.

Example Request

[
  curl --location 'https://api.usgov.cloudability.com/v3/containers/report?pretty=true' \
-H "apptio-opentoken: ${token}" \
-H "apptio-environmentid: ${env_id}"
-H "Content-type: application/json" \
--data '{
    "start": "2025-08-01",
    "end": "2025-08-05",
    "costType": "adjusted",
    "metrics": [
        "total_cost_fairshare"
    ],
    "group": [
        "namespace"
    ],
    "sort": [
        {
            "sortMetric": "total_cost_fairshare",
            "sortOrder": "desc"
        }
    ],
    "widgetType": "top",
    "limit": 1
}'

Sample Response

[
  {
  "result": {
    "data": [
      {
        "dimensions": {
          "namespace": "cloudability"
        },
        "metrics": {
          "total_cost_fairshare": {
            "unit": "currency",
            "values": [
              7.996368043
            ]
          }
        }
      }
    ],
    "pagination": {
      "hasNext": true,
      "nextToken": "veryLongPaginationToken"
    }
  }
}

The response body consists of :