Microsoft Azure Advisor Resource Recommendation Bases API

openapi: 3.2.0
info:
  title: Microsoft Azure Advisor Resource Recommendation Bases API
  version: '2026-10-01'
  x-typespec-generated:
  - emitter: '@azure-tools/typespec-autorest'
  description: 'Operations tagged ResourceRecommendationBases across 2 of this provider''s published API definitions: microsoft-azure-advisor-2026-10-01-openapi.json, microsoft-azure-advisor-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://management.azure.com
security:
- azure_auth:
  - user_impersonation
tags:
- name: ResourceRecommendationBases
paths:
  /{resourceUri}/providers/Microsoft.Advisor/recommendations/{recommendationId}:
    get:
      operationId: Recommendations_Get
      tags:
      - ResourceRecommendationBases
      description: Obtains details of a cached recommendation.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/parameters/ApiVersionParameter
      - $ref: '#/components/parameters/Azure.ResourceManager.ResourceUriParameter'
      - name: recommendationId
        in: path
        description: The recommendation ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceRecommendationBase'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArmErrorResponse'
      x-ms-examples:
        GetRecommendationDetailSubscriptionResourceUri:
          $ref: ./examples/GetRecommendationDetailSubscriptionResourceUri.json
      summary: Recommendations get
      x-summary-source: derived
    servers:
    - url: https://management.azure.com
  /subscriptions/{subscriptionId}/providers/Microsoft.Advisor/recommendations:
    get:
      operationId: Recommendations_List
      tags:
      - ResourceRecommendationBases
      description: Obtains cached recommendations for a subscription. The recommendations are generated or computed by invoking generateRecommendations.
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/parameters/SubscriptionIdParameter
      - name: $filter
        in: query
        description: 'The filter to apply to the recommendations.<br>Filter can be applied to properties [''ResourceId'', ''ResourceGroup'', ''RecommendationTypeGuid'', ''[Category](#category)'', ''SubCategory'', ''RetirementDate'', ''[RecommendationStatus](#recommendationStatus)''] with operators [''eq'', ''and'', ''or'', ''lt'', ''gt'', ''le'', ''ge'']<br>.

          <br>The filter can also be applied to property [''trackingIds''], which uses the collection syntax `trackingIds/any(t: t eq ''<trackingId>'')`.<br>

          <br>**Note:** `Control` is a legacy filter property and will be deprecated in the future. Please use `SubCategory` for filtering recommendation subcategory.<br>

          <br>**Note:** `RecommendationStatus` filter is available from API Version 2026-02-01-preview and onwards.<br>

          <br>**Note:** Each `trackingIds/any(...)` predicate matches a single tracking ID; supplying multiple values inside one predicate is not supported. To match several tracking IDs, combine predicates with `or`. `trackingIds` can also be combined with the other supported filter properties using `and`.<br>

          <br>**Note:** A tracking ID is an Azure Service Health tracking ID, for example ''VN1S-1V8''. It is not a GUID and is not the same value as `RecommendationTypeGuid`. A single tracking ID can map to more than one recommendation type, so a result set filtered by `trackingIds` is not guaranteed to contain a single `RecommendationTypeGuid`. `trackingIds` is a filter-only property and is not returned on the recommendation resource; use the recommendation metadata API to resolve a tracking ID to the recommendation types that carry it.<br>

          <br>Valid options for SubCategory:<br>[''BusinessContinuity'', ''DisasterRecovery'', ''HighAvailability'', ''MonitoringAndAlerting'', ''Other'', ''Personalized'', ''PrioritizedRecommendations'', ''Scalability'', ''ServiceUpgradeAndRetirement'', ''Validation'']<br>

          <br>Example:<br>- $filter=Category eq ''Cost'' and ResourceGroup eq ''MyResourceGroup''<br>-$filter=SubCategory eq ''ServiceUpgradeAndRetirement'' and RetirementDate ge ''2024-01-01'' and RetirementDate le ''2028-01-01''. Filter can be applied on trackingIds as well.<br>- $filter=trackingIds/any(t: t eq ''VN1S-1V8'')<br>- $filter=ResourceId eq ''/subscriptions/{subscriptionId}/resourceGroups/MyResourceGroup/providers/Microsoft.Storage/storageAccounts/mystorage'' and trackingIds/any(t: t eq ''VN1S-1V8'')<br>- $filter=trackingIds/any(t: t eq ''VN1S-1V8'') or trackingIds/any(t: t eq ''6TH2-BV8'')'
        required: false
        schema:
          type: string
      - name: $top
        in: query
        description: The number of recommendations per page if a paged version of this API is being used.
        required: false
        schema:
          type: integer
          format: int32
      - name: $skipToken
        in: query
        description: The page-continuation token to use with a paged version of this API.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceRecommendationBaseListResult'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArmErrorResponse'
      x-ms-examples:
        ListRecommendationsSubscriptionResourceUri:
          $ref: ./examples/ListRecommendationsSubscriptionResourceUri.json
      x-ms-pageable:
        nextLinkName: nextLink
      summary: Recommendations list
      x-summary-source: derived
    servers:
    - url: https://management.azure.com
  /subscriptions/{subscriptionId}/providers/Microsoft.Advisor/recommendations/{recommendationId}:
    patch:
      operationId: Recommendations_Update
      tags:
      - ResourceRecommendationBases
      description: Update the state of a Recommendation
      parameters:
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/parameters/ApiVersionParameter
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/parameters/SubscriptionIdParameter
      - name: recommendationId
        in: path
        description: The recommendation ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Azure operation completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceRecommendationBase'
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: ../../../../../../common-types/resource-management/v4/types.json#/definitions/ErrorResponse
      x-ms-examples:
        PatchRecommendationStateProperties:
          $ref: ./examples/PatchRecommendationStateProperties.json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecommendationPatchPayload'
        description: The resource properties to be updated.
        required: true
      summary: Recommendations update
      x-summary-source: derived
    servers:
    - url: https://management.azure.com
