> ## 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 available filters

> Retrieve available filter values with cross-filtering support.
Returns the set of valid filter options based on the current
filter selection, allowing progressive refinement of queries.

When filters are provided, each requested field's options are
computed with all *other* active filters applied (cross-filtering).




## OpenAPI

````yaml /api-reference/openapi.yaml post /cost-insights/filters
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/filters:
    post:
      tags:
        - Cost insights
      summary: Get available filters
      description: |
        Retrieve available filter values with cross-filtering support.
        Returns the set of valid filter options based on the current
        filter selection, allowing progressive refinement of queries.

        When filters are provided, each requested field's options are
        computed with all *other* active filters applied (cross-filtering).
      operationId: getFilters
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FiltersRequest'
            example:
              fields:
                - accounts
                - services
              filters:
                inclusions:
                  dateRange:
                    start: '2026-01-01'
                    end: '2026-03-31'
      responses:
        '200':
          description: Filter values retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SuccessEnvelopeBase'
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        $ref: '#/components/schemas/FiltersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    FiltersRequest:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FilterField'
          description: |
            Specific filter fields to return. When omitted, all available
            filter fields are returned.
        filters:
          $ref: '#/components/schemas/Filters'
    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.
    FiltersResponse:
      type: object
      description: |
        Available filter values. Each field contains an array of valid
        values. The `enriched` field provides cost and availability
        metadata for cross-filterable fields.
      properties:
        costLayers:
          type: array
          items:
            type: string
        clouds:
          type: array
          items:
            type: string
        services:
          type: array
          items:
            type: string
        resourceFamilies:
          type: array
          items:
            type: string
        regions:
          type: array
          items:
            type: string
        instanceTypes:
          type: array
          items:
            type: string
        usageTypes:
          type: array
          items:
            type: string
        billingPeriods:
          type: array
          items:
            type: string
        costTypes:
          type: array
          items:
            type: string
        accounts:
          type: array
          items:
            type: string
        accountIdToName:
          type: object
          additionalProperties:
            type: string
          description: Map of account IDs to human-readable account names
        integrations:
          type: array
          items:
            type: string
        resourceTags:
          type: array
          items:
            type: string
        tagValues:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Map of tag keys to their available values
        costCategories:
          type: array
          items:
            type: string
        enriched:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/EnrichedFilterOption'
          description: |
            Enriched options with cost and availability data, keyed by
            field name. Only populated for cross-filterable fields.
    FilterField:
      type: string
      enum:
        - costLayers
        - clouds
        - services
        - resourceFamilies
        - regions
        - instanceTypes
        - usageTypes
        - billingPeriods
        - costTypes
        - accounts
        - integrations
        - resourceTags
        - costCategories
      description: |
        Filter field names for the filters endpoint. Pass these in the
        `fields` array to request specific filter option sets.
    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'
    EnrichedFilterOption:
      type: object
      properties:
        value:
          type: string
        amortizedCost:
          type: number
          format: double
          description: Total amortized cost for this filter value
        available:
          type: boolean
          description: Whether this value is available given current cross-filters
    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
    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.

````