Vantage Recommendations API

openapi: 3.2.0
info:
  title: Vantage AccessGrants Recommendations API
  description: The Vantage API provides programmatic access to the Vantage cloud cost management and FinOps platform. It covers cost reporting and querying (Costs, Cost Reports, forecasts, unit costs), cost visibility and optimization (Resources, Recommendations, Financial Commitments, Kubernetes efficiency), governance and alerting (Budgets, Budget Alerts, Cost Alerts, Anomaly Alerts and Notifications), organization (Segments, Folders, Saved Filters, Dashboards, Workspaces, Teams), and billing (Billing Profiles, Billing Rules, Invoices). The API spans AWS, Azure, GCP, Kubernetes, Datadog, Snowflake, MongoDB, and other supported providers. Base URL https://api.vantage.sh/v2. Authentication is via OAuth2 (client credentials / bearer token) with read and write scopes.
  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
    Errors:
      required:
      - errors
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        errors:
          type: array
          items:
            type: string
      description: Errors model
    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.
    RecommendationProviderResources:
      required:
      - resources
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/RecommendationProviderResource'
      description: RecommendationProviderResources 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
    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
    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
  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'