Skip to main content

list-gcp-resource-cuds 

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

Returns a paginated list of resource-based (vCPU / memory) CUDs for the billing account. Optionally filter by CUD state (status). Omit to return CUDs in all states.

  • 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", "cancelled", "not_yet_active".
--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 resource-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[].autoRenewbooleantrue if the CUD is configured to renew automatically at the end of its term.
items[].billingProjectNumberstringGCP project number billed for this CUD's charges.
items[].commitmentNumericIdstringResource-based CUD ID (provider-assigned).
items[].createdTimestring (date-time)When the CUD was created. Null when unknown.
items[].customTermEligibleUntilstring (date-time)Latest date by which this CUD is eligible for a custom-term exchange. Null when not eligible.
items[].endTimestring (date-time)When the CUD term ends. Null when unknown.
items[].exportDatestring (date-time)Timestamp of the BigQuery CUD export row this item was read from.
items[].hardwareScopestringMachine family this CUD's reserved resources apply to.
items[].hostProjectIdstringGCP project ID hosting the reserved resources.
items[].inventoryStatestringRaw provider inventory state.
items[].lastMonthCPUCoveragenumber (double)Fraction (0–1) of vCPU usage covered by this CUD in the last full calendar month.
items[].lastMonthCPUSavingsnumber (double)Realized vCPU savings in the last full calendar month.
items[].lastMonthCPUUtilizationnumber (double)Fraction (0–1) of this CUD's reserved vCPUs actually used in the last full calendar month.
items[].lastMonthMemoryCoveragenumber (double)Fraction (0–1) of memory usage covered by this CUD in the last full calendar month.
items[].lastMonthMemorySavingsnumber (double)Realized memory savings in the last full calendar month.
items[].lastMonthMemoryUtilizationnumber (double)Fraction (0–1) of this CUD's reserved memory actually used in the last full calendar month.
items[].namestringProvider commitment display name.
items[].organizationIdstringGCP organization ID that owns the host project.
items[].planstringRaw provider commitment plan.
items[].regionstringGCP region the reserved resources are scoped to.
items[].reservedResourcesarray of objectResources reserved by this CUD.
items[].reservedResources[].amountstring
items[].reservedResources[].resourceKindstring
items[].startTimestring (date-time)When the CUD term started. Null when unknown.
items[].statestringRaw provider commitment state.
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 resource-based Committed Use Discount (vCPU / memory). Mirrors the stored provider\ndocument verbatim (raw values, e.g. `state`/`status` \"ACTIVE\", `plan` \"TWELVE_MONTH\").",
        "required": [
          "commitmentNumericId",
          "state"
        ],
        "properties": {
          "autoRenew": {
            "type": "boolean",
            "description": "`true` if the CUD is configured to renew automatically at the end of its term."
          },
          "billingProjectNumber": {
            "type": "string",
            "description": "GCP project number billed for this CUD's charges.",
            "example": "744947574473"
          },
          "commitmentNumericId": {
            "type": "string",
            "description": "Resource-based CUD ID (provider-assigned).",
            "example": "6100297402551498897"
          },
          "createdTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the CUD was created. Null when unknown.",
            "nullable": true
          },
          "customTermEligibleUntil": {
            "type": "string",
            "format": "date-time",
            "description": "Latest date by which this CUD is eligible for a custom-term exchange. Null when not eligible.",
            "nullable": true
          },
          "endTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the CUD term ends. Null when unknown.",
            "nullable": true
          },
          "exportDate": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the BigQuery CUD export row this item was read from."
          },
          "hardwareScope": {
            "type": "string",
            "description": "Machine family this CUD's reserved resources apply to.",
            "example": "GENERAL_PURPOSE_E2"
          },
          "hostProjectId": {
            "type": "string",
            "description": "GCP project ID hosting the reserved resources.",
            "example": "test-k8s-project-468707"
          },
          "inventoryState": {
            "type": "string",
            "description": "Raw provider inventory state.",
            "example": "ACTIVE"
          },
          "lastMonthCPUCoverage": {
            "type": "number",
            "format": "double",
            "description": "Fraction (0–1) of vCPU usage covered by this CUD in the last full calendar month."
          },
          "lastMonthCPUSavings": {
            "type": "number",
            "format": "double",
            "description": "Realized vCPU savings in the last full calendar month."
          },
          "lastMonthCPUUtilization": {
            "type": "number",
            "format": "double",
            "description": "Fraction (0–1) of this CUD's reserved vCPUs actually used in the last full calendar month."
          },
          "lastMonthMemoryCoverage": {
            "type": "number",
            "format": "double",
            "description": "Fraction (0–1) of memory usage covered by this CUD in the last full calendar month."
          },
          "lastMonthMemorySavings": {
            "type": "number",
            "format": "double",
            "description": "Realized memory savings in the last full calendar month."
          },
          "lastMonthMemoryUtilization": {
            "type": "number",
            "format": "double",
            "description": "Fraction (0–1) of this CUD's reserved memory actually used in the last full calendar month."
          },
          "name": {
            "type": "string",
            "description": "Provider commitment display name.",
            "example": "resource-based-cud-1"
          },
          "organizationId": {
            "type": "string",
            "description": "GCP organization ID that owns the host project.",
            "example": "604768222286"
          },
          "plan": {
            "type": "string",
            "description": "Raw provider commitment plan.",
            "example": "TWELVE_MONTH"
          },
          "region": {
            "type": "string",
            "description": "GCP region the reserved resources are scoped to.",
            "example": "us-central1"
          },
          "reservedResources": {
            "type": "array",
            "description": "Resources reserved by this CUD.",
            "items": {
              "type": "object",
              "required": [
                "resourceKind",
                "amount"
              ],
              "properties": {
                "amount": {
                  "type": "string",
                  "example": "1"
                },
                "resourceKind": {
                  "type": "string",
                  "example": "VCPU"
                }
              }
            }
          },
          "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"
          }
        }
      }
    },
    "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: listgcpresourcecuds