Vantage FinancialCommitmentReports API

openapi: 3.0.1
info:
  title: Vantage AccessGrants FinancialCommitmentReports 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: FinancialCommitmentReports
  description: Operations about FinancialCommitmentReports
paths:
  /financial_commitment_reports:
    get:
      tags:
      - FinancialCommitmentReports
      summary: Get all financial commitment reports
      description: Return all FinancialCommitmentReports.
      operationId: getFinancialCommitmentReports
      parameters:
      - name: page
        in: query
        description: The page of results to return.
        schema:
          type: integer
          format: int32
      - name: limit
        in: query
        description: The amount of results to return. The maximum is 1000.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialCommitmentReports'
              example:
                links:
                  self: https://api.vantage.sh/v2/financial_commitment_reports
                  first: https://api.vantage.sh/v2/financial_commitment_reports?page=1
                  next: null
                  last: https://api.vantage.sh/v2/financial_commitment_reports?page=1
                  prev: null
                financial_commitment_reports:
                - token: fncl_cmnt_rprt_28bc840bf137769c
                  title: All Financial Commitments
                  default: false
                  created_at: '2025-01-27T21:42:06Z'
                  workspace_token: wrkspc_f8d8bd5e493a734c
                  user_token: null
                  start_date: '2024-10-01'
                  end_date: '2025-01-25'
                  date_interval: last_3_months
                  date_bucket: month
                  groupings: cost_type
                  on_demand_costs_scope: discountable
                  filter: (financial_commitments.provider = 'aws')
      security:
      - oauth2:
        - read
    post:
      tags:
      - FinancialCommitmentReports
      summary: Create financial commitment report
      description: Create a FinancialCommitmentReport.
      operationId: createFinancialCommitmentReport
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createFinancialCommitmentReport'
        required: true
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialCommitmentReport'
              example:
                token: fncl_cmnt_rprt_d0f702a7d0ff20a4
                title: title
                default: false
                created_at: '2025-01-27T21:42:07Z'
                workspace_token: wrkspc_609f0ae3bffb9f37
                user_token: null
                start_date: '2024-10-01'
                end_date: '2025-01-25'
                date_interval: last_3_months
                date_bucket: month
                groupings: cost_type
                on_demand_costs_scope: discountable
                filter: financial_commitments.provider = 'aws'
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: UnprocessableEntity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - write
      x-codegen-request-body-name: createFinancialCommitmentReport
  /financial_commitment_reports/{financial_commitment_report_token}:
    get:
      tags:
      - FinancialCommitmentReports
      summary: Get financial commitment report by token
      description: Return a FinancialCommitmentReport.
      operationId: getFinancialCommitmentReport
      parameters:
      - name: financial_commitment_report_token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialCommitmentReport'
              example:
                token: fncl_cmnt_rprt_86a93126175f91ed
                title: All Financial Commitments
                default: false
                created_at: '2025-01-27T21:42:04Z'
                workspace_token: wrkspc_0e9408c2a0682914
                user_token: null
                start_date: '2024-10-01'
                end_date: '2025-01-25'
                date_interval: last_3_months
                date_bucket: month
                groupings: cost_type
                on_demand_costs_scope: discountable
                filter: (financial_commitments.provider = 'aws')
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - read
    put:
      tags:
      - FinancialCommitmentReports
      summary: Update financial commitment report
      description: Update a FinancialCommitmentReport.
      operationId: updateFinancialCommitmentReport
      parameters:
      - name: financial_commitment_report_token
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateFinancialCommitmentReport'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialCommitmentReport'
              example:
                token: fncl_cmnt_rprt_38f1d3fcee354f6a
                title: new title
                default: false
                created_at: '2025-01-27T21:42:06Z'
                workspace_token: wrkspc_358df7afe2a742fb
                user_token: null
                start_date: '2024-10-01'
                end_date: '2025-01-25'
                date_interval: last_3_months
                date_bucket: week
                groupings: cost_type,commitment_type
                on_demand_costs_scope: discountable
                filter: (financial_commitments.provider = 'aws')
        '400':
          description: BadRequest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '422':
          description: UnprocessableEntity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - write
      x-codegen-request-body-name: updateFinancialCommitmentReport
    delete:
      tags:
      - FinancialCommitmentReports
      summary: Delete financial commitment report
      description: Delete a FinancialCommitmentReport.
      operationId: deleteFinancialCommitmentReport
      parameters:
      - name: financial_commitment_report_token
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialCommitmentReport'
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      security:
      - oauth2:
        - write
