Vantage Recommendations API

openapi: 3.2.0
info:
  title: Vantage Recommendations API
  description: The Vantage API provides programmatic access to the Vantage cloud cost management and FinOps platform.
  termsOfService: https://www.vantage.sh/terms-of-use
  contact:
    name: Vantage Support
    url: https://www.vantage.sh
    email: support@vantage.sh
  version: 2.0.0
servers:
- url: https://api.vantage.sh/v2
security:
- oauth2:
  - read
tags:
- name: Recommendations
  description: Operations about Recommendations
paths:
  /recommendations:
    get:
      tags:
      - Recommendations
      summary: Get all recommendations
      description: 'Return all Recommendations. Use the `type` query parameter with a fuzzy fragment to filter recommendation type case-insensitively (for example: aws, aws:ec2, aws:ec2:rightsizing).'
      operationId: getRecommendations
      parameters:
      - name: provider_ids
        in: query
        description: Filter by one or more providers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - aws
            - gcp
            - azure
            - kubernetes
            - datadog
      - name: billing_account_ids
        in: query
        description: Filter by billing account identifiers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: account_ids
        in: query
        description: Filter by account identifiers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: regions
        in: query
        description: Filter by region slugs (e.g. us-east-1, eastus, asia-east1). Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: tag_key
        in: query
        description: Filter by tag key (must be used with tag_value). Requires workspace_token.
        schema:
          type: string
      - name: tag_value
        in: query
        description: Filter by tag value (requires tag_key). Requires workspace_token.
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter recommendations created on/after this YYYY-MM-DD date. Requires workspace_token.
        schema:
          type: string
      - name: end_date
        in: query
        description: Filter recommendations created on/before this YYYY-MM-DD date. Requires workspace_token.
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status.
        schema:
          type: string
          enum:
          - active
          - archived
      - name: min_savings
        in: query
        description: Filter by recommendations whose potential savings are greater than or equal to this amount, in the workspace's currency. Requires workspace_token.
        schema:
          type: number
          format: float
      - name: page
        in: query
        description: The page of results to return.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The number of results to return. The maximum is 1000.
        schema:
          type: integer
          format: int32
      - name: workspace_token
        in: query
        description: Filter by workspace.
        schema:
          type: string
      - name: provider_account_id
        in: query
        description: Filter by provider account id (AWS account, Azure subscription id, etc).
        schema:
          type: string
      - name: category
        in: query
        description: Filter by exact recommendation category. Ignored when type is provided.
        schema:
          type: string
      - name: type
        in: query
        description: 'Fuzzy filter by recommendation type using a case-insensitive literal substring. Examples: aws, aws:ec2, aws:ec2:rightsizing.'
        schema:
          type: string
      - name: provider
        in: query
        description: Filter by provider.
        schema:
          type: string
          enum:
          - aws
          - gcp
          - azure
          - kubernetes
          - datadog
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recommendations'
              example:
                links:
                  self: https://api.vantage.sh/v2/recommendations
                  first: https://api.vantage.sh/v2/recommendations?page=1
                  next: null
                  last: https://api.vantage.sh/v2/recommendations?page=1
                  prev: null
                recommendations:
                - token: rcmmndtn_9bb8fa992d5b876b
                  type: null
                  category: ip_unattached
                  workspace_token: wrkspc_e0e58b3c1ddef29c
                  provider: aws
                  provider_account_id: '123456789012'
                  description: IP address is not attached to an instance.
                  documentation_url: https://handbook.vantage.sh/aws/services/ec2-other-pricing/#stranded-resources
                  potential_savings: '100.0'
                  service: AWS IP
                  created_at: '2026-01-28T16:53:32Z'
                  resources_affected_count: 0
                  currency_code: USD
                  currency_symbol: $
      security:
      - oauth2:
        - read
  /recommendations/{recommendation_token}:
    get:
      tags:
      - Recommendations
      summary: Get recommendation by token
      description: Return a Recommendation.
      operationId: getRecommendation
      parameters:
      - name: recommendation_token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recommendation'
              example:
                token: rcmmndtn_0eea161ff1a4d183
                type: null
                category: ip_unattached
                workspace_token: wrkspc_634a8ca67ed39555
                provider: aws
                provider_account_id: '123456789012'
                description: IP address is not attached to an instance.
                documentation_url: https://handbook.vantage.sh/aws/services/ec2-other-pricing/#stranded-resources
                potential_savings: '100.0'
                service: AWS IP
                created_at: '2026-01-28T16:53:23Z'
                resources_affected_count: 0
                currency_code: USD
                currency_symbol: $
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - read
  /recommendations/{recommendation_token}/resources:
    get:
      tags:
      - Recommendations
      summary: Get all resources for a recommendation
      description: Return all Active Resources, including Recommendation Actions, referenced in this Recommendation.
      operationId: getRecommendationResources
      parameters:
      - name: recommendation_token
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: The page of results to return.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The number of results to return. Defaults to 25. The maximum is 500.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationProviderResources'
              example:
                links:
                  self: https://api.vantage.sh/v2/recommendations/rcmmndtn_073dad68f8be41a2/resources
                  first: https://api.vantage.sh/v2/recommendations/rcmmndtn_073dad68f8be41a2/resources?page=1
                  next: null
                  last: https://api.vantage.sh/v2/recommendations/rcmmndtn_073dad68f8be41a2/resources?page=1
                  prev: null
                resources:
                - token: prvdr_rsrc_8ec00e4b4c410538
                  resource_id: i-12345
                  recommendation_actions:
                  - action: modify
                    description: 'Migrate to c5a.xlarge. Reasons: CPU over-provisioned, EBS IOPS over-provisioned, EBS throughput over-provisioned, Network bandwidth over-provisioned, and Network PPS over-provisioned.'
                    potential_savings: '100.0'
                    instance_type: c5a.xlarge
                    remediation_cli_command: 'aws ec2 modify-instance-attribute --instance-id i-12345 --instance-type ''{"Value": "c5a.xlarge"}'''
      security:
      - oauth2:
        - read
  /recommendations/{recommendation_token}/resources/{resource_token}:
    get:
      tags:
      - Recommendations
      summary: Get specific resource for a recommendation
      description: Return an Active Resource, including Recommendation Actions, referenced in this Recommendation.
      operationId: getRecommendationResource
      parameters:
      - name: recommendation_token
        in: path
        required: true
        schema:
          type: string
      - name: resource_token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationProviderResource'
              example:
                token: prvdr_rsrc_3065ac9b0999c363
                resource_id: i-12345
                recommendation_actions:
                - action: modify
                  description: 'Migrate to c5a.xlarge. Reasons: CPU over-provisioned, EBS IOPS over-provisioned, EBS throughput over-provisioned, Network bandwidth over-provisioned, and Network PPS over-provisioned.'
                  potential_savings: '100.0'
                  instance_type: c5a.xlarge
                  remediation_cli_command: 'aws ec2 modify-instance-attribute --instance-id i-12345 --instance-type ''{"Value": "c5a.xlarge"}'''
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - read
  /recommendations/by_type/{type}/resources:
    get:
      tags:
      - Recommendations
      summary: Get all resources for a recommendation type
      description: Return all Active Resources associated with recommendations of the specified type.
      operationId: getRecommendationTypeResources
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - name: provider_ids
        in: query
        description: Filter by one or more providers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
            enum:
            - aws
            - gcp
            - azure
            - kubernetes
            - datadog
      - name: billing_account_ids
        in: query
        description: Filter by billing account identifiers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: account_ids
        in: query
        description: Filter by account identifiers. Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: regions
        in: query
        description: Filter by region slugs (e.g. us-east-1, eastus, asia-east1). Requires workspace_token.
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - name: tag_key
        in: query
        description: Filter by tag key (must be used with tag_value). Requires workspace_token.
        schema:
          type: string
      - name: tag_value
        in: query
        description: Filter by tag value (requires tag_key). Requires workspace_token.
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter recommendations created on/after this YYYY-MM-DD date. Requires workspace_token.
        schema:
          type: string
      - name: end_date
        in: query
        description: Filter recommendations created on/before this YYYY-MM-DD date. Requires workspace_token.
        schema:
          type: string
      - name: status
        in: query
        description: Filter by status.
        schema:
          type: string
          enum:
          - active
          - archived
      - name: min_savings
        in: query
        description: Filter by recommendations whose potential savings are greater than or equal to this amount, in the workspace's currency. Requires workspace_token.
        schema:
          type: number
          format: float
      - name: page
        in: query
        description: The page of results to return.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The number of results to return. The maximum is 1000.
        schema:
          type: integer
          format: int32
      - name: workspace_token
        in: query
        description: The workspace token to filter recommendations by. Required.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecommendationProviderResources'
              example:
                resources:
                - token: pvdr_rsrc_abc123
                  resource_id: i-1234567890abcdef0
                  recommendation_actions:
                  - action: modify
                    instance_type: c5a.xlarge
                    description: Migrate to c5a.xlarge for cost savings.
                    potential_savings: '100.00'
                links:
                  first: /v2/recommendations/by_type/aws:ec2:co-rightsizing/resources?workspace_token=wrkspc_abc123&page=1
                  last: /v2/recommendations/by_type/aws:ec2:co-rightsizing/resources?workspace_token=wrkspc_abc123&page=1
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - read
components:
  schemas:
    RecommendationAction:
      required:
      - action
      - description
      - potential_savings
      type: object
      properties:
        action:
          type: string
        description:
          type: string
        potential_savings:
          type: string
          description: Potential savings in dollars
          example: '100.00'
        instance_type:
          type:
          - string
          - 'null'
        containers:
          type:
          - string
          - 'null'
        remediation_cli_command:
          type:
          - string
          - 'null'
          description: CLI command to remediate this recommendation
          example: aws ec2 stop-instances --instance-ids i-1234567890abcdef0
    Links:
      type: object
      properties:
        self:
          type:
          - string
          - 'null'
          description: The URL of the current page of results.
        first:
          type:
          - string
          - 'null'
          description: The URL of the first page of results.
        next:
          type:
          - string
          - 'null'
          description: The URL of the next page of results, if one exists.
        last:
          type:
          - string
          - 'null'
          description: The URL of the last page of results, if one exists.
        prev:
          type:
          - string
          - 'null'
          description: The URL of the previous page of results, if one exists.
    Errors:
      required:
      - errors
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        errors:
          type: array
          items:
            type: string
      description: Errors model
    RecommendationProviderResource:
      required:
      - account_id
      - billing_account_id
      - created_at
      - label
      - metadata
      - provider
      - region
      - resource_id
      - tags
      - token
      - type
      - uuid
      type: object
      properties:
        token:
          type: string
        uuid:
          type: string
          description: The unique identifier for the resource.
          example: i-0a1b2c3d4e5f6g7h8
        type:
          type: string
          description: The kind of resource.
          example: aws_instance
        label:
          type:
          - string
          - 'null'
        metadata:
          type:
          - object
          - 'null'
          properties: {}
          description: Type-specific attributes of the resource.
        account_id:
          type:
          - string
          - 'null'
          description: The provider account where the resource is located.
        billing_account_id:
          type:
          - string
          - 'null'
          description: The provider billing account this resource is charged to.
        provider:
          type: string
          description: The provider of the resource.
          example: aws
        region:
          type:
          - string
          - 'null'
          description: The region where the resource is located. Region values are specific to each provider.
          example: us-west-2
        costs:
          type: array
          description: The cost of the resource broken down by category.
          items:
            $ref: '#/components/schemas/ResourceCost'
        created_at:
          type: string
          description: The date and time when Vantage first observed the resource.
        tags:
          type: object
          properties: {}
          description: Key-value pairs of tags associated with the resource.
        resource_id:
          type: string
          description: The unique identifier of the Active Resource.
          example: i-0a1b2c3d4e5f6g7h8
        recommendation_actions:
          type: array
          description: The actions to take to implement the Recommendation.
          items:
            $ref: '#/components/schemas/RecommendationAction'
      description: RecommendationProviderResource model
    RecommendationProviderResources:
      required:
      - resources
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/RecommendationProviderResource'
      description: RecommendationProviderResources model
    Recommendation:
      required:
      - category
      - created_at
      - description
      - documentation_url
      - potential_savings
      - provider
      - provider_account_id
      - resources_affected_count
      - service
      - token
      - type
      - workspace_token
      type: object
      properties:
        token:
          type: string
        type:
          type: string
          description: The type of the Recommendation. This is analogous to category, but with a uniform format.
          example: aws:ec2:co-rightsizing
        category:
          type: string
          description: The category of the Recommendation.
          example: ec2_compute_optimizer_recommender
        workspace_token:
          type: string
          description: The token for the Workspace the Recommendation is a part of.
        provider:
          type: string
          description: The provider the Recommendation is for.
        provider_account_id:
          type:
          - string
          - 'null'
          description: The account ID of the provider. For Azure, this is the subscription ID.
        description:
          type: string
        documentation_url:
          type:
          - string
          - 'null'
          description: A URL to related documentation if available.
          example: https://handbook.vantage.sh/aws/services/s3-pricing/#intelligent-tiering
        potential_savings:
          type:
          - string
          - 'null'
          description: The monthly potential savings of the Recommendation, converted to the organization's selected currency.
          example: '100.00'
        service:
          type: string
          description: The service the Recommendation is for.
          example: Amazon EC2
        created_at:
          type: string
          description: The date and time, in UTC, the Recommendation was created. ISO 8601 Formatted.
        resources_affected_count:
          type: integer
          description: The number of ProviderResources related to the Recommendation. Use the `recommendations/:token/resources` endpoint to get the full list of resources.
          format: int32
        currency_code:
          type:
          - string
          - 'null'
          description: The currency code used by the Workspace to which this Recommendation belongs.
          example: EUR
        currency_symbol:
          type:
          - string
          - 'null'
          description: The currency symbol used by the Workspace to which this Recommendation belongs.
          example: EUR
      description: Recommendation model
    ResourceCost:
      required:
      - amount
      - category
      type: object
      properties:
        category:
          type: string
          description: The category of the cost.
        amount:
          type: number
          description: The cost amount.
          format: float
    Recommendations:
      required:
      - recommendations
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        recommendations:
          type: array
          items:
            $ref: '#/components/schemas/Recommendation'
      description: Recommendations model
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://console.vantage.sh/account/profile
          scopes:
            read: Grants read access
            write: Grants write access
x-original-swagger-version: '2.0'