Update GetBudget API spec with cost query parameters and custom forecast fields

.generator/schemas/v2/openapi.yaml

@@ -12570,6 +12570,20 @@ components:
     BudgetAttributes:
       description: The attributes of a budget.
       properties:
+        costs:
+          $ref: "#/components/schemas/BudgetAttributesCosts"
+          description: Aggregated cost data for the budget. Present only when `actual=true` or `forecast=true` is requested.
+        costs_period_end:
+          description: The end of the period used to compute cost data, in milliseconds since epoch.
+          format: int64
+          type: integer
+        costs_period_start:
+          description: The start of the period used to compute cost data, in milliseconds since epoch.
+          format: int64
+          type: integer
+        costs_unit:
+          $ref: "#/components/schemas/BudgetAttributesCostsUnit"
+          description: The unit used for all cost values in the response.
         created_at:
           description: The timestamp when the budget was created.
           example: 1738258683590
@@ -12622,6 +12636,53 @@ components:
           example: 00000000-0a0a-0a0a-aaa0-00000000000a
           type: string
       type: object
+    BudgetAttributesCosts:
+      description: Aggregated cost data for the budget over the requested period.
+      properties:
+        actual:
+          description: The total actual cost. Present only when `actual=true` is requested.
+          format: double
+          nullable: true
+          type: number
+        amount:
+          description: The total budgeted amount over the requested period.
+          format: double
+          nullable: true
+          type: number
+        forecast:
+          description: The total forecast cost, with any custom forecast overrides applied. Present only when `forecast=true` is requested.
+          format: double
+          nullable: true
+          type: number
+        ootb_forecast:
+          description: The out-of-the-box ML forecast before custom overrides. Present only when `forecast=true` is requested.
+          format: double
+          nullable: true
+          type: number
+      type: object
+    BudgetAttributesCostsUnit:
+      description: The unit used for all cost values in the response.
+      properties:
+        family:
+          description: The unit family (for example, `currency`).
+          type: string
+        id:
+          description: The unique identifier for the unit.
+          type: string
+        name:
+          description: The full name of the unit.
+          type: string
+        plural:
+          description: The plural form of the unit name.
+          type: string
+        scale_factor:
+          description: The scale factor applied to raw cost values.
+          format: double
+          type: number
+        short_name:
+          description: The abbreviated unit name.
+          type: string
+      type: object
     BudgetValidationRequest:
       description: The request object for validating a budget configuration before creating or updating it.
       example:
@@ -12787,6 +12848,9 @@ components:
           description: The budgeted amount for this entry.
           format: double
           type: number
+        costs:
+          $ref: "#/components/schemas/BudgetWithEntriesDataAttributesEntriesItemsCosts"
+          description: Cost data for this entry. Present only when `actual=true` or `forecast=true` is requested.
         month:
           description: The month this budget entry applies to, in YYYYMM format.
           format: int64
@@ -12797,6 +12861,36 @@ components:
             $ref: "#/components/schemas/BudgetWithEntriesDataAttributesEntriesItemsTagFiltersItems"
           type: array
       type: object
+    BudgetWithEntriesDataAttributesEntriesItemsCosts:
+      description: Cost data for a single budget entry.
+      properties:
+        actual:
+          description: The actual cost for this entry. Present only when `actual=true` is requested.
+          format: double
+          nullable: true
+          type: number
+        amount:
+          description: The budgeted amount for this entry.
+          format: double
+          nullable: true
+          type: number
+        custom_forecast:
+          description: |-
+            The custom forecast override for this entry. `null` when `forecast=true` is requested but no custom forecast has been set for this entry's month. A numeric value, including `0`, indicates an explicit custom forecast override. Omitted when `forecast=false` or the feature is not available for the organization.
+          format: double
+          nullable: true
+          type: number
+        forecast:
+          description: The final forecast for this entry, with any custom forecast override applied. Present only when `forecast=true` is requested.
+          format: double
+          nullable: true
+          type: number
+        ootb_forecast:
+          description: The out-of-the-box ML forecast for this entry, before custom overrides. Present only when `forecast=true` is requested.
+          format: double
+          nullable: true
+          type: number
+      type: object
     BudgetWithEntriesDataAttributesEntriesItemsTagFiltersItems:
       description: A tag filter used to scope a budget entry to specific resource tags.
       properties:
@@ -116220,10 +116314,36 @@ paths:
       tags:
         - Cloud Cost Management
     get:
-      description: Get a budget
+      description: Get a budget by ID. Pass `actual=true` or `forecast=true` to include cost data in the response. Use `start` and `end` (millisecond epochs, both required) to set the cost window. When `forecast=true`, each entry also includes `ootb_forecast` (the ML forecast before overrides) and `custom_forecast` (`null` if no override is set, a number if one is).
       operationId: GetBudget
       parameters:
         - $ref: "#/components/parameters/BudgetID"
+        - description: When `true`, includes actual cost data in the response.
+          in: query
+          name: actual
+          required: false
+          schema:
+            type: boolean
+        - description: When `true`, includes forecast cost data in the response, including `ootb_forecast` and `custom_forecast` per entry.
+          in: query
+          name: forecast
+          required: false
+          schema:
+            type: boolean
+        - description: Start of the cost window in milliseconds since epoch. Must be used together with `end`.
+          in: query
+          name: start
+          required: false
+          schema:
+            format: int64
+            type: integer
+        - description: End of the cost window in milliseconds since epoch. Must be used together with `start`.
+          in: query
+          name: end
+          required: false
+          schema:
+            format: int64
+            type: integer
       responses:
         "200":
           content:
@@ -116233,11 +116353,31 @@ paths:
                   value:
                     data:
                       attributes:
+                        costs:
+                          actual: 850.25
+                          amount: 1000.0
+                          forecast: 1100.5
+                          ootb_forecast: 1100.5
+                        costs_period_end: 1740873600000
+                        costs_period_start: 1738281600000
+                        costs_unit:
+                          family: currency
+                          id: "1"
+                          name: dollar
+                          plural: dollars
+                          scale_factor: 1.0
+                          short_name: $
                         created_at: 1738258683590
                         created_by: 00000000-0a0a-0a0a-aaa0-00000000000a
                         end_month: 202502
                         entries:
                           - amount: 500
+                            costs:
+                              actual: 425.5
+                              amount: 500.0
+                              custom_forecast:
+                              forecast: 550.25
+                              ootb_forecast: 550.25
                             month: 202501
                             tag_filters:
                               - tag_key: service
@@ -116254,6 +116394,10 @@ paths:
               schema:
                 $ref: "#/components/schemas/BudgetWithEntries"
           description: OK
+        "400":
+          $ref: "#/components/responses/BadRequestResponse"
+        "404":
+          $ref: "#/components/responses/NotFoundResponse"
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
       security:

examples/v2/cloud-cost-management/UpsertBudget.rb

@@ -6,11 +6,25 @@
 body = DatadogAPIClient::V2::BudgetWithEntries.new({
   data: DatadogAPIClient::V2::BudgetWithEntriesData.new({
     attributes: DatadogAPIClient::V2::BudgetAttributes.new({
+      costs: DatadogAPIClient::V2::BudgetAttributesCosts.new({
+        actual: nil,
+        amount: nil,
+        forecast: nil,
+        ootb_forecast: nil,
+      }),
+      costs_unit: DatadogAPIClient::V2::BudgetAttributesCostsUnit.new({}),
       created_at: 1738258683590,
       created_by: "00000000-0a0a-0a0a-aaa0-00000000000a",
       end_month: 202502,
       entries: [
         DatadogAPIClient::V2::BudgetWithEntriesDataAttributesEntriesItems.new({
+          costs: DatadogAPIClient::V2::BudgetWithEntriesDataAttributesEntriesItemsCosts.new({
+            actual: nil,
+            amount: nil,
+            custom_forecast: nil,
+            forecast: nil,
+            ootb_forecast: nil,
+          }),
           tag_filters: [
             DatadogAPIClient::V2::BudgetWithEntriesDataAttributesEntriesItemsTagFiltersItems.new({}),
           ],

features/scenarios_model_mapping.rb

@@ -2600,6 +2600,10 @@
     },
     "v2.GetBudget" => {
             "budget_id" => "String",
+            "actual" => "Boolean",
+            "forecast" => "Boolean",
+            "start" => "Integer",
+            "_end" => "Integer",
     },
     "v2.GetCommitmentsCommitmentList" => {
             "provider" => "CommitmentsProvider",

features/v2/cloud_cost_management.feature

@@ -70,21 +70,21 @@ Feature: Cloud Cost Management
   @generated @skip @team:DataDog/cloud-cost-management
   Scenario: Create or update a budget returns "Bad Request" response
     Given new "UpsertBudget" request
-    And body with value {"data": {"attributes": {"created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
+    And body with value {"data": {"attributes": {"costs": {"actual": null, "amount": null, "forecast": null, "ootb_forecast": null}, "costs_unit": {}, "created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"costs": {"actual": null, "amount": null, "custom_forecast": null, "forecast": null, "ootb_forecast": null}, "tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
     When the request is sent
     Then the response status is 400 Bad Request
 
   @generated @skip @team:DataDog/cloud-cost-management
   Scenario: Create or update a budget returns "Not Found" response
     Given new "UpsertBudget" request
-    And body with value {"data": {"attributes": {"created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
+    And body with value {"data": {"attributes": {"costs": {"actual": null, "amount": null, "forecast": null, "ootb_forecast": null}, "costs_unit": {}, "created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"costs": {"actual": null, "amount": null, "custom_forecast": null, "forecast": null, "ootb_forecast": null}, "tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
     When the request is sent
     Then the response status is 404 Not Found
 
   @generated @skip @team:DataDog/cloud-cost-management
   Scenario: Create or update a budget returns "OK" response
     Given new "UpsertBudget" request
-    And body with value {"data": {"attributes": {"created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
+    And body with value {"data": {"attributes": {"costs": {"actual": null, "amount": null, "forecast": null, "ootb_forecast": null}, "costs_unit": {}, "created_at": 1738258683590, "created_by": "00000000-0a0a-0a0a-aaa0-00000000000a", "end_month": 202502, "entries": [{"costs": {"actual": null, "amount": null, "custom_forecast": null, "forecast": null, "ootb_forecast": null}, "tag_filters": [{}]}], "metrics_query": "aws.cost.amortized{service:ec2} by {service}", "name": "my budget", "org_id": 123, "start_month": 202501, "total_amount": 1000, "updated_at": 1738258683590, "updated_by": "00000000-0a0a-0a0a-aaa0-00000000000a"}, "id": "00000000-0a0a-0a0a-aaa0-00000000000a", "type": ""}}
     When the request is sent
     Then the response status is 200 OK
 
@@ -336,6 +336,20 @@ Feature: Cloud Cost Management
     And the response "data.type" is equal to "ruleset"
     And the response "data.attributes.name" is equal to "EVP Cost Tags"
 
+  @generated @skip @team:DataDog/cloud-cost-management
+  Scenario: Get budget returns "Bad Request" response
+    Given new "GetBudget" request
+    And request contains "budget_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 400 Bad Request
+
+  @generated @skip @team:DataDog/cloud-cost-management
+  Scenario: Get budget returns "Not Found" response
+    Given new "GetBudget" request
+    And request contains "budget_id" parameter from "REPLACE.ME"
+    When the request is sent
+    Then the response status is 404 Not Found
+
   @generated @skip @team:DataDog/cloud-cost-management
   Scenario: Get budget returns "OK" response
     Given new "GetBudget" request

lib/datadog_api_client/inflector.rb

@@ -1757,6 +1757,8 @@ def overrides
           "v2.budget" => "Budget",
           "v2.budget_array" => "BudgetArray",
           "v2.budget_attributes" => "BudgetAttributes",
+          "v2.budget_attributes_costs" => "BudgetAttributesCosts",
+          "v2.budget_attributes_costs_unit" => "BudgetAttributesCostsUnit",
           "v2.budget_validation_request" => "BudgetValidationRequest",
           "v2.budget_validation_request_data" => "BudgetValidationRequestData",
           "v2.budget_validation_response" => "BudgetValidationResponse",
@@ -1767,6 +1769,7 @@ def overrides
           "v2.budget_with_entries_data" => "BudgetWithEntriesData",
           "v2.budget_with_entries_data_attributes" => "BudgetWithEntriesDataAttributes",
           "v2.budget_with_entries_data_attributes_entries_items" => "BudgetWithEntriesDataAttributesEntriesItems",
+          "v2.budget_with_entries_data_attributes_entries_items_costs" => "BudgetWithEntriesDataAttributesEntriesItemsCosts",
           "v2.budget_with_entries_data_attributes_entries_items_tag_filters_items" => "BudgetWithEntriesDataAttributesEntriesItemsTagFiltersItems",
           "v2.budget_with_entries_data_type" => "BudgetWithEntriesDataType",
           "v2.bulk_delete_apps_datastore_items_request" => "BulkDeleteAppsDatastoreItemsRequest",

lib/datadog_api_client/v2/api/cloud_cost_management_api.rb

@@ -967,10 +967,14 @@ def get_budget(budget_id, opts = {})
 
     # Get budget.
     #
-    # Get a budget
+    # Get a budget by ID. Pass `actual=true` or `forecast=true` to include cost data in the response. Use `start` and `end` (millisecond epochs, both required) to set the cost window. When `forecast=true`, each entry also includes `ootb_forecast` (the ML forecast before overrides) and `custom_forecast` (`null` if no override is set, a number if one is).
     #
     # @param budget_id [String] Budget id.
     # @param opts [Hash] the optional parameters
+    # @option opts [Boolean] :actual When `true`, includes actual cost data in the response.
+    # @option opts [Boolean] :forecast When `true`, includes forecast cost data in the response, including `ootb_forecast` and `custom_forecast` per entry.
+    # @option opts [Integer] :start Start of the cost window in milliseconds since epoch. Must be used together with `end`.
+    # @option opts [Integer] :_end End of the cost window in milliseconds since epoch. Must be used together with `start`.
     # @return [Array<(BudgetWithEntries, Integer, Hash)>] BudgetWithEntries data, response status code and response headers
     def get_budget_with_http_info(budget_id, opts = {})
 
@@ -986,6 +990,10 @@ def get_budget_with_http_info(budget_id, opts = {})
 
       # query parameters
       query_params = opts[:query_params] || {}
+      query_params[:'actual'] = opts[:'actual'] if !opts[:'actual'].nil?
+      query_params[:'forecast'] = opts[:'forecast'] if !opts[:'forecast'].nil?
+      query_params[:'start'] = opts[:'start'] if !opts[:'start'].nil?
+      query_params[:'end'] = opts[:'_end'] if !opts[:'_end'].nil?
 
       # header parameters
       header_params = opts[:header_params] || {}