Skip to main content

list-gcp-recommendations 

dci list-gcp-recommendations <billingAccountId> [flags]

Returns commitment purchase recommendations for the billing account, filtered to the term preferred in each product line's settings (preferredCommitmentPeriod).

gcp_service and region filters: omit both to return recommendations for all product lines (compute, cloud_sql) across all their regions. Supply gcp_service alone to return all regions for that service; supply both to return a single service/region scope. region requires gcp_service — a request with region but no gcp_service returns 400 with code gcp_service_required. A region that is malformed or incompatible with gcp_service (compute is global-only, cloud_sql is regional-only) returns 400 with code validation_failed; a well-formed, compatible region with no data returns 200 with an empty items array.

404 is returned only when the billing account does not exist or the caller cannot access it. A billing account with no matching recommendation documents returns 200 with an empty items array.

  • billingAccountId — GCP Billing Account ID (format XXXXXX-XXXXXX-XXXXXX; the account that owns the CUDs) that scopes the request.

Flags​

FlagTypeDefaultExampleDescription
--gcp-servicestringFilter by PerfectScale for Commitments GCP product line. Omit to return all product lines. Matching is case-insensitive; the value is lowercased before validation. One of: "compute", "cloud_sql".
--regionstringus_east1Filter by region scope, in lower_snake_case wire form (for example us_east1), or the literal global. Requires gcp_service; a request with region but no gcp_service returns 400 with code gcp_service_required. When both are omitted, all available regions for all available product lines are returned. The value is format-validated, not checked against a closed region list: compute accepts only global, cloud_sql accepts only concrete regions (never global), and a value that is malformed or incompatible with gcp_service returns 400 with code validation_failed. A well-formed, service-compatible region with no data returns 200 with an empty result. Matching is case-insensitive; the value is lowercased before validation.

Every command also accepts the CLI-wide flags for output shaping — see Output formats and Table output options.

Output​

List of GCP recommendations.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
itemsarray of object
items[].policystringCoverage target policy configured for this product line and region scope (built-in or customer-defined).
items[].regionstringRegion scope for this recommendation, in lower_snake_case wire form (for example us_east1). global for compute; a concrete region for cloud_sql.
items[].servicestringPS4C product line (gcp_service) this recommendation belongs to. One of: "compute", "cloud_sql".
items[].currentCommitmentnumber (double)Active hourly commitment ($/h) currently applied to this billing account and product line, including commitments already purchased.
items[].recommendedCommitmentnumber (double)Recommended total hourly commitment ($/h) based on usage patterns and your commitment policy. Designed to increase savings while managing underutilization risk.
items[].potentialAdditionalSavingsnumber (double)Estimated additional monthly savings ($/month) from applying the recommended commitment relative to currentCommitment.
items[].estimatedAverageCoveragenumber (double)Estimated average coverage of eligible spend if the recommended commitment were in place, as a fraction from 0 to 1 (for example, 0.5517 is 55.17%). Same scale as esr and the inventory utilization and coverage fields.
pageTokenstringReserved for pagination. Currently always null.
rowCountinteger (int64)Number of recommendations returned in items.
Raw JSON schema
{
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A CUD purchase recommendation for a (service, region) scope.",
        "properties": {
          "policy": {
            "allOf": [
              {
                "type": "string",
                "description": "ID of a commitment policy: either one of the built-in policies — `conservative` (lower\ncoverage target, ~65%), `balanced` (moderate, ~80%), `max_savings` (aggressive, ~90%) — or the\nID of a policy the customer defined in the DoiT Console. One catalog is shared by AWS and GCP,\nand the same policy may be assigned to any AWS organization or GCP billing account product\nline. Custom policies make this an open list, so it is not an enum; treat the value as an\nopaque identifier and use the commitment-policies endpoint to resolve it.",
                "example": "balanced"
              }
            ],
            "description": "Coverage target policy configured for this product line and region scope (built-in or customer-defined)."
          },
          "region": {
            "allOf": [
              {
                "type": "string",
                "pattern": "^(global|[a-z]+(_[a-z0-9]+)+)$",
                "description": "GCP region scope in the DCI `lower_snake_case` wire form (for example `us_east1`), or the\nliteral `global` for cross-region scopes. This is not the raw provider spelling (`us-east1`);\nthe same pattern applies to the `region` query parameter. Regions are discovery-driven, so the\nlist is open rather than an enum.",
                "example": "us_east1"
              }
            ],
            "description": "Region scope for this recommendation, in `lower_snake_case` wire form (for example `us_east1`). `global` for `compute`; a concrete region for `cloud_sql`."
          },
          "service": {
            "type": "string",
            "enum": [
              "compute",
              "cloud_sql"
            ],
            "description": "PS4C product line (`gcp_service`) this recommendation belongs to."
          },
          "currentCommitment": {
            "type": "number",
            "format": "double",
            "description": "Active hourly commitment ($/h) currently applied to this billing account and product line, including commitments already purchased."
          },
          "recommendedCommitment": {
            "type": "number",
            "format": "double",
            "description": "Recommended total hourly commitment ($/h) based on usage patterns and your commitment policy. Designed to increase savings while managing underutilization risk."
          },
          "potentialAdditionalSavings": {
            "type": "number",
            "format": "double",
            "description": "Estimated additional monthly savings ($/month) from applying the recommended commitment relative to `currentCommitment`."
          },
          "estimatedAverageCoverage": {
            "type": "number",
            "format": "double",
            "minimum": 0,
            "maximum": 1,
            "description": "Estimated average coverage of eligible spend if the recommended commitment were in place, as a fraction from 0 to 1 (for example, `0.5517` is 55.17%). Same scale as `esr` and the inventory utilization and coverage fields."
          }
        }
      }
    },
    "pageToken": {
      "type": "string",
      "description": "Reserved for pagination. Currently always `null`.",
      "nullable": true
    },
    "rowCount": {
      "type": "integer",
      "format": "int64",
      "description": "Number of recommendations returned in `items`."
    }
  }
}

Errors​

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping
HTTP statusExit codeError codeMeaning
40030VALIDATION_ERRORThe arguments or request body were rejected. Review the command's flags and payload.
40110AUTHENTICATION_FAILEDNot signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
40311PERMISSION_DENIEDThe DoiT user or the active customer context does not have access.
40420RESOURCE_NOT_FOUNDThe requested resource does not exist. Check the identifier argument.
500, 50340API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: listgcprecommendations