Skip to main content

list-gcp-spend-cuds 

dci list-gcp-spend-cuds <billingAccountId> [flags]

Returns a paginated list of spend-based CUDs for the billing account. Optionally filter by CUD state (status); omit to return CUDs in all states.

gcp_service and region filters: gcp_service narrows results to one product line's coverage sub-type (compute or cloud_sql); region additionally narrows to one region scope and 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 matching CUDs returns 200 with an empty items array. Note the region query parameter uses the lower_snake_case wire form (us_central1), while each item's region field echoes the raw provider value (us-central1).

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

Flags​

FlagTypeDefaultExampleDescription
--statusstringFilter by CUD state. Omit to include all states. One of: "active", "expired", "creating", "pending", "cancelled", "not_yet_active".
--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.
--page-tokenstringOpaque cursor token returned by a previous list response. Omit to start from the beginning; an empty or absent token in a response means there are no more results. Do not parse it. A structurally invalid cursor returns 400 with code pagination_token_invalid; an expired cursor returns 400 with code pagination_token_expired — restart pagination from the beginning.
--max-resultsinteger50Maximum number of items to return. Server may return fewer. Defaults to 50; maximum 500.

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

Output​

Paginated list of spend-based CUDs.

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[].commitmentAmountnumber (double)Hourly commitment amount.
items[].commitmentUnitstringUnit for commitmentAmount.
items[].consumptionModelIdstringProvider-assigned ID of the pricing model this CUD's discount is applied through.
items[].cudIdstringCUD ID (provider-assigned).
items[].cudProductIdstringProvider-assigned ID of the product family (cudProductName) this CUD applies to.
items[].cudProductNamestringProduct family name (e.g. Compute Flexible, Cloud Run, BigQuery).
items[].cudProductTypestringRaw provider CUD type label.
items[].endTimestring (date-time)When the CUD term ends. Null when unknown.
items[].entitlementScopestringProvider resource path this CUD's discount is scoped to (typically the billing account).
items[].exportDatestring (date-time)Timestamp of the BigQuery CUD export row this item was read from.
items[].lastMonthSavingsnumber (double)Realized savings in the last full calendar month.
items[].lastMonthUtilizationnumber (double)Utilization in the last full calendar month, as a fraction from 0 to 1.
items[].namestringProvider commitment display name.
items[].regionstringRegion in raw provider form (us-central1), or global for cross-region spend CUDs. Not the lower_snake_case wire form used by the region query parameter.
items[].startTimestring (date-time)When the CUD term started. Null when unknown.
items[].statestringRaw provider commitment state.
items[].subTypestringNormalized coverage sub-type token (UPPER_SNAKE) identifying the product family within the product line.
items[].termstringRaw provider commitment term (ISO-8601 duration).
pageTokenstring
rowCountinteger (int64)Best-effort count for the filtered result set. May be null or omitted for expensive counts.
Raw JSON schema
{
  "type": "object",
  "required": [
    "items"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "GCP spend-based Committed Use Discount. Mirrors the stored provider document verbatim\n(raw values, e.g. `state` \"Active\", `term` \"P1Y\", `commitmentAmount` as a plain double).",
        "required": [
          "cudId",
          "cudProductName",
          "state"
        ],
        "properties": {
          "commitmentAmount": {
            "type": "number",
            "format": "double",
            "description": "Hourly commitment amount.",
            "example": 0.01
          },
          "commitmentUnit": {
            "type": "string",
            "description": "Unit for `commitmentAmount`.",
            "example": "$/hr"
          },
          "consumptionModelId": {
            "type": "string",
            "description": "Provider-assigned ID of the pricing model this CUD's discount is applied through.",
            "example": "D97B-0795-975B"
          },
          "cudId": {
            "type": "string",
            "description": "CUD ID (provider-assigned)."
          },
          "cudProductId": {
            "type": "string",
            "description": "Provider-assigned ID of the product family (`cudProductName`) this CUD applies to."
          },
          "cudProductName": {
            "type": "string",
            "description": "Product family name (e.g. `Compute Flexible`, `Cloud Run`, `BigQuery`).",
            "example": "Compute Flexible"
          },
          "cudProductType": {
            "type": "string",
            "description": "Raw provider CUD type label.",
            "example": "Spend-Based"
          },
          "endTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the CUD term ends. Null when unknown.",
            "nullable": true
          },
          "entitlementScope": {
            "type": "string",
            "description": "Provider resource path this CUD's discount is scoped to (typically the billing account).",
            "example": "billingAccounts/00BECC-389F90-CDF2E8"
          },
          "exportDate": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the BigQuery CUD export row this item was read from."
          },
          "lastMonthSavings": {
            "type": "number",
            "format": "double",
            "description": "Realized savings in the last full calendar month."
          },
          "lastMonthUtilization": {
            "type": "number",
            "format": "double",
            "description": "Utilization in the last full calendar month, as a fraction from 0 to 1."
          },
          "name": {
            "type": "string",
            "description": "Provider commitment display name.",
            "example": "my-commitment1"
          },
          "region": {
            "type": "string",
            "description": "Region in raw provider form (`us-central1`), or `global` for cross-region spend CUDs. Not the `lower_snake_case` wire form used by the `region` query parameter.",
            "example": "global"
          },
          "startTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the CUD term started. Null when unknown.",
            "nullable": true
          },
          "state": {
            "type": "string",
            "description": "Raw provider commitment state.",
            "example": "Active"
          },
          "subType": {
            "type": "string",
            "description": "Normalized coverage sub-type token (`UPPER_SNAKE`) identifying the product family within the product line.",
            "example": "COMPUTE_FLEXIBLE"
          },
          "term": {
            "type": "string",
            "description": "Raw provider commitment term (ISO-8601 duration).",
            "example": "P1Y"
          }
        }
      }
    },
    "pageToken": {
      "type": "string",
      "nullable": true
    },
    "rowCount": {
      "type": "integer",
      "format": "int64",
      "description": "Best-effort count for the filtered result set. May be null or omitted for expensive counts.",
      "nullable": true
    }
  }
}

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: listgcpspendcuds