Amazon Billing And Cost Management Cost And Usage API

openapi: 3.1.0
info:
  title: AWS Budgets Anomaly Detection Cost And Usage API
  description: The AWS Budgets API enables programmatic creation and management of custom budgets that track AWS cost, usage, coverage, and utilization. Supports budget actions that automatically respond when thresholds are exceeded.
  version: '2016-10-20'
  contact:
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
servers:
- url: https://budgets.amazonaws.com
  description: AWS Budgets (Global endpoint)
security:
- aws_iam: []
tags:
- name: Cost And Usage
  description: Query cost and usage data
paths:
  /GetCostAndUsage:
    post:
      operationId: GetCostAndUsage
      summary: Get Cost And Usage
      description: Retrieves cost and usage metrics for your account. You can specify which cost and usage-related metric that you want the request to return, and filter and group your data by various dimensions, such as SERVICE or AZ, in a specific time range.
      tags:
      - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostAndUsageRequest'
      responses:
        '200':
          description: Cost and usage data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostAndUsageResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
        '500':
          $ref: '#/components/responses/LimitExceededException'
  /GetCostAndUsageWithResources:
    post:
      operationId: GetCostAndUsageWithResources
      summary: Get Cost And Usage With Resources
      description: Retrieves cost and usage metrics with resources for your account. Supports resource-level data for EC2 instances.
      tags:
      - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetCostAndUsageRequest'
      responses:
        '200':
          description: Cost and usage with resources returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCostAndUsageResponse'
        '400':
          $ref: '#/components/responses/DataUnavailableException'
  /GetDimensionValues:
    post:
      operationId: GetDimensionValues
      summary: Get Dimension Values
      description: Retrieves all available filter values for a specified filter over a period of time. For example, you can search the EC2 cost category entries for a specific month.
      tags:
      - Cost And Usage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                TimePeriod:
                  $ref: '#/components/schemas/DateInterval'
                Dimension:
                  type: string
                  description: The name of the dimension (e.g., SERVICE, REGION, AZ, LINKED_ACCOUNT, USAGE_TYPE, OPERATION)
                SearchString:
                  type: string
                Context:
                  type: string
      responses:
        '200':
          description: Dimension values returned
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/DataUnavailableException'
components:
  responses:
    DataUnavailableException:
      description: The requested data is unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    LimitExceededException:
      description: You've exceeded the limit for this resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        Message:
          type: string
        Code:
          type: string
    DateInterval:
      type: object
      required:
      - Start
      - End
      properties:
        Start:
          type: string
          description: Start of the time period in YYYY-MM-DD format
          example: '2026-01-01'
        End:
          type: string
          description: End of the time period in YYYY-MM-DD format
          example: '2026-04-01'
    GetCostAndUsageRequest:
      type: object
      required:
      - TimePeriod
      - Granularity
      - Metrics
      properties:
        TimePeriod:
          $ref: '#/components/schemas/DateInterval'
        Granularity:
          type: string
          enum:
          - DAILY
          - MONTHLY
          - HOURLY
        Filter:
          $ref: '#/components/schemas/Expression'
        Metrics:
          type: array
          items:
            type: string
          description: 'Metrics to return. Options: AmortizedCost, BlendedCost, NormalizedUsageAmount, UnblendedCost, UsageQuantity, NetAmortizedCost, NetUnblendedCost'
        GroupBy:
          type: array
          items:
            $ref: '#/components/schemas/GroupDefinition'
        NextPageToken:
          type: string
    GetCostAndUsageResponse:
      type: object
      properties:
        ResultsByTime:
          type: array
          items:
            type: object
            properties:
              TimePeriod:
                $ref: '#/components/schemas/DateInterval'
              Total:
                type: object
              Groups:
                type: array
              Estimated:
                type: boolean
        DimensionValueAttributes:
          type: array
        NextPageToken:
          type: string
    Expression:
      type: object
      description: Filter expression to apply to cost and usage data. Can filter by dimensions, tags, or cost categories.
      properties:
        Dimensions:
          type: object
          properties:
            Key:
              type: string
            Values:
              type: array
              items:
                type: string
        Tags:
          type: object
          properties:
            Key:
              type: string
            Values:
              type: array
              items:
                type: string
        And:
          type: array
          items:
            type: object
        Or:
          type: array
          items:
            type: object
        Not:
          type: object
    GroupDefinition:
      type: object
      properties:
        Type:
          type: string
          enum:
          - DIMENSION
          - TAG
          - COST_CATEGORY
        Key:
          type: string
  securitySchemes:
    aws_iam:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 authentication
externalDocs:
  description: AWS Budgets API Reference
  url: https://docs.aws.amazon.com/budgets/latest/APIReference/