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 (v1: compute / global only).
With no filters, returns all existing projection documents in stable order: service groups
sorted alphabetically by service; 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 are sorted alphabetically by service. 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 GCP planned purchases by PS4C product line. One of: "compute". | ||
--region | string | Filter 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". | ||
--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". |
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). v1 compute uses global only; future regional scopes add values such as us_east1. One of: "global". |
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. |
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"
],
"description": "Commitment type this projection group belongs to.",
"x-enumDescriptions": {
"compute": "Compute 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": {
"type": "string",
"enum": [
"global"
],
"description": "Region token for this projection scope (`lower_snake_case`). v1 compute uses `global` only; future regional scopes add values such as `us_east1`.",
"x-enumDescriptions": {
"global": "Cross-region projection scope; the only supported region in v1."
}
},
"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",
"enum": [
"conservative",
"balanced",
"max_savings"
],
"description": "Coverage target policy that balances savings against underutilization risk. Used by recommendations and planned-purchase projections.",
"x-enumDescriptions": {
"conservative": "Lower coverage target (~65%); favors stable usage and lower underutilization risk.",
"balanced": "Moderate coverage target (~80%); default balance of savings and buffer.",
"max_savings": "Aggressive coverage target (~90%); highest savings potential with a smaller buffer."
}
}
],
"description": "Coverage target policy used to generate this projection."
},
"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