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 the customer's compute settings (preferredCommitmentPeriod).

gcp_service and region filters: a gcp_service is required to select which product line's settings determine the term — omitting both returns no recommendations. 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. Invalid gcp_service or region values return 400. In v1 the only supported values are gcp_service=compute and region=global.

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 GCP planned purchases by PS4C product line. One of: "compute".
--regionstringFilter GCP planned purchases by region scope. Requires gcp_service; when omitted together with gcp_service, all available regions for all available product lines are returned. A request with region but no gcp_service returns 400 with code gcp_service_required. One of: "global".

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 currently configured for this commitment type (display name). One of: "Conservative", "Balanced (Recommended)", "Max Savings".
items[].regionstringRegion scope for this recommendation. v1 supports global only. One of: "global".
items[].servicestringPS4C product line (gcp_service) this recommendation belongs to. One of: "compute".
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 (0–1) of eligible spend if the recommended commitment were in place.
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": {
            "type": "string",
            "enum": [
              "Conservative",
              "Balanced (Recommended)",
              "Max Savings"
            ],
            "description": "Coverage target policy currently configured for this commitment type (display name).",
            "x-enumDescriptions": {
              "Conservative": "Lower coverage target; favors stable usage and lower underutilization risk.",
              "Balanced (Recommended)": "Moderate coverage target; default balance of savings and buffer.",
              "Max Savings": "Aggressive coverage target; highest savings potential with a smaller buffer."
            }
          },
          "region": {
            "type": "string",
            "enum": [
              "global"
            ],
            "description": "Region scope for this recommendation. v1 supports `global` only."
          },
          "service": {
            "type": "string",
            "enum": [
              "compute"
            ],
            "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",
            "description": "Estimated average coverage (0–1) of eligible spend if the recommended commitment were in place."
          }
        }
      }
    },
    "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