---
title: "List recommendations"
method: GET
path: "/v2/optimize/recommendations"
tags: ["recommendations"]
---

# List recommendations

`GET /v2/optimize/recommendations`

Gets recommendations for a specified organization in paginated form. This endpoint supports filtering, sorting, and grouping by various columns as well as searching. **Note:** The `optimization_id` field is deprecated; use `recommendation_type_id` instead.

## Query parameters

- `status` Status[], nullable — Filter by status
- `recommendation_type_id` string[], nullable — Filter by recommendation type ID (e.g., CIR-AWS-00216).
- `recommendation_type_name` string[], nullable — Filter by recommendation type name.
- `category` string[], nullable — Filter by recommendation category (e.g., optimization).
- `effort` string[], nullable — Filter by effort level required to address the recommendation. Accepts: low, medium, high, not_set.
- `source` string[], nullable — Filter by recommendation source (e.g., CloudZero, AWS: Trusted Advisor).
- `cost_impact_last_30_days[gte]` union — Minimum 30-day cost impact to include. Only recommendations with cost impact greater than or equal to this value are returned (default $1.00).
  - number
  - string
- `group_by` string — Specifies a column to group the recommendations by. The resulting data will contain the group by column, the total recommendations in the group, and the cost impact of the recommendations in the group.
- `search` string — Returns recommendations where at least one column contains a search term. Search terms are separated by spaces.
- `limit` integer — Number of recommendations to show per page (default: 60000)
- `offset` integer — Number of recommendations to skip for pagination (default 0)
- `sort_key` 'cost_impact_last_30_days'
- `sort_order` 'desc'
- `cursor` string, binary, nullable — Opaque pagination cursor returned from a previous request. When provided, other filter and sort parameters are ignored.

## Response `200`

Successful Response

- ListRecommendationsResponse
  - `recommendations` union[] — The recommendations or groups of recommendations if a group by column is specified
    - union
      - Recommendation
        - `recommendation_id` string, required — The ID of the recommendation
        - `title` string, required — The title of the recommendation
        - `category` string, required — The category of the recommendation
        - `optimization_id` string — Deprecated: renamed to recommendation_type_id. The optimization type ID.
        - `recommendation_type_id` string, required — The recommendation type ID
        - `source` string, nullable — The source of the recommendation
        - `effort` string — The effort of the recommendation
        - `status` string — The status of the recommendation
        - `work_item` string, nullable — The ID of a work item associated with a configured ticketing system like Jira, etc.
        - `cost_impact_last_30_days` number — The cost impact of the recommendation over the last 30 days
        - `realized_savings_last_30_days` number — The realized savings of the recommendation over the last 30 days
        - `resource` string, nullable — The resource that this recommendation is about
        - `resource_type` string, nullable — The type of the resource
        - `resource_name` string, nullable — The name of the resource
        - `account` string[] — The cloud provider account of the recommendation
        - `addressed_on_ts` integer, nullable — The timestamp of when the recommendation was addressed
        - `cloud_provider` string[] — The cloud provider of the recommendation
        - `region` string[] — The cloud provider region of the recommendation
        - `service` string[] — The cloud provider service of the recommendation
        - `created` integer — The Unix timestamp of when the recommendation was created
        - `cluster` string[], nullable — The Kubernetes cluster associated with the recommendation, if one exists.
        - `namespace` string[], nullable — The Kubernetes namespace associated with the recommendation, if one exists.
        - `pod` string[], nullable — The Kubernetes pod associated with the recommendation, if one exists.
      - RecommendationsGroup
        - `group` string — The name of the group. The actual field name will be the `group_by` column name.
        - `recommendations` integer — The total number of recommendations in the group
        - `cost_impact_last_30_days` number — The cost impact of the recommendations in the group
  - `sorting` SortOptions
    - `available` AvailableSortOptions
      - `sort_keys` SortKeyEnum[] — The available sort keys
      - `sort_orders` SortOrderEnum[] — The available sort orders
    - `current` ActualSortOptions
      - `sort_key` 'cost_impact_last_30_days'
      - `sort_order` 'desc'
  - `filtering` FilterOptions
    - `available` object — The available filter options
    - `current` object — The current filter options
  - `group_by` GroupByOptions
    - `available` string[] — The available columns to group by
    - `current` string[] — The current columns that the recommendations are grouped by
  - `columns` string[] — The columns in the response
  - `multiple_value_columns` string[] — Columns in the response that are an array of values
  - `display_names` object — A mapping of column names to display names
  - `pagination` PaginationResponse
    - `page_count` integer — The total number of pages available
    - `item_count` integer — The number of items in the current page
    - `total_count` integer — The total number of items available
    - `cursor` CursorResponse
      - `next_cursor` string, nullable — The cursor to use to paginate the recommendations. This cursor should be used as the cursor parameter in the next request to get the next page of recommendations.
      - `previous_cursor` string, nullable — The cursor to use to paginate the recommendations. This cursor should be used as the cursor parameter in the previous request to get the previous page of recommendations.
      - `has_next` boolean — Whether there is a next page of recommendations
      - `has_previous` boolean — Whether there is a previous page of recommendations
  - `unique_recommendation` UniqueRecommendationResponse
    - `total_count` integer — The total number of unique recommendations across all pages. Individual recommendations that may be accounted for in multiple groups are only counted once here.
    - `total_cost_impact_last_30_days` number — The cost impact of the unique recommendations across all pages. Individual recommendations that may be accounted for in multiple groups are only counted once here.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources.md) · [All operations](https://skmtc.dev/cloudzero/apis/cloudzero-api-v2-resources/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cloudzero/cloudzero-api-v2-resources/revisions/fd805a0e75e5/schema)