components:
  schemas:
    Errors:
      required:
      - errors
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        errors:
          type: array
          nullable: false
          items:
            type: string
      description: Errors model
    updateFinancialCommitmentReport:
      type: object
      properties:
        title:
          type: string
          description: The title of the FinancialCommitmentReport.
        filter:
          type: string
          description: The filter query language to apply to the FinancialCommitmentReport. Additional documentation available at https://docs.vantage.sh/vql.
        start_date:
          type: string
          description: The start date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter.
          format: date
          example: '2024-03-01'
        end_date:
          type: string
          description: The end date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter.
          format: date
          example: '2024-03-01'
        date_interval:
          type: string
          description: The date interval of the FinancialCommitmentReport. Unless 'custom' is used, this is incompatible with 'start_date' and 'end_date' parameters. Defaults to 'last_3_months'.
          enum:
          - this_month
          - last_7_days
          - last_30_days
          - last_month
          - last_3_months
          - last_6_months
          - custom
          - last_12_months
          - last_24_months
          - last_36_months
          - year_to_date
          - last_3_days
          - last_14_days
        date_bucket:
          type: string
          description: The date bucket of the FinancialCommitmentReport.
          enum:
          - hour
          - day
          - week
          - month
          - quarter
        on_demand_costs_scope:
          type: string
          description: 'The scope for the costs. Possible values: discountable, all.'
          enum:
          - discountable
          - all
        groupings:
          type: array
          description: 'Grouping values for aggregating costs on the FinancialCommitmentReport. Valid groupings: cost_type, commitment_type, commitment_id, service, resource_account_id, provider_account_id, region, cost_category, cost_sub_category, instance_type, tag, tag:<label_name>.'
          items:
            type: string
      description: Update a FinancialCommitmentReport.
    createFinancialCommitmentReport:
      required:
      - title
      - workspace_token
      type: object
      properties:
        workspace_token:
          type: string
          description: The Workspace in which the FinancialCommitmentReport will be created.
        title:
          type: string
          description: The title of the FinancialCommitmentReport.
        filter:
          type: string
          description: The filter query language to apply to the FinancialCommitmentReport. Additional documentation available at https://docs.vantage.sh/vql.
        start_date:
          type: string
          description: The start date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter.
          format: date
          example: '2024-03-01'
        end_date:
          type: string
          description: The end date of the FinancialCommitmentReport. YYYY-MM-DD formatted. Incompatible with 'date_interval' parameter.
          format: date
          example: '2024-03-01'
        date_interval:
          type: string
          description: The date interval of the FinancialCommitmentReport. Unless 'custom' is used, this is incompatible with 'start_date' and 'end_date' parameters. Defaults to 'last_3_months'.
          enum:
          - this_month
          - last_7_days
          - last_30_days
          - last_month
          - last_3_months
          - last_6_months
          - custom
          - last_12_months
          - last_24_months
          - last_36_months
          - year_to_date
          - last_3_days
          - last_14_days
        date_bucket:
          type: string
          description: The date bucket of the FinancialCommitmentReport.
          enum:
          - hour
          - day
          - week
          - month
          - quarter
        on_demand_costs_scope:
          type: string
          description: 'The scope for the costs. Possible values: discountable, all.'
          enum:
          - discountable
          - all
        groupings:
          type: array
          description: 'Grouping values for aggregating costs on the FinancialCommitmentReport. Valid groupings: cost_type, commitment_type, commitment_id, service, resource_account_id, provider_account_id, region, cost_category, cost_sub_category, instance_type, tag, tag:<label_name>.'
          items:
            type: string
      description: Create a FinancialCommitmentReport.
    FinancialCommitmentReports:
      required:
      - financial_commitment_reports
      type: object
      properties:
        links:
          $ref: '#/components/schemas/Links'
        financial_commitment_reports:
          type: array
          items:
            $ref: '#/components/schemas/FinancialCommitmentReport'
      description: FinancialCommitmentReports model
    Links:
      type: object
      properties:
        self:
          type: string
          description: The URL of the current page of results.
          nullable: true
        first:
          type: string
          description: The URL of the first page of results.
          nullable: true
        next:
          type: string
          description: The URL of the next page of results, if one exists.
          nullable: true
        last:
          type: string
          description: The URL of the last page of results, if one exists.
          nullable: true
        prev:
          type: string
          description: The URL of the previous page of results, if one exists.
          nullable: true
    FinancialCommitmentReport:
      required:
      - created_at
      - date_bucket
      - date_interval
      - default
      - end_date
      - filter
      - groupings
      - on_demand_costs_scope
      - start_date
      - title
      - token
      - workspace_token
      type: object
      properties:
        token:
          type: string
          nullable: false
        title:
          type: string
          description: The title of the FinancialCommitmentReport.
          nullable: false
          example: Acme123 Financial Commitment Report
        default:
          type: boolean
          description: Indicates whether the FinancialCommitmentReport is the default report.
          nullable: false
        created_at:
          type: string
          description: The date and time, in UTC, the report was created. ISO 8601 Formatted.
          nullable: false
          example: '2024-03-19T00:00:00Z'
        workspace_token:
          type: string
          description: The token for the Workspace the FinancialCommitmentReport is a part of.
          nullable: false
        user_token:
          type: string
          description: The token for the User who created this FinancialCommitmentReport.
          nullable: true
        start_date:
          type: string
          description: The start date for the FinancialCommitmentReport. Only set for custom date ranges. ISO 8601 Formatted.
          nullable: true
          example: '2024-03-01'
        end_date:
          type: string
          description: The end date for the FinancialCommitmentReport. Only set for custom date ranges. ISO 8601 Formatted.
          nullable: true
          example: '2024-03-20'
        date_interval:
          type: string
          description: The date range for the FinancialCommitmentReport. Only present if a custom date range is not specified.
          nullable: true
          example: last_month
        date_bucket:
          type: string
          description: 'How costs are grouped and displayed in the FinancialCommitmentReport. Possible values: day, week, month.'
          nullable: false
          example: month
        groupings:
          type: string
          description: The grouping aggregations applied to the filtered data.
          nullable: true
          example: cost_type, tag:account
        on_demand_costs_scope:
          type: string
          description: 'The scope for the costs. Possible values: discountable, all.'
          nullable: false
          example: discountable
        filter:
          type: string
          description: The filter applied to the FinancialCommitmentReport. Additional documentation available at https://docs.vantage.sh/vql.
          nullable: true
      description: FinancialCommitmentReport 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'