list-gcp-planned-purchases
dci list-gcp-planned-purchases <billingAccountId> [flags]
Returns the laddering projections for the billing account, grouped by PS4C product line
(service) and region. Each service group lists one entry per available
gcp-purchases-projection document for that scope (compute scopes are global;
cloud_sql scopes are per-region).
With no filters, returns all existing projection documents in stable order: service groups
ordered compute first, then cloud_sql; within each group, regions sorted with global
first, then remaining regions alphabetically. Services with no projection documents are omitted
(not returned as empty groups). When a filter matches no documents, the response is an
empty items array (not 404). Partial projection documents return only the fields
available in storage.
gcp_service and region filters: omit both to return all available services and
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. Invalid
gcp_service or region values return 400 with code validation_failed.
404 is returned only when the billing account does not exist or the caller cannot access
it. A billing account that is not onboarded for PS4C still returns 200 with an empty
items array when no projection documents exist — use
GET /ps4commitments/v1/gcp/billing-accounts (or get-by-id) for onboarding status.
Pagination: results are paginated by service group (a whole group is never split
across pages). Groups keep the stable service order above. Use maxResults to limit
page size (default 50, max 500). When more groups remain, the response includes a
non-null pageToken; pass it unchanged on the next request with the same query parameters
(gcp_service, region, maxResults). rowCount is the number of service groups in
this page. An invalid pageToken returns 400 with code pagination_token_invalid; an
expired token returns 400 with code pagination_token_expired.
billingAccountId— GCP Billing Account ID (formatXXXXXX-XXXXXX-XXXXXX; the account that owns the CUDs) that scopes the request.
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--gcp-service | string | Filter 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". | ||
--region | string | us_east1 | Filter 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-token | string | Opaque 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-results | integer | 50 | Maximum 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
List of planned purchase projections grouped by service and region.
By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.
| Field | Type | Description |
|---|---|---|
items | array of object | |
items[].service | string | Commitment type this projection group belongs to. One of: "compute", "cloud_sql". |
items[].billingAccountId | string | GCP Billing Account ID. |
items[].regions | array of object | Per-region projection entries for this service, sorted with global first, then remaining regions alphabetically. |
items[].regions[].region | string | Region token for this projection scope (lower_snake_case, for example us_east1). compute projections use the cross-region scope global; cloud_sql projections use concrete regions. |
items[].regions[].status | string | Projection lifecycle state. When the stored document has no status, the server returns valid. One of: "valid", "expired". |
items[].regions[].purchaseApprovalStatus | string | Customer commitment approval state for this scope. Absent or unrecognized stored values (including REJECTED) are returned as pending_approval, except on autonomous automation-mode lines, where they are returned as approved since no customer approval is required. One of: "pending_approval", "approved", "paused". |
items[].regions[].pauseNote | string | Customer-visible pause reason, when purchases are paused. |
items[].regions[].requiresApproval | boolean | true when the projection as a whole requires customer approval before the planner stores a purchase plan: the target finalCommitment exceeds the approved ceiling, and/or purchaseApprovalStatus is not approved. Distinct from step-level steps[].requiresApproval, which flags individual ladder rows that exceed the ceiling. |
items[].regions[].wowViolation | boolean | true when week-over-week eligible spend dropped beyond the allowed threshold. |
items[].regions[].profile | string | Coverage target policy used to generate this projection (built-in or customer-defined). Omitted when the projection predates policy tracking. |
items[].regions[].term | string | Commitment term used for projected purchases. |
items[].regions[].finalCommitment | object | Target hourly commitment at the end of the laddering cycle. Currency is USD in v1. |
items[].regions[].finalCommitment.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].regions[].finalCommitment.currency | string | ISO 4217 currency code. |
items[].regions[].weeksToTarget | integer | Number of ladder steps remaining to reach the target commitment. |
items[].regions[].planningCycleStartDate | string (date) | First day of the planning cycle for this projection. Null when not set. |
items[].regions[].planningCycleEndDate | string (date) | Last day of the planning cycle for this projection. Null when not set. |
items[].regions[].estimatedSavings | object | Total estimated savings from the underlying recommendation. Currency is USD in v1. |
items[].regions[].estimatedSavings.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].regions[].estimatedSavings.currency | string | ISO 4217 currency code. |
items[].regions[].steps | array of object | Weekly ladder steps from the projection output. Omitted when the stored document has no output section. |
items[].regions[].steps[].order | integer | Step sequence number (1-based) within the ladder. |
items[].regions[].steps[].scheduledDate | string (date) | Calendar date (UTC) when this purchase step is scheduled to execute, with format YYYY-MM-DD. |
items[].regions[].steps[].purchaseAmount | object | Hourly commitment to purchase on this step. Nested fields omitted — see the raw JSON schema. |
items[].regions[].steps[].cumulativeCommitment | object | Total hourly commitment after this step executes. Nested fields omitted — see the raw JSON schema. |
items[].regions[].steps[].estimatedSavings | object | This step's proportional share of the projection-level estimatedSavings (allocated by purchase amount). Zero when the recommendation total is unavailable. Nested fields omitted — see the raw JSON schema. |
items[].regions[].steps[].isBootstrap | boolean | true if this is the initial bootstrap purchase. |
items[].regions[].steps[].isFinal | boolean | true if this step reaches the target commitment. |
items[].regions[].steps[].requiresApproval | boolean | true when this step's cumulativeCommitment exceeds the customer-approved commitment ceiling (approvedFinalCommitment). Used for per-step status in the ladder even when the projection-level purchaseApprovalStatus is approved. |
pageToken | string | |
rowCount | integer (int64) | Number of service groups in items for this response. |
Raw JSON schema
{
"type": "object",
"required": [
"items",
"rowCount"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"description": "Planned purchase projections for one PS4C product line.",
"required": [
"service",
"billingAccountId",
"regions"
],
"properties": {
"service": {
"type": "string",
"enum": [
"compute",
"cloud_sql"
],
"description": "Commitment type this projection group belongs to.",
"x-enumDescriptions": {
"compute": "Compute commitment type (CUDs).",
"cloud_sql": "Cloud SQL commitment type (CUDs)."
}
},
"billingAccountId": {
"type": "string",
"description": "GCP Billing Account ID."
},
"regions": {
"type": "array",
"items": {
"type": "object",
"description": "Laddering projection for one product-line and region scope.",
"required": [
"region",
"status"
],
"properties": {
"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 token for this projection scope (`lower_snake_case`, for example `us_east1`). `compute` projections use the cross-region scope `global`; `cloud_sql` projections use concrete regions."
},
"status": {
"type": "string",
"enum": [
"valid",
"expired"
],
"description": "Projection lifecycle state. When the stored document has no `status`, the server returns `valid`.",
"x-enumDescriptions": {
"valid": "Projection is current for the active planning cycle.",
"expired": "Planning cycle has lapsed; wait for the scheduler to produce a new projection."
}
},
"purchaseApprovalStatus": {
"type": "string",
"enum": [
"pending_approval",
"approved",
"paused"
],
"description": "Customer commitment approval state for this scope. Absent or unrecognized stored values (including `REJECTED`) are returned as `pending_approval`, except on autonomous automation-mode lines, where they are returned as `approved` since no customer approval is required.",
"x-enumDescriptions": {
"pending_approval": "Approve the commitment ceiling on the Planned Purchases tab in the DoiT Console before purchases can run.",
"approved": "Purchases may run up to the approved commitment ceiling.",
"paused": "Purchases are paused (Pause Purchases on Planned Purchases); see `pauseNote` for the reason."
}
},
"pauseNote": {
"type": "string",
"description": "Customer-visible pause reason, when purchases are paused.",
"nullable": true
},
"requiresApproval": {
"type": "boolean",
"description": "`true` when the projection as a whole requires customer approval before the planner\nstores a purchase plan: the target `finalCommitment` exceeds the approved ceiling,\nand/or `purchaseApprovalStatus` is not `approved`. Distinct from step-level\n`steps[].requiresApproval`, which flags individual ladder rows that exceed the ceiling."
},
"wowViolation": {
"type": "boolean",
"description": "`true` when week-over-week eligible spend dropped beyond the allowed threshold."
},
"profile": {
"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 used to generate this projection (built-in or customer-defined). Omitted when the projection predates policy tracking."
},
"term": {
"allOf": [
{
"type": "string",
"enum": [
"one_year",
"three_year"
],
"description": "Preferred or actual commitment term length for Savings Plans and related settings.",
"x-enumDescriptions": {
"one_year": "One-year commitment term.",
"three_year": "Three-year commitment term."
}
}
],
"description": "Commitment term used for projected purchases."
},
"finalCommitment": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Target hourly commitment at the end of the laddering cycle. Currency is `USD` in v1."
},
"weeksToTarget": {
"type": "integer",
"description": "Number of ladder steps remaining to reach the target commitment.",
"nullable": true
},
"planningCycleStartDate": {
"type": "string",
"format": "date",
"description": "First day of the planning cycle for this projection. Null when not set.",
"nullable": true
},
"planningCycleEndDate": {
"type": "string",
"format": "date",
"description": "Last day of the planning cycle for this projection. Null when not set.",
"nullable": true
},
"estimatedSavings": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Total estimated savings from the underlying recommendation. Currency is `USD` in v1."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"description": "A single weekly ladder step within a projection.",
"required": [
"order",
"scheduledDate",
"purchaseAmount",
"cumulativeCommitment",
"estimatedSavings",
"isBootstrap",
"isFinal",
"requiresApproval"
],
"properties": {
"order": {
"type": "integer",
"description": "Step sequence number (1-based) within the ladder."
},
"scheduledDate": {
"type": "string",
"format": "date",
"description": "Calendar date (UTC) when this purchase step is scheduled to execute, with format YYYY-MM-DD."
},
"purchaseAmount": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Hourly commitment to purchase on this step."
},
"cumulativeCommitment": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "Total hourly commitment after this step executes."
},
"estimatedSavings": {
"allOf": [
{
"type": "object",
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^-?(0|[1-9]\\d*)(\\.\\d+)?$",
"description": "Decimal monetary amount at ISO 4217 minor-unit precision (string).",
"example": "100.00"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "ISO 4217 currency code.",
"example": "USD"
}
}
}
],
"description": "This step's proportional share of the projection-level `estimatedSavings`\n(allocated by purchase amount). Zero when the recommendation total is unavailable."
},
"isBootstrap": {
"type": "boolean",
"description": "`true` if this is the initial bootstrap purchase."
},
"isFinal": {
"type": "boolean",
"description": "`true` if this step reaches the target commitment."
},
"requiresApproval": {
"type": "boolean",
"description": "`true` when this step's `cumulativeCommitment` exceeds the customer-approved\ncommitment ceiling (`approvedFinalCommitment`). Used for per-step status in the\nladder even when the projection-level `purchaseApprovalStatus` is `approved`."
}
}
},
"description": "Weekly ladder steps from the projection output. Omitted when the stored document has\nno `output` section."
}
}
},
"description": "Per-region projection entries for this service, sorted with `global` first, then\nremaining regions alphabetically."
}
}
}
},
"pageToken": {
"type": "string",
"nullable": true
},
"rowCount": {
"type": "integer",
"format": "int64",
"description": "Number of service groups in `items` for this response."
}
}
}
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 status | Exit code | Error code | Meaning |
|---|---|---|---|
| 400 | 30 | VALIDATION_ERROR | The arguments or request body were rejected. Review the command's flags and payload. |
| 401 | 10 | AUTHENTICATION_FAILED | Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY. |
| 403 | 11 | PERMISSION_DENIED | The DoiT user or the active customer context does not have access. |
| 404 | 20 | RESOURCE_NOT_FOUND | The requested resource does not exist. Check the identifier argument. |
| 500, 503 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- get-gcp-billing-account — Get a GCP billing account
- get-gcp-recommendation — Get a GCP recommendation
- list-gcp-billing-accounts — List GCP billing accounts
- list-gcp-billing-accounts-settings — List billing account engine settings
- list-gcp-recommendations — List GCP recommendations
- list-gcp-resource-cuds — List GCP resource-based Committed Use Discounts
- list-gcp-spend-cuds — List GCP spend-based Committed Use Discounts
- API reference: GET /ps4commitments/v1/gcp/billing-accounts/{billingAccountId}/planned-purchases
Aliases: listgcpplannedpurchases