components:
  schemas:
    Impact:
      type: string
      description: The business impact of the recommendation.
      enum:
      - High
      - Medium
      - Low
      x-ms-enum:
        name: Impact
        modelAsString: true
        values:
        - name: High
          value: High
        - name: Medium
          value: Medium
        - name: Low
          value: Low
    RecommendationStatus:
      type: string
      description: The state of the Recommendation applicable from v2026-02-01-preview.
      enum:
      - New
      - Postponed
      - Dismissed
      - Completed
      x-ms-enum:
        name: RecommendationStatus
        modelAsString: true
        values:
        - name: New
          value: New
        - name: Postponed
          value: Postponed
        - name: Dismissed
          value: Dismissed
        - name: Completed
          value: Completed
    RecommendationPropertiesReview:
      type: object
      description: The Review that this Recommendation belongs to.
      properties:
        id:
          type: string
          description: The ARM Resource Id of the Review
        name:
          type: string
          description: The Name of the Review
    RecommendationDismissReason:
      type: string
      description: The reason for dismissing the Recommendation.
      enum:
      - ExcessiveCostInvestmentRequired
      - TooComplexOrImpracticalToImplement
      - AnAlternativeSolutionIsAlreadyInPlace
      - IncompatibleWithTheCurrentConfiguration
      - ImplementationStepsAreUnclear
      - RiskIsAcceptable
      - Other
      x-ms-enum:
        name: RecommendationDismissReason
        modelAsString: true
        values:
        - name: ExcessiveCostInvestmentRequired
          value: ExcessiveCostInvestmentRequired
        - name: TooComplexOrImpracticalToImplement
          value: TooComplexOrImpracticalToImplement
        - name: AnAlternativeSolutionIsAlreadyInPlace
          value: AnAlternativeSolutionIsAlreadyInPlace
        - name: IncompatibleWithTheCurrentConfiguration
          value: IncompatibleWithTheCurrentConfiguration
        - name: ImplementationStepsAreUnclear
          value: ImplementationStepsAreUnclear
        - name: RiskIsAcceptable
          value: RiskIsAcceptable
        - name: Other
          value: Other
    ResourceRecommendationBase:
      type: object
      description: Advisor Recommendation.
      properties:
        properties:
          $ref: '#/components/schemas/RecommendationProperties'
          description: The properties of the recommendation.
          x-ms-client-flatten: true
      allOf:
      - $ref: ../../../../../../common-types/resource-management/v4/types.json#/definitions/ProxyResource
    Control:
      type: string
      description: The sub-category of the recommendation.
      enum:
      - HighAvailability
      - BusinessContinuity
      - DisasterRecovery
      - Scalability
      - MonitoringAndAlerting
      - ServiceUpgradeAndRetirement
      - Other
      - PrioritizedRecommendations
      - Personalized
      x-ms-enum:
        name: Control
        modelAsString: true
        values:
        - name: HighAvailability
          value: HighAvailability
        - name: BusinessContinuity
          value: BusinessContinuity
        - name: DisasterRecovery
          value: DisasterRecovery
        - name: Scalability
          value: Scalability
        - name: MonitoringAndAlerting
          value: MonitoringAndAlerting
        - name: ServiceUpgradeAndRetirement
          value: ServiceUpgradeAndRetirement
        - name: Other
          value: Other
        - name: PrioritizedRecommendations
          value: PrioritizedRecommendations
        - name: Personalized
          value: Personalized
    ResourceMetadata:
      type: object
      description: Recommendation resource metadata
      properties:
        resourceId:
          type: string
          description: Azure resource Id of the assessed resource
        source:
          type: string
          description: Source from which recommendation is generated
        action:
          type: object
          description: The action to view resource.
          additionalProperties: {}
        singular:
          type: string
          description: 'The singular user friendly name of resource type. eg: virtual machine'
        plural:
          type: string
          description: 'The plural user friendly name of resource type. eg: virtual machines'
    ArmErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ARMErrorResponseBody'
          description: ARM error response body.
    RecommendationPropertiesResourceWorkload:
      type: object
      description: The Workload that this Resource belongs to.
      properties:
        id:
          type: string
          description: The Id of the Workload
        name:
          type: string
          description: The Name of the Workload
    ShortDescription:
      type: object
      description: A summary of the recommendation.
      properties:
        problem:
          type: string
          description: The issue or opportunity identified by the recommendation and proposed solution.
        solution:
          type: string
          description: The issue or opportunity identified by the recommendation and proposed solution.
    Risk:
      type: string
      description: The potential risk of not implementing the recommendation.
      enum:
      - Error
      - Warning
      - None
      x-ms-enum:
        name: Risk
        modelAsString: true
        values:
        - name: Error
          value: Error
        - name: Warning
          value: Warning
        - name: None
          value: None
    ResourceRecommendationBaseListResult:
      type: object
      description: The response of a ResourceRecommendationBase list operation.
      properties:
        value:
          type: array
          description: The ResourceRecommendationBase items on this page
          items:
            $ref: '#/components/schemas/ResourceRecommendationBase'
        nextLink:
          type: string
          format: uri
          description: The link to the next page of items
      required:
      - value
    RecommendationPatchPayload:
      type: object
      description: The recommendation patch payload.
      properties:
        properties:
          $ref: '#/components/schemas/RecommendationStatePropertiesPayload'
          description: The properties for recommendation patch payload.
    ARMErrorResponseBody:
      type: object
      description: ARM error response body.
      properties:
        message:
          type: string
          description: Gets or sets the string that describes the error in detail and provides debugging information.
        code:
          type: string
          description: Gets or sets the string that can be used to programmatically identify the error.
    Priority:
      type: string
      description: The Priority of the Recommendation.
      enum:
      - Critical
      - High
      - Medium
      - Low
      - Informational
      x-ms-enum:
        name: Priority
        modelAsString: true
        values:
        - name: Critical
          value: Critical
        - name: High
          value: High
        - name: Medium
          value: Medium
        - name: Low
          value: Low
        - name: Informational
          value: Informational
    Category:
      type: string
      description: The category of the recommendation.
      enum:
      - HighAvailability
      - Security
      - Performance
      - Cost
      - OperationalExcellence
      x-ms-enum:
        name: Category
        modelAsString: true
        values:
        - name: HighAvailability
          value: HighAvailability
        - name: Security
          value: Security
        - name: Performance
          value: Performance
        - name: Cost
          value: Cost
        - name: OperationalExcellence
          value: OperationalExcellence
    RecommendationStatePropertiesPayload:
      type: object
      description: Properties for recommendation state patch payload.
      properties:
        recommendationStatus:
          $ref: '#/components/schemas/RecommendationStatus'
          description: The state of the recommendation.
        recommendationDismissReason:
          $ref: '#/components/schemas/RecommendationDismissReason'
          description: The reason the state of the Recommendation was changed.
        postponedUntilDateTime:
          type: string
          format: date-time
          description: The time the Recommendation was postponed until.
    TrackedRecommendationProperties:
      type: object
      description: The tracked properties of a Recommendation
      properties:
        priority:
          $ref: '#/components/schemas/Priority'
          description: The Priority of the Recommendation.
    RecommendationProperties:
      type: object
      description: The properties of the recommendation.
      properties:
        category:
          $ref: '#/components/schemas/Category'
          description: The category of the recommendation.
        control:
          $ref: '#/components/schemas/Control'
          description: The sub-category of the recommendation.
        impact:
          $ref: '#/components/schemas/Impact'
          description: The business impact of the recommendation.
        impactedField:
          type: string
          description: The resource type identified by Advisor.
        impactedValue:
          type: string
          description: The resource identified by Advisor.
        recommendationStatus:
          $ref: '#/components/schemas/RecommendationStatus'
          description: The state of the Recommendation
        completionType:
          type: string
          description: The type of recommendation completion, which is either MarkedByUser or SystemVerified
        recommendationDismissReason:
          $ref: '#/components/schemas/RecommendationDismissReason'
          description: The reason the Recommendation was dismissed.
        postponedUntilDateTime:
          type: string
          format: date-time
          description: The time the Recommendation was postponed until.
        lastRefreshed:
          type: string
          format: date-time
          description: The most recent time Advisor evaluated the recommendation for validity (re-ingested).
        lastUpdated:
          type: string
          format: date-time
          description: The most recent time the recommendation state changed (manual or automated).
        createdTime:
          type: string
          format: date-time
          description: The created time of the recommendation.
        metadata:
          type: object
          description: The recommendation metadata.
          additionalProperties: {}
        recommendationTypeId:
          type: string
          description: The recommendation-type GUID.
        risk:
          $ref: '#/components/schemas/Risk'
          description: The potential risk of not implementing the recommendation.
        shortDescription:
          $ref: '#/components/schemas/ShortDescription'
          description: A summary of the recommendation.
        suppressionId:
          type: string
          description: The single snoozed or dismissed rule for the recommendation.
        extendedProperties:
          type: object
          description: Extended properties
          additionalProperties:
            type: string
        resourceMetadata:
          $ref: '#/components/schemas/ResourceMetadata'
          description: Metadata of resource that was assessed
        description:
          type: string
          description: The detailed description of recommendation.
        label:
          type: string
          description: The label of recommendation.
        learnMoreLink:
          type: string
          description: The link to learn more about recommendation and generation logic.
        potentialBenefits:
          type: string
          description: The potential benefit of implementing recommendation.
        actions:
          type: array
          description: The list of recommended actions to implement recommendation.
          items:
            type: object
            additionalProperties: {}
          x-ms-identifiers: []
        remediation:
          type: object
          description: The automated way to apply recommendation.
          additionalProperties: {}
        exposedMetadataProperties:
          type: object
          description: The recommendation metadata properties exposed to customer to provide additional information.
          additionalProperties: {}
        trackedProperties:
          $ref: '#/components/schemas/TrackedRecommendationProperties'
          description: The properties of a tracked recommendation.
        review:
          $ref: '#/components/schemas/RecommendationPropertiesReview'
          description: The Review that this Recommendation belongs to.
        resourceWorkload:
          $ref: '#/components/schemas/RecommendationPropertiesResourceWorkload'
          description: The Workload that this Resource belongs to.
        sourceSystem:
          type: string
          description: The Source System that this Recommendation originated from.
        notes:
          type: string
          description: Additional notes for the Recommendation
  parameters:
    Azure.ResourceManager.ResourceUriParameter:
      name: resourceUri
      in: path
      description: The fully qualified Azure Resource manager identifier of the resource.
      required: true
      x-ms-parameter-location: method
      x-ms-skip-url-encoding: true
      schema:
        type: string
  securitySchemes:
    azure_auth:
      type: oauth2
      flows:
        implicit:
          scopes:
            user_impersonation: impersonate your user account
          authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
      description: Azure Active Directory OAuth2 Flow.
x-refined-from:
- microsoft-azure-advisor-2026-10-01-openapi.json
- microsoft-azure-advisor-openapi.yml