> ## 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.

# Get cost data

> Retrieve cost data with flexible filtering and grouping options.
Results include a detailed cost breakdown per date and dimension,
plus an aggregated summary across the full period.




## OpenAPI

````yaml /api-reference/openapi.yaml post /cost-insights/data
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/data:
    post:
      tags:
        - Cost insights
      summary: Get cost data
      description: |
        Retrieve cost data with flexible filtering and grouping options.
        Results include a detailed cost breakdown per date and dimension,
        plus an aggregated summary across the full period.
      operationId: getCostData
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CostDataRequest'
            example:
              filters:
                inclusions:
                  dateRange:
                    start: '2026-01-01'
                    end: '2026-03-31'
                  accountIds:
                    - '123456789012'
              groupBy:
                dimension: account
                dateGrouping: monthly
      responses:
        '200':
          description: Cost data retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelopeBase'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/CostDataResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    CostDataRequest:
      type: object
      required:
        - groupBy
      properties:
        filters:
          $ref: '#/components/schemas/Filters'
        groupBy:
          $ref: '#/components/schemas/GroupBy'
    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.
    CostDataResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CostDataPoint'
        summary:
          $ref: '#/components/schemas/CostDataSummary'
    Filters:
      type: object
      description: |
        Filter container supporting both inclusion and exclusion criteria.
        Use `inclusions` to narrow results to matching data and `exclusions`
        to remove matching data from results.
      properties:
        inclusions:
          $ref: '#/components/schemas/FilterFields'
        exclusions:
          $ref: '#/components/schemas/FilterFields'
    GroupBy:
      type: object
      required:
        - dateGrouping
      description: |
        Grouping configuration. `dateGrouping` is required and controls
        the time-series granularity. Optionally specify `dimension` for
        single-dimension grouping or `dimensions` for multi-dimension.
      properties:
        dimension:
          type: string
          description: |
            Single grouping dimension. Accepts a `Dimension` enum value
            or a string for tag fields (e.g., `tag:environment`,
            `costCategory:department`).
          example: service
        dimensions:
          type: array
          items:
            type: string
          description: |
            Multi-dimension grouping. When provided, takes precedence
            over `dimension`.
          example:
            - account
            - service
        dateGrouping:
          $ref: '#/components/schemas/DateGrouping'
    CostDataPoint:
      type: object
      properties:
        usage_date:
          type: string
          description: Date for this data point (YYYY-MM-DD)
          example: '2026-01-15'
        dimension_value:
          type: string
          description: Value of the grouping dimension for this row
        dimension_values:
          type: object
          additionalProperties:
            type: string
          description: Per-dimension values when using multi-dimension groupBy
        amortized_cost:
          type: number
          format: double
          description: >-
            Amortized cost — upfront commitment fees spread evenly across the
            commitment term
        billed_cost:
          type: number
          format: double
          description: Actual billed cost as it appears on the AWS invoice
        cash_cost:
          type: number
          format: double
          description: >-
            Cash cost — upfront fees recognised in the period they were charged,
            not amortized
        on_demand_cost:
          type: number
          format: double
          description: >-
            Equivalent cost at on-demand rates, before any discounts or
            commitments
        total_savings:
          type: number
          format: double
          description: Total savings across all sources (commitment, Spot, discounts)
        enterprise_discount_savings:
          type: number
          format: double
          description: Savings from AWS Enterprise Discount Programme (EDP) agreements
        product_discount_savings:
          type: number
          format: double
          description: Savings from AWS product-level discounts
        partner_discount_savings:
          type: number
          format: double
          description: Savings from AWS Partner discount arrangements
        commitment_savings:
          type: number
          format: double
          description: Savings from Reserved Instances and Savings Plans commitments
        spot_savings:
          type: number
          format: double
          description: Savings from AWS Spot Instance usage compared to on-demand rates
        other_savings:
          type: number
          format: double
          description: >-
            Savings from all other discount sources not captured in the above
            categories
    CostDataSummary:
      type: object
      description: Aggregated totals across the full queried period
      properties:
        total_amortized_cost:
          type: number
          format: double
          description: Sum of amortized cost across the full queried period
        total_billed_cost:
          type: number
          format: double
          description: Sum of billed cost across the full queried period
        total_cash_cost:
          type: number
          format: double
          description: Sum of cash cost across the full queried period
        total_on_demand_cost:
          type: number
          format: double
          description: Sum of on-demand equivalent cost across the full queried period
        total_savings:
          type: number
          format: double
          description: Sum of total savings across all sources and the full queried period
        total_enterprise_discount_savings:
          type: number
          format: double
          description: Sum of enterprise discount savings across the full queried period
        total_product_discount_savings:
          type: number
          format: double
          description: Sum of product discount savings across the full queried period
        total_partner_discount_savings:
          type: number
          format: double
          description: Sum of partner discount savings across the full queried period
        total_commitment_savings:
          type: number
          format: double
          description: Sum of commitment savings across the full queried period
        total_spot_savings:
          type: number
          format: double
          description: Sum of Spot Instance savings across the full queried period
        total_other_savings:
          type: number
          format: double
          description: Sum of all other savings across the full queried period
        effective_savings_rate:
          type: number
          format: double
          description: >-
            Effective Savings Rate (ESR) — total savings divided by total
            on-demand cost
    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.
    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
    DateGrouping:
      type: string
      enum:
        - daily
        - weekly
        - monthly
      description: Time granularity for cost data aggregation
    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'
  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.

````