AWS CloudWatch Metrics API

openapi: 3.1.0
info:
  title: AWS CloudWatch Amazon CloudWatch Alarms Metrics API
  description: Amazon CloudWatch monitors your Amazon Web Services (AWS) resources and the applications you run on AWS in real time. You can use CloudWatch to collect and track metrics, which are variables you can measure for your resources and applications. CloudWatch alarms watch metrics and automatically send notifications or make changes to the resources you are monitoring when a threshold is breached. CloudWatch dashboards provide a unified view of your AWS resources, custom applications, and services.
  version: '2010-08-01'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/cloudwatch/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://a0.awsstatic.com/libra-css/images/logos/aws_logo_smile_1200x630.png
servers:
- url: https://monitoring.{region}.amazonaws.com
  description: CloudWatch regional endpoint
  variables:
    region:
      default: us-east-1
      description: The AWS region
      enum:
      - us-east-1
      - us-east-2
      - us-west-1
      - us-west-2
      - eu-west-1
      - eu-west-2
      - eu-west-3
      - eu-central-1
      - eu-north-1
      - ap-east-1
      - ap-south-1
      - ap-southeast-1
      - ap-southeast-2
      - ap-northeast-1
      - ap-northeast-2
      - ap-northeast-3
      - sa-east-1
      - ca-central-1
      - me-south-1
      - af-south-1
security:
- aws_sigv4: []
tags:
- name: Metrics
  description: Operations for working with CloudWatch metrics and metric data
paths:
  /:
    post:
      operationId: PutMetricData
      summary: Aws Cloudwatch Publish Metric Data Points to Cloudwatch
      description: Publishes metric data points to Amazon CloudWatch. CloudWatch associates the data points with the specified metric. If the specified metric does not exist, CloudWatch creates the metric. When CloudWatch creates a metric, it can take up to fifteen minutes for the metric to appear in calls to ListMetrics. Each PutMetricData request is limited to 1 MB in size for HTTP POST requests and is limited to 40 KB for HTTP GET requests. The maximum number of metric datum items per PutMetricData request is 1,000.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_PutMetricData'
      - $ref: '#/components/parameters/Version'
      - $ref: '#/components/parameters/ContentType'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PutMetricDataInput'
            examples:
              PutmetricdataRequestExample:
                summary: Default PutMetricData request
                x-microcks-default: true
                value:
                  Namespace: example_value
                  MetricData:
                  - MetricName: example_value
                    Dimensions: {}
                    Timestamp: '2026-01-15T10:30:00Z'
                    Value: 42.5
                    Values: {}
                    Counts: {}
                    StorageResolution: 10
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad request
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Putmetricdata400Example:
                  summary: Default PutMetricData 400 response
                  x-microcks-default: true
                  value:
                    Error:
                      Type: example_value
                      Code: example_value
                      Message: example_value
                    RequestId: '500123'
        '500':
          description: Internal failure
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Putmetricdata500Example:
                  summary: Default PutMetricData 500 response
                  x-microcks-default: true
                  value:
                    Error:
                      Type: example_value
                      Code: example_value
                      Message: example_value
                    RequestId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#GetMetricData:
    post:
      operationId: GetMetricData
      summary: Aws Cloudwatch Retrieve Metric Data From Cloudwatch
      description: Retrieves CloudWatch metric values. You can use GetMetricData to retrieve as many as 500 different metrics in a single request, with a total of as many as 100,800 data points per request. You can also optionally perform metric math expressions on the values of the returned statistics. CloudWatch returns aggregated data points based on the statistical values requested.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_GetMetricData'
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GetMetricDataInput'
            examples:
              GetmetricdataRequestExample:
                summary: Default GetMetricData request
                x-microcks-default: true
                value:
                  MetricDataQueries:
                  - Id: abc123
                    Expression: example_value
                    Label: Example Title
                    ReturnData: true
                    Period: 10
                    AccountId: '500123'
                  StartTime: '2026-01-15T10:30:00Z'
                  EndTime: '2026-01-15T10:30:00Z'
                  NextToken: example_value
                  ScanBy: TimestampDescending
                  MaxDatapoints: 10
                  LabelOptions:
                    Timezone: example_value
      responses:
        '200':
          description: Successful response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetMetricDataOutput'
              examples:
                Getmetricdata200Example:
                  summary: Default GetMetricData 200 response
                  x-microcks-default: true
                  value:
                    MetricDataResults:
                    - Id: abc123
                      Label: Example Title
                      Timestamps: {}
                      Values: {}
                      StatusCode: Complete
                      Messages: {}
                    NextToken: example_value
                    Messages:
                    - Code: example_value
                      Value: example_value
        '400':
          description: Invalid parameter value or combination
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Getmetricdata400Example:
                  summary: Default GetMetricData 400 response
                  x-microcks-default: true
                  value:
                    Error:
                      Type: example_value
                      Code: example_value
                      Message: example_value
                    RequestId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#GetMetricStatistics:
    post:
      operationId: GetMetricStatistics
      summary: Aws Cloudwatch Retrieve Statistics for a Specified Metric
      description: Gets statistics for the specified metric. The maximum number of data points returned from a single call is 1,440. If you request more than 1,440 data points, CloudWatch returns an error. CloudWatch retains metric data as follows - data points with a period of less than 60 seconds are available for 3 hours, data points with a period of 60 seconds are available for 15 days, data points with a period of 300 seconds are available for 63 days, and data points with a period of 3600 seconds are available for 455 days.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_GetMetricStatistics'
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/GetMetricStatisticsInput'
            examples:
              GetmetricstatisticsRequestExample:
                summary: Default GetMetricStatistics request
                x-microcks-default: true
                value:
                  Namespace: example_value
                  MetricName: example_value
                  Dimensions:
                  - Name: Example Title
                    Value: example_value
                  StartTime: '2026-01-15T10:30:00Z'
                  EndTime: '2026-01-15T10:30:00Z'
                  Period: 10
                  Statistics:
                  - SampleCount
                  ExtendedStatistics:
                  - example_value
                  Unit: Seconds
      responses:
        '200':
          description: Successful response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/GetMetricStatisticsOutput'
              examples:
                Getmetricstatistics200Example:
                  summary: Default GetMetricStatistics 200 response
                  x-microcks-default: true
                  value:
                    Label: Example Title
                    Datapoints:
                    - Timestamp: '2026-01-15T10:30:00Z'
                      SampleCount: 42.5
                      Average: 42.5
                      Sum: 42.5
                      Minimum: 42.5
                      Maximum: 42.5
                      ExtendedStatistics: example_value
        '400':
          description: Bad request
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Getmetricstatistics400Example:
                  summary: Default GetMetricStatistics 400 response
                  x-microcks-default: true
                  value:
                    Error:
                      Type: example_value
                      Code: example_value
                      Message: example_value
                    RequestId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#ListMetrics:
    post:
      operationId: ListMetrics
      summary: Aws Cloudwatch List the Specified Metrics
      description: List the specified metrics. You can use the returned metrics with GetMetricData or GetMetricStatistics to get statistical data. Up to 500 results are returned for any one call. To retrieve additional results, use the returned token with subsequent calls. CloudWatch retains metric data for 15 months.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_ListMetrics'
      - $ref: '#/components/parameters/Version'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ListMetricsInput'
            examples:
              ListmetricsRequestExample:
                summary: Default ListMetrics request
                x-microcks-default: true
                value:
                  Namespace: example_value
                  MetricName: example_value
                  Dimensions:
                  - Name: Example Title
                    Value: example_value
                  NextToken: example_value
                  RecentlyActive: PT3H
                  IncludeLinkedAccounts: true
                  OwningAccount: example_value
      responses:
        '200':
          description: Successful response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListMetricsOutput'
              examples:
                Listmetrics200Example:
                  summary: Default ListMetrics 200 response
                  x-microcks-default: true
                  value:
                    Metrics:
                    - Namespace: example_value
                      MetricName: example_value
                      Dimensions: {}
                    NextToken: example_value
                    OwningAccounts:
                    - example_value
        '400':
          description: Bad request
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Listmetrics400Example:
                  summary: Default ListMetrics 400 response
                  x-microcks-default: true
                  value:
                    Error:
                      Type: example_value
                      Code: example_value
                      Message: example_value
                    RequestId: '500123'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#TagResource:
    post:
      operationId: TagResource
      summary: Aws Cloudwatch Assign Tags to a Cloudwatch Resource
      description: Assigns one or more tags (key-value pairs) to the specified CloudWatch resource. Currently, the only CloudWatch resources that can be tagged are alarms and Contributor Insights rules. Tags can help you organize and categorize your resources.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_TagResource'
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/TagResourceInput'
            examples:
              TagresourceRequestExample:
                summary: Default TagResource request
                x-microcks-default: true
                value:
                  ResourceARN: example_value
                  Tags:
                  - Key: example_value
                    Value: example_value
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#UntagResource:
    post:
      operationId: UntagResource
      summary: Aws Cloudwatch Remove Tags From a Cloudwatch Resource
      description: Removes one or more tags from the specified resource.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_UntagResource'
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UntagResourceInput'
            examples:
              UntagresourceRequestExample:
                summary: Default UntagResource request
                x-microcks-default: true
                value:
                  ResourceARN: example_value
                  TagKeys:
                  - example_value
      responses:
        '200':
          description: Successful response
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /#ListTagsForResource:
    post:
      operationId: ListTagsForResource
      summary: Aws Cloudwatch List Tags for a Cloudwatch Resource
      description: Displays the tags associated with a CloudWatch resource. Currently, alarms and Contributor Insights rules support tagging.
      tags:
      - Metrics
      parameters:
      - $ref: '#/components/parameters/Action_ListTagsForResource'
      - $ref: '#/components/parameters/Version'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ListTagsForResourceInput'
            examples:
              ListtagsforresourceRequestExample:
                summary: Default ListTagsForResource request
                x-microcks-default: true
                value:
                  ResourceARN: example_value
      responses:
        '200':
          description: Successful response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListTagsForResourceOutput'
              examples:
                Listtagsforresource200Example:
                  summary: Default ListTagsForResource 200 response
                  x-microcks-default: true
                  value:
                    Tags:
                    - Key: example_value
                      Value: example_value
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Statistic:
      type: string
      description: The statistic for the metric.
      enum:
      - SampleCount
      - Average
      - Sum
      - Minimum
      - Maximum
    UntagResourceInput:
      type: object
      required:
      - ResourceARN
      - TagKeys
      properties:
        ResourceARN:
          type: string
          minLength: 1
          maxLength: 1024
          description: The ARN of the CloudWatch resource that you're removing tags from.
          example: example_value
        TagKeys:
          type: array
          items:
            type: string
          description: The list of tag keys to remove from the resource.
          example: []
    Tag:
      type: object
      description: A key-value pair associated with a CloudWatch resource.
      required:
      - Key
      - Value
      properties:
        Key:
          type: string
          minLength: 1
          maxLength: 128
          description: A string that you can use to assign a value.
          example: example_value
        Value:
          type: string
          minLength: 0
          maxLength: 256
          description: The value for the specified tag key.
          example: example_value
    ListMetricsInput:
      type: object
      properties:
        Namespace:
          type: string
          minLength: 1
          maxLength: 255
          description: Filters the results to only those metrics in the specified namespace.
          example: example_value
        MetricName:
          type: string
          minLength: 1
          maxLength: 255
          description: Filters the results to only the specified metric name.
          example: example_value
        Dimensions:
          type: array
          items:
            $ref: '#/components/schemas/DimensionFilter'
          maxItems: 30
          description: Filters the results to only those metrics that match the specified dimensions.
          example: []
        NextToken:
          type: string
          description: The token returned by a previous call to indicate there is more data available.
          example: example_value
        RecentlyActive:
          type: string
          enum:
          - PT3H
          description: To filter the results to show only metrics that have had data points published in the past three hours, specify this parameter with a value of PT3H.
          example: PT3H
        IncludeLinkedAccounts:
          type: boolean
          description: If you are using this operation in a monitoring account, specify true to include metrics from source accounts in the returned data.
          example: true
        OwningAccount:
          type: string
          description: When you use this operation in a monitoring account, use this field to return metrics only from one source account.
          example: example_value
    MetricDataQuery:
      type: object
      description: This structure is used in both GetMetricData and PutMetricAlarm. The supported use of this structure is different for those two operations.
      required:
      - Id
      properties:
        Id:
          type: string
          minLength: 1
          maxLength: 255
          pattern: '[a-z][a-zA-Z0-9_]*'
          description: A short name used to tie this object to the results in the response.
          example: abc123
        MetricStat:
          $ref: '#/components/schemas/MetricStat'
        Expression:
          type: string
          minLength: 1
          maxLength: 2048
          description: This field can contain a Metrics Insights query, or a metric math expression.
          example: example_value
        Label:
          type: string
          description: A human-readable label for this metric or expression.
          example: Example Title
        ReturnData:
          type: boolean
          description: When used in GetMetricData, this option indicates whether to return the timestamps and raw data values of this metric.
          example: true
        Period:
          type: integer
          minimum: 1
          description: The granularity, in seconds, of the returned data points.
          example: 10
        AccountId:
          type: string
          minLength: 1
          maxLength: 255
          description: The ID of the account where the metrics are located.
          example: '500123'
    StatisticSet:
      type: object
      description: Represents a set of statistics that describes a specific metric.
      required:
      - SampleCount
      - Sum
      - Minimum
      - Maximum
      properties:
        SampleCount:
          type: number
          format: double
          description: The number of samples used for the statistic set.
          example: 42.5
        Sum:
          type: number
          format: double
          description: The sum of values for the sample set.
          example: 42.5
        Minimum:
          type: number
          format: double
          description: The minimum value of the sample set.
          example: 42.5
        Maximum:
          type: number
          format: double
          description: The maximum value of the sample set.
          example: 42.5
    ListTagsForResourceOutput:
      type: object
      properties:
        Tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: The list of tag keys and values associated with the resource you specified.
          example: []
    ListMetricsOutput:
      type: object
      properties:
        Metrics:
          type: array
          items:
            $ref: '#/components/schemas/Metric'
          description: The metrics that match your request.
          example: []
        NextToken:
          type: string
          description: The token that marks the start of the next batch of returned results.
          example: example_value
        OwningAccounts:
          type: array
          items:
            type: string
          description: If you are using this operation in a monitoring account, this array contains the account IDs of the source accounts.
          example: []
    StandardUnit:
      type: string
      description: The unit of the metric.
      enum:
      - Seconds
      - Microseconds
      - Milliseconds
      - Bytes
      - Kilobytes
      - Megabytes
      - Gigabytes
      - Terabytes
      - Bits
      - Kilobits
      - Megabits
      - Gigabits
      - Terabits
      - Percent
      - Count
      - Bytes/Second
      - Kilobytes/Second
      - Megabytes/Second
      - Gigabytes/Second
      - Terabytes/Second
      - Bits/Second
      - Kilobits/Second
      - Megabits/Second
      - Gigabits/Second
      - Terabits/Second
      - Count/Second
      - None
    MessageData:
      type: object
      description: A message returned by the GetMetricData API.
      properties:
        Code:
          type: string
          description: The error code or status code associated with the message.
          example: example_value
        Value:
          type: string
          description: The message text.
          example: example_value
    PutMetricDataInput:
      type: object
      required:
      - Namespace
      - MetricData
      properties:
        Namespace:
          type: string
          minLength: 1
          maxLength: 255
          pattern: '[^:].*'
          description: The namespace for the metric data. To avoid conflicts with AWS service namespaces, you should not specify a namespace that begins with AWS/.
          example: example_value
        MetricData:
          type: array
          items:
            $ref: '#/components/schemas/MetricDatum'
          description: The data for the metric. The array can include no more than 1000 metrics per call.
          example: []
    MetricStat:
      type: object
      description: This structure defines the metric to be returned, along with the statistics, period, and units.
      required:
      - Metric
      - Period
      - Stat
      properties:
        Metric:
          $ref: '#/components/schemas/Metric'
        Period:
          type: integer
          minimum: 1
          description: The granularity, in seconds, of the returned data points.
          example: 10
        Stat:
          type: string
          description: The statistic to return. It can include any CloudWatch statistic or extended statistic.
          example: example_value
        Unit:
          $ref: '#/components/schemas/StandardUnit'
    Datapoint:
      type: object
      description: Encapsulates the statistical data that CloudWatch computes from metric data.
      properties:
        Timestamp:
          type: string
          format: date-time
          description: The time stamp used for the data point.
          example: '2026-01-15T10:30:00Z'
        SampleCount:
          type: number
          format: double
          description: The number of metric values that contributed to the aggregate value of this data point.
          example: 42.5
        Average:
          type: number
          format: double
          description: The average of the metric values that correspond to the data point.
          example: 42.5
        Sum:
          type: number
          format: double
          description: The sum of the metric values for the data point.
          example: 42.5
        Minimum:
          type: number
          format: double
          description: The minimum metric value for the data point.
          example: 42.5
        Maximum:
          type: number
          format: double
          description: The maximum metric value for the data point.
          example: 42.5
        Unit:
          $ref: '#/components/schemas/StandardUnit'
        ExtendedStatistics:
          type: object
          additionalProperties:
            type: number
            format: double
          description: The percentile statistic for the data point.
          example: example_value
    ErrorResponse:
      type: object
      description: Standard error response from CloudWatch API.
      properties:
        Error:
          type: object
          properties:
            Type:
              type: string
              description: The error type (Sender or Receiver).
            Code:
              type: string
              description: The error code.
            Message:
              type: string
              description: A description of the error.
          example: example_value
        RequestId:
          type: string
          description: The unique request ID.
          example: '500123'
    GetMetricStatisticsInput:
      type: object
      required:
      - Namespace
      - MetricName
      - StartTime
      - EndTime
      - Period
      properties:
        Namespace:
          type: string
          minLength: 1
          maxLength: 255
          description: The namespace of the metric.
          example: example_value
        MetricName:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the metric.
          example: example_value
        Dimensions:
          type: array
          items:
            $ref: '#/components/schemas/Dimension'
          maxItems: 30
          description: The dimensions to filter the metric.
          example: []
        StartTime:
          type: string
          format: date-time
          description: The time stamp that determines the first data point to return.
          example: '2026-01-15T10:30:00Z'
        EndTime:
          type: string
          format: date-time
          description: The time stamp that determines the last data point to return.
          example: '2026-01-15T10:30:00Z'
        Period:
          type: integer
          minimum: 1
          description: The granularity, in seconds, of the returned data points.
          example: 10
        Statistics:
          type: array
          items:
            $ref: '#/components/schemas/Statistic'
          minItems: 1
          maxItems: 5
          description: The metric statistics.
          example: []
        ExtendedStatistics:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 10
          description: The percentile statistics.
          example: []
        Unit:
          $ref: '#/components/schemas/StandardUnit'
    GetMetricStatisticsOutput:
      type: object
      properties:
        Label:
          type: string
          description: A label for the specified metric.
          example: Example Title
        Datapoints:
          type: array
          items:
            $ref: '#/components/schemas/Datapoint'
          description: The data points for the specified metric.
          example: []
    ListTagsForResourceInput:
      type: object
      required:
      - ResourceARN
      properties:
        ResourceARN:
          type: string
          minLength: 1
          maxLength: 1024
          description: The ARN of the CloudWatch resource that you want to view tags for.
          example: example_value
    DimensionFilter:
      type: object
      description: Represents filters for a dimension.
      required:
      - Name
      properties:
        Name:
          type: string
          minLength: 1
          maxLength: 255
          description: The dimension name to be matched.
          example: Example Title
        Value:
          type: string
          minLength: 1
          maxLength: 1024
          description: The value of the dimension to be matched.
          example: example_value
    GetMetricDataInput:
      type: object
      required:
      - MetricDataQueries
      - StartTime
      - EndTime
      properties:
        MetricDataQueries:
          type: array
          items:
            $ref: '#/components/schemas/MetricDataQuery'
          description: The metric queries to be returned. A single GetMetricData call can include as many as 500 MetricDataQuery structures.
          example: []
        StartTime:
          type: string
          format: date-time
          description: The time stamp indicating the earliest data to be returned.
          example: '2026-01-15T10:30:00Z'
        EndTime:
          type: string
          format: date-time
          description: The time stamp indicating the latest data to be returned.
          example: '2026-01-15T10:30:00Z'
        NextToken:
          type: string
          description: Include this value if it was returned by the previous GetMetricData operation.
          example: example_value
        ScanBy:
          type: string
          enum:
          - TimestampDescending
          - TimestampAscending
          description: The order in which data points should be returned.
          example: TimestampDescending
        MaxDatapoints:
          type: integer
          description: The maximum number of data points the request should return before paginating.
          example: 10
        LabelOptions:
          type: object
          properties:
            Timezone:
              type: string
              description: The time zone to use for metric data return.
          example: example_value
    Metric:
      type: object
      description: Represents a specific metric.
      properties:
        Namespace:
          type: string
          minLength: 1
          maxLength: 255
          pattern: '[^:].*'
          description: The namespace of the metric.
          example: example_value
        MetricName:
          type: string
          minLength: 1
          maxLength: 255
          description: The name of the metric.
          example: example_value
        Dimension

# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cloudwatch/refs/heads/main/openapi/cloudwatch-metrics-api-openapi.yml