> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcapital.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Compare costs across periods

> Compare costs between two time periods. Returns per-dimension
comparisons with absolute and percentage deltas, plus aggregated
totals for all key metrics.




## OpenAPI

````yaml /api-reference/openapi.yaml post /cost-insights/compare
openapi: 3.0.3
info:
  title: Cloud Capital Public API
  description: >
    The Cloud Capital Public API provides programmatic access to cost insights

    data. Use this API to query cloud cost data, apply filters, compare costs

    across time periods, and manage shared filter configurations.


    **Response shape:** Successful responses are JSON objects with `success:
    true`

    and a `data` property holding the endpoint-specific payload. Error responses

    use `success: false` and an `error` object with a `message` string.
  version: 1.0.0
  contact:
    email: support@cloudcapital.co
servers:
  - url: https://api.cloudcapital.co/v1
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /cost-insights/compare:
    post:
      tags:
        - Cost insights
      summary: Compare costs across periods
      description: |
        Compare costs between two time periods. Returns per-dimension
        comparisons with absolute and percentage deltas, plus aggregated
        totals for all key metrics.
      operationId: compareCosts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompareRequest'
            example:
              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
      responses:
        '200':
          description: Comparison data retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelopeBase'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CompareResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CompareRequest:
      type: object
      required:
        - baselinePeriod
        - comparisonPeriod
        - metric
        - groupBy
      properties:
        baselinePeriod:
          $ref: '#/components/schemas/DateRange'
        comparisonPeriod:
          $ref: '#/components/schemas/DateRange'
        metric:
          $ref: '#/components/schemas/ComparisonMetric'
        groupBy:
          type: object
          required:
            - dateGrouping
          properties:
            dimension:
              type: string
              description: Grouping dimension (Dimension enum value or tag string)
            dateGrouping:
              $ref: '#/components/schemas/DateGrouping'
        filters:
          type: object
          description: |
            Filters for comparison (same structure as Filters but without
            dateRange/billingPeriods since periods are specified explicitly).
          properties:
            inclusions:
              $ref: '#/components/schemas/FilterFields'
            exclusions:
              $ref: '#/components/schemas/FilterFields'
    SuccessEnvelopeBase:
      type: object
      description: |
        Successful HTTP responses wrap the endpoint-specific body in `data`.
        Each operation's `200` response schema is this object merged (`allOf`)
        with a `data` property referencing the payload schema for that endpoint.
      required:
        - success
      properties:
        success:
          type: boolean
          enum:
            - true
          description: Always `true` when the HTTP status is 2xx.
    CompareResponse:
      type: object
      properties:
        comparisons:
          type: array
          items:
            $ref: '#/components/schemas/DimensionComparison'
          description: Per-dimension comparison results
        totals:
          type: object
          properties:
            baseline:
              type: number
              format: double
            comparison:
              type: number
              format: double
            delta:
              $ref: '#/components/schemas/ComparisonDelta'
          description: Overall totals for the selected metric
        metric_totals:
          type: object
          description: Aggregated totals for all key metrics across both periods
          properties:
            amortized_cost:
              $ref: '#/components/schemas/MetricComparisonTotal'
            on_demand_cost:
              $ref: '#/components/schemas/MetricComparisonTotal'
            total_savings:
              $ref: '#/components/schemas/MetricComparisonTotal'
            effective_savings_rate:
              $ref: '#/components/schemas/MetricComparisonTotal'
        metadata:
          type: object
          properties:
            baseline_period:
              $ref: '#/components/schemas/DateRange'
            comparison_period:
              $ref: '#/components/schemas/DateRange'
            metric:
              $ref: '#/components/schemas/ComparisonMetric'
            baseline_label:
              type: string
              description: Pre-formatted label for baseline period (e.g., "Jan 1-31, 2026")
            comparison_label:
              type: string
              description: Pre-formatted label for comparison period
    DateRange:
      type: object
      required:
        - start
        - end
      properties:
        start:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Start date in YYYY-MM-DD format
          example: '2026-01-01'
        end:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: End date in YYYY-MM-DD format
          example: '2026-03-31'
    ComparisonMetric:
      type: string
      enum:
        - amortized_cost
        - billed_cost
        - cash_cost
        - on_demand_cost
        - total_savings
        - commitment_savings
        - spot_savings
        - effective_savings_rate
      description: Metric to compare across periods
    DateGrouping:
      type: string
      enum:
        - daily
        - weekly
        - monthly
      description: Time granularity for cost data aggregation
    FilterFields:
      type: object
      description: |
        Filter criteria. All fields are optional. When multiple fields
        are specified they are combined with AND logic; values within a
        single field use OR logic.
      properties:
        costLayers:
          type: array
          items:
            type: string
          description: Cost layer names
        clouds:
          type: array
          items:
            type: string
          description: Cloud provider names
        services:
          type: array
          items:
            type: string
          description: Cloud service names
        resourceFamilies:
          type: array
          items:
            type: string
          description: Resource family names
        regions:
          type: array
          items:
            type: string
          description: Cloud region codes
        instanceTypes:
          type: array
          items:
            type: string
          description: Instance type identifiers
        usageTypes:
          type: array
          items:
            type: string
          description: Usage type identifiers
        billingPeriods:
          type: array
          items:
            type: string
          description: Billing periods in yyyy-MM format (legacy; prefer dateRange)
        dateRange:
          $ref: '#/components/schemas/DateRange'
        costTypes:
          type: array
          items:
            type: string
          description: Cost type identifiers
        accountIds:
          type: array
          items:
            type: string
          description: AWS account IDs
        integrationIds:
          type: array
          items:
            type: string
          description: Integration IDs
        resourceTag:
          type: string
          description: A single resource tag key to filter by
        resourceTagValues:
          type: array
          items:
            type: string
          description: Values for the specified resourceTag
        costCategory:
          type: string
          description: A single cost category key to filter by
        costCategoryValues:
          type: array
          items:
            type: string
          description: Values for the specified costCategory
    DimensionComparison:
      type: object
      properties:
        dimension_value:
          type: string
        baseline:
          $ref: '#/components/schemas/PeriodTotals'
        comparison:
          $ref: '#/components/schemas/PeriodTotals'
        delta:
          $ref: '#/components/schemas/ComparisonDelta'
    ComparisonDelta:
      type: object
      properties:
        absolute:
          type: number
          format: double
          description: Absolute change between periods
        percentage:
          type: number
          format: double
          nullable: true
          description: Percentage change (null when comparison total is 0)
        direction:
          type: string
          enum:
            - increase
            - decrease
            - unchanged
    MetricComparisonTotal:
      type: object
      properties:
        baseline:
          type: number
          format: double
        comparison:
          type: number
          format: double
        delta:
          $ref: '#/components/schemas/ComparisonDelta'
    ErrorEnvelope:
      type: object
      description: |
        Most error responses from the API use this shape. The HTTP status code
        indicates the class of error (e.g. `400` validation, `429` rate limit,
        `500` server).
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
          description: Always `false` when the HTTP status is an error.
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: Human-readable error description
    ApiGatewayUnauthorized:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          example: Unauthorized
          description: Fixed message when authentication fails at the gateway.
    PeriodTotals:
      type: object
      properties:
        total:
          type: number
          format: double
        by_date:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
              value:
                type: number
                format: double
  responses:
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              message: >-
                Invalid request. Please see message details.. Invalid input:
                expected object, received undefined (at groupBy)
    Unauthorized:
      description: >
        Missing or invalid API key. The API returns this compact body from the

        gateway (not the `success` / `error` envelope used for application
        errors).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiGatewayUnauthorized'
          example:
            message: Unauthorized
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests in the current window
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              message: Rate limit exceeded. Please retry after the specified time.
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: |
        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.

````