openapi: 3.1.0
info:
  title: Azure Monitor Metric Definitions API
  description: >-
    Retrieves the list of available metric definitions for a given Azure
    resource, including metric names, units, aggregation types, and dimensions.
  version: '2023-10-01'
  contact:
    name: Microsoft Azure Support
    url: https://azure.microsoft.com/en-us/support/options/
  license:
    name: Microsoft API License
    url: https://azure.microsoft.com/en-us/support/legal/
servers:
  - url: https://management.azure.com
    description: Azure Resource Manager
security:
  - oauth2:
      - https://management.azure.com/.default
tags:
  - name: Metric Definitions
    description: Operations for listing metric definitions
paths:
  /subscriptions/{subscriptionId}/providers/Microsoft.Insights/metricDefinitions:
    get:
      operationId: MetricDefinitions_ListAtSubscriptionScope
      summary: Azure Monitor List metric definitions at subscription scope
      description: >-
        Lists the metric definitions for the subscription. Returns the available
        metric definitions that can be queried at the subscription level.
      tags:
        - Metric Definitions
      parameters:
        - $ref: '#/components/parameters/SubscriptionIdParameter'
        - $ref: '#/components/parameters/ApiVersionParameter'
        - $ref: '#/components/parameters/RegionParameter'
        - $ref: '#/components/parameters/MetricNamespaceParameter'
      responses:
        '200':
          description: Successful request to get the list of metric definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricDefinitionCollection'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /{resourceUri}/providers/Microsoft.Insights/metricDefinitions:
    get:
      operationId: MetricDefinitions_List
      summary: Azure Monitor List metric definitions for a resource
      description: >-
        Lists the metric definitions for the resource. Returns the available
        metric definitions and their properties for the specified resource.
      tags:
        - Metric Definitions
      parameters:
        - $ref: '#/components/parameters/ResourceUriParameter'
        - $ref: '#/components/parameters/ApiVersionParameter'
        - $ref: '#/components/parameters/MetricNamespaceParameter'
      responses:
        '200':
          description: Successful request to get the list of metric definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricDefinitionCollection'
        default:
          description: Error response describing why the operation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
          scopes:
            https://management.azure.com/.default: Access Azure Management API
  parameters:
    SubscriptionIdParameter:
      name: subscriptionId
      in: path
      required: true
      description: The ID of the target subscription.
      schema:
        type: string
    ResourceUriParameter:
      name: resourceUri
      in: path
      required: true
      description: The identifier of the resource.
      schema:
        type: string
    ApiVersionParameter:
      name: api-version
      in: query
      required: true
      description: Client API version.
      schema:
        type: string
        default: '2023-10-01'
    RegionParameter:
      name: region
      in: query
      required: false
      description: The region where the metrics you want reside.
      schema:
        type: string
    MetricNamespaceParameter:
      name: metricNamespace
      in: query
      required: false
      description: Metric namespace to query metric definitions for.
      schema:
        type: string
  schemas:
    MetricDefinitionCollection:
      type: object
      required:
        - value
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/MetricDefinition'
          description: The values for the metric definitions.
    MetricDefinition:
      type: object
      properties:
        isDimensionRequired:
          type: boolean
          description: Flag to indicate whether the dimension is required.
        resourceId:
          type: string
          description: The resource identifier of the resource that emitted the metric.
        namespace:
          type: string
          description: The namespace the metric belongs to.
        name:
          $ref: '#/components/schemas/LocalizableString'
        displayDescription:
          type: string
          description: Detailed description of this metric.
        category:
          type: string
          description: Custom category name for this metric.
        metricClass:
          type: string
          enum:
            - Availability
            - Transactions
            - Errors
            - Latency
            - Saturation
          description: The class of the metric.
        unit:
          type: string
          enum:
            - Count
            - Bytes
            - Seconds
            - CountPerSecond
            - BytesPerSecond
            - Percent
            - MilliSeconds
            - ByteSeconds
            - Unspecified
            - Cores
            - MilliCores
            - NanoCores
            - BitsPerSecond
          description: The unit of the metric.
        primaryAggregationType:
          type: string
          enum:
            - None
            - Average
            - Count
            - Minimum
            - Maximum
            - Total
          description: The primary aggregation type value defining how to use the values.
        supportedAggregationTypes:
          type: array
          items:
            type: string
            enum:
              - None
              - Average
              - Count
              - Minimum
              - Maximum
              - Total
          description: The collection of what aggregation types are supported.
        metricAvailabilities:
          type: array
          items:
            $ref: '#/components/schemas/MetricAvailability'
          description: The collection of what aggregation intervals are available.
        id:
          type: string
          description: The resource identifier of the metric definition.
        dimensions:
          type: array
          items:
            $ref: '#/components/schemas/LocalizableString'
          description: >-
            The name and the display name of the dimension, i.e. the
            localized string representation.
    MetricAvailability:
      type: object
      properties:
        timeGrain:
          type: string
          description: The time grain specifies the aggregation interval in ISO 8601 duration format.
        retention:
          type: string
          description: The retention period for the metric in ISO 8601 duration format.
    LocalizableString:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          description: The invariant value.
        localizedValue:
          type: string
          description: The display name.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Error message indicating why the operation failed.