Skip to main content
POST
/
cost-insights
/
compare
Compare costs across periods
curl --request POST \
  --url https://api.cloudcapital.co/v1/cost-insights/compare \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "baselinePeriod": {
    "start": "2026-02-01",
    "end": "2026-02-28"
  },
  "comparisonPeriod": {
    "start": "2026-01-01",
    "end": "2026-01-31"
  },
  "metric": "amortized_cost",
  "groupBy": {
    "dimension": "service",
    "dateGrouping": "daily"
  }
}
'
{
  "comparisons": [
    {
      "dimension_value": "<string>",
      "baseline": {
        "total": 123,
        "by_date": [
          {
            "date": "<string>",
            "value": 123
          }
        ]
      },
      "comparison": {
        "total": 123,
        "by_date": [
          {
            "date": "<string>",
            "value": 123
          }
        ]
      },
      "delta": {
        "absolute": 123,
        "percentage": 123,
        "direction": "increase"
      }
    }
  ],
  "totals": {
    "baseline": 123,
    "comparison": 123,
    "delta": {
      "absolute": 123,
      "percentage": 123,
      "direction": "increase"
    }
  },
  "metric_totals": {
    "amortized_cost": {
      "baseline": 123,
      "comparison": 123,
      "delta": {
        "absolute": 123,
        "percentage": 123,
        "direction": "increase"
      }
    },
    "on_demand_cost": {
      "baseline": 123,
      "comparison": 123,
      "delta": {
        "absolute": 123,
        "percentage": 123,
        "direction": "increase"
      }
    },
    "total_savings": {
      "baseline": 123,
      "comparison": 123,
      "delta": {
        "absolute": 123,
        "percentage": 123,
        "direction": "increase"
      }
    },
    "effective_savings_rate": {
      "baseline": 123,
      "comparison": 123,
      "delta": {
        "absolute": 123,
        "percentage": 123,
        "direction": "increase"
      }
    }
  },
  "metadata": {
    "baseline_period": {
      "start": "2026-01-01",
      "end": "2026-03-31"
    },
    "comparison_period": {
      "start": "2026-01-01",
      "end": "2026-03-31"
    },
    "metric": "amortized_cost",
    "baseline_label": "<string>",
    "comparison_label": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

API key authentication. Generate an API key from your Cloud Capital dashboard under Settings > API keys. Include it in the Authorization header as a Bearer token.

Body

application/json
​
baselinePeriod
object
required
​
comparisonPeriod
object
required
​
metric
enum<string>
required

Metric to compare across periods

Available options:
amortized_cost,
billed_cost,
cash_cost,
on_demand_cost,
total_savings,
commitment_savings,
spot_savings,
effective_savings_rate
​
groupBy
object
required
​
filters
object

Filters for comparison (same structure as Filters but without dateRange/billingPeriods since periods are specified explicitly).

Response

Comparison data retrieved successfully

​
comparisons
object[]

Per-dimension comparison results

​
totals
object

Overall totals for the selected metric

​
metric_totals
object

Totals for all key metrics (for summary cards)

​
metadata
object