Cloud Cost Recommendations Search API (#3528)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -17847,6 +17847,76 @@ components:
       required:
         - data
       type: object
+    CostRecommendationArray:
+      description: A page of cost recommendations with pagination metadata.
+      properties:
+        data:
+          description: The list of cost recommendations on this page.
+          items:
+            $ref: "#/components/schemas/CostRecommendationData"
+          type: array
+        meta:
+          $ref: "#/components/schemas/RecommendationsPageMeta"
+      required:
+        - data
+      type: object
+    CostRecommendationData:
+      description: A single cost recommendation entry in JSON:API form.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/CostRecommendationDataAttributes"
+        id:
+          description: Unique identifier for the recommendation.
+          type: string
+        type:
+          $ref: "#/components/schemas/CostRecommendationDataType"
+      required:
+        - type
+      type: object
+    CostRecommendationDataAttributes:
+      description: Attributes describing a single cost recommendation.
+      properties:
+        dd_resource_key:
+          description: Datadog resource key identifying the recommended resource.
+          type: string
+        potential_daily_savings:
+          $ref: "#/components/schemas/CostRecommendationDataAttributesPotentialDailySavings"
+        recommendation_type:
+          description: The kind of recommendation (for example, `terminate` or `rightsize`).
+          type: string
+        resource_id:
+          description: Cloud provider identifier of the resource.
+          type: string
+        resource_type:
+          description: Resource type (for example, `aws_ec2_instance`).
+          type: string
+        tags:
+          description: Tags attached to the recommended resource.
+          items:
+            description: A single resource tag.
+            type: string
+          type: array
+      type: object
+    CostRecommendationDataAttributesPotentialDailySavings:
+      description: Estimated daily savings if the recommendation is applied.
+      properties:
+        amount:
+          description: Numeric amount of the potential daily savings.
+          format: double
+          type: number
+        currency:
+          description: ISO 4217 currency code for the savings amount.
+          type: string
+      type: object
+    CostRecommendationDataType:
+      default: recommendation
+      description: Recommendation resource type.
+      enum:
+        - recommendation
+      example: recommendation
+      type: string
+      x-enum-varnames:
+        - RECOMMENDATION
     CostTag:
       description: A Cloud Cost Management tag.
       properties:
@@ -64113,6 +64183,64 @@ components:
       type: string
       x-enum-varnames:
         - RECOMMENDATION
+    RecommendationsFilterRequest:
+      description: Request body for filtering cost recommendations.
+      example:
+        filter: "@resource_table:aws_ec2_instance"
+        sort:
+          - expression: potential_daily_savings.amount
+            order: DESC
+      properties:
+        filter:
+          description: Filter expression applied to the recommendations.
+          type: string
+        scope:
+          description: Recommendations scope. Defaults to `ccm`; use `experiment` for experimental recommendations or `*` for both.
+          type: string
+        sort:
+          description: Ordered list of sort clauses applied to the result set.
+          items:
+            $ref: "#/components/schemas/RecommendationsFilterRequestSortItems"
+          type: array
+        view:
+          description: Active view name (for example, `active`, `dismissed`, `open`, `in-progress`, or `completed`).
+          type: string
+      type: object
+    RecommendationsFilterRequestSortItems:
+      description: A single sort clause applied to the cost recommendations result set.
+      properties:
+        expression:
+          description: Field to sort by (for example, `potential_daily_savings.amount`).
+          type: string
+        order:
+          description: Sort direction, either `ASC` or `DESC`.
+          type: string
+      type: object
+    RecommendationsPageMeta:
+      description: Top-level JSON:API meta object for paginated cost recommendation responses.
+      properties:
+        page:
+          $ref: "#/components/schemas/RecommendationsPageMetaPage"
+      type: object
+    RecommendationsPageMetaPage:
+      description: Pagination metadata for a page of cost recommendations.
+      properties:
+        filter:
+          description: The filter expression that was applied to produce this page.
+          type: string
+        next_page_token:
+          description: Opaque token used to fetch the next page; absent on the last page.
+          type: string
+        page_size:
+          description: Number of items returned in this page (1–10000).
+          format: int32
+          maximum: 10000
+          minimum: 1
+          type: integer
+        page_token:
+          description: Pagination token echoed back from the request.
+          type: string
+      type: object
     ReferenceTableCreateSourceType:
       description: The source type for creating reference table data. Only these source types can be created through this API.
       enum:
@@ -106527,6 +106655,76 @@ paths:
         operator: OR
         permissions:
           - cloud_cost_management_read
+  /api/v2/cost/recommendations:
+    post:
+      description: List cost recommendations matching a filter, with pagination and sorting.
+      operationId: SearchCostRecommendations
+      parameters:
+        - description: Number of results per page (1–10000).
+          in: query
+          name: page[size]
+          schema:
+            type: string
+        - description: Pagination token from a previous response.
+          in: query
+          name: page[token]
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            examples:
+              default:
+                value:
+                  filter: "@resource_table:aws_ec2_instance"
+                  sort:
+                    - expression: potential_daily_savings.amount
+                      order: DESC
+            schema:
+              $ref: "#/components/schemas/RecommendationsFilterRequest"
+        required: true
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                default:
+                  value:
+                    data:
+                      - attributes:
+                          dd_resource_key: "arn:aws:ec2:us-east-1:123456789012:instance/i-1234567890abcdef0"
+                          potential_daily_savings:
+                            amount: 1.23
+                            currency: USD
+                          recommendation_type: terminate
+                          resource_id: i-1234567890abcdef0
+                          resource_type: aws_ec2_instance
+                          tags:
+                            - "env:prod"
+                            - "team:ccm"
+                        id: encoded-event-id-1
+                        type: recommendation
+                    meta:
+                      page:
+                        filter: "@resource_table:aws_ec2_instance"
+                        next_page_token: ""
+                        page_size: 100
+              schema:
+                $ref: "#/components/schemas/CostRecommendationArray"
+          description: OK
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+        - AuthZ:
+            - cloud_cost_management_read
+      summary: Search cost recommendations
+      tags:
+        - Cloud Cost Management
+      x-unstable: |-
+        **Note**: This endpoint is in preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
   /api/v2/cost/tag_descriptions:
     get:
       description: List Cloud Cost Management tag key descriptions for the organization. Use `filter[cloud]` to scope the result to a single cloud provider; when omitted, both cross-cloud defaults and cloud-specific descriptions are returned.

docs/datadog_api_client.v2.model.rst

@@ -7137,6 +7137,41 @@ datadog\_api\_client.v2.model.cost\_orchestrators\_response module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.cost\_recommendation\_array module
+----------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.cost_recommendation_array
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.cost\_recommendation\_data module
+---------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.cost_recommendation_data
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.cost\_recommendation\_data\_attributes module
+---------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.cost_recommendation_data_attributes
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.cost\_recommendation\_data\_attributes\_potential\_daily\_savings module
+------------------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.cost_recommendation_data_attributes_potential_daily_savings
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.cost\_recommendation\_data\_type module
+---------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.cost_recommendation_data_type
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.cost\_tag module
 ----------------------------------------------
 
@@ -27521,6 +27556,34 @@ datadog\_api\_client.v2.model.recommendation\_type module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.recommendations\_filter\_request module
+---------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.recommendations_filter_request
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.recommendations\_filter\_request\_sort\_items module
+----------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.recommendations_filter_request_sort_items
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.recommendations\_page\_meta module
+----------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.recommendations_page_meta
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.recommendations\_page\_meta\_page module
+----------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.recommendations_page_meta_page
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.reference\_table\_create\_source\_type module
 ---------------------------------------------------------------------------
 

examples/v2/cloud-cost-management/SearchCostRecommendations.py

@@ -0,0 +1,26 @@
+"""
+Search cost recommendations returns "OK" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.cloud_cost_management_api import CloudCostManagementApi
+from datadog_api_client.v2.model.recommendations_filter_request import RecommendationsFilterRequest
+from datadog_api_client.v2.model.recommendations_filter_request_sort_items import RecommendationsFilterRequestSortItems
+
+body = RecommendationsFilterRequest(
+    filter="@resource_table:aws_ec2_instance",
+    sort=[
+        RecommendationsFilterRequestSortItems(
+            expression="potential_daily_savings.amount",
+            order="DESC",
+        ),
+    ],
+)
+
+configuration = Configuration()
+configuration.unstable_operations["search_cost_recommendations"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = CloudCostManagementApi(api_client)
+    response = api_instance.search_cost_recommendations(body=body)
+
+    print(response)

src/datadog_api_client/configuration.py

@@ -413,6 +413,7 @@ def __init__(
                 "v2.list_cost_tag_metadata": False,
                 "v2.list_cost_tag_metadata_metrics": False,
                 "v2.list_cost_tag_metadata_orchestrators": False,
+                "v2.search_cost_recommendations": False,
                 "v2.create_dashboard_secure_embed": False,
                 "v2.delete_dashboard_secure_embed": False,
                 "v2.get_dashboard_secure_embed": False,