list-aws-planned-purchases
dci list-aws-planned-purchases managementAccountId [flags]
Returns the laddering projections for the organization — one item per available
purchases-projection document (typically compute and/or database; up to four
product lines as PS4C expands).
With no filters, returns all existing projection documents for the organization in
stable product-line order (compute, then database, then any future lines in enum
order). When a filtered product line has no projection document, the response is an
empty items array (not 404). Partial projection documents return only the fields
available in storage.
404 is returned only when the organization does not exist or the caller cannot
access it. An organization that is not onboarded for PS4C still returns 200 with an
empty items array when no projection documents exist — use
GET /ps4commitments/v1/aws/organizations (or get-by-id) for onboardingStatus.
Pagination: results are returned in stable product-line order (compute, then
database, then any future lines in enum order). Use maxResults to limit page size
(default 50, max 500). When more items remain, the response includes a non-null
pageToken; pass it unchanged on the next request with the same query parameters
(service, maxResults). rowCount is the number of items in this page. An invalid
pageToken returns 400 with code pagination_token_invalid; an expired token returns
400 with code pagination_token_expired.
Flags
--service: (string enum:"compute","database")
--page-token: (string)
--max-results: (integer default:50)
Output
Paginated list of planned purchase projections.
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[].managementAccountId | string | 12-digit account number of the organization's management (payer) account. |
items[].service | string | PS4C product line this projection belongs to. One of: "compute", "database". |
items[].status | string | Projection lifecycle state. expired means the planning cycle has lapsed and a new projection should be triggered by the automated scheduler. When the stored document has no status, the server returns valid. One of: "valid", "expired". |
items[].purchaseApprovalStatus | string | Customer commitment approval state for this product line. Absent or unrecognized stored values are returned as pending_approval. One of: "pending_approval", "approved", "paused". |
items[].pauseNote | string | Customer-visible pause reason, when purchases are paused. |
items[].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[].wowViolation | boolean | true when week-over-week eligible spend dropped beyond the allowed threshold. |
items[].profile | string | Coverage target policy. - conservative — lower coverage target (~65%) - balanced — moderate coverage target (~80%) - max_savings — aggressive coverage target (~90%) One of: "conservative", "balanced", "max_savings". |
items[].term | string | Commitment term length. One of: "one_year", "three_year". |
items[].paymentOption | string | One of: "no_upfront", "partial_upfront", "all_upfront", null. |
items[].finalCommitment | object | Target hourly commitment at the end of the laddering cycle. Currency is USD in v1. |
items[].finalCommitment.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].finalCommitment.currency | string | ISO 4217 currency code. |
items[].weeksToTarget | integer | Number of ladder steps remaining to reach the target commitment. |
items[].planningCycleStartDate | string (date) | |
items[].planningCycleEndDate | string (date) | |
items[].estimatedSavings | object | Total estimated savings from the underlying recommendation. Currency is USD in v1. |
items[].estimatedSavings.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].estimatedSavings.currency | string | ISO 4217 currency code. |
items[].steps | array of object | Weekly ladder steps from the projection output. Omitted when the stored document has no output section. |
items[].steps[].order | integer | Step sequence number (1-based). |
items[].steps[].scheduledDate | string (date) | |
items[].steps[].purchaseAmount | object | Hourly commitment to purchase on this step. |
items[].steps[].purchaseAmount.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].purchaseAmount.currency | string | ISO 4217 currency code. |
items[].steps[].cumulativeCommitment | object | Total hourly commitment after this step executes. |
items[].steps[].cumulativeCommitment.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].cumulativeCommitment.currency | string | ISO 4217 currency code. |
items[].steps[].estimatedSavings | object | This step's proportional share of the projection-level estimatedSavings (allocated by purchase amount). Zero when the recommendation total is unavailable. |
items[].steps[].estimatedSavings.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].steps[].estimatedSavings.currency | string | ISO 4217 currency code. |
items[].steps[].isBootstrap | boolean | true if this is the initial bootstrap purchase. |
items[].steps[].isFinal | boolean | true if this step reaches the target commitment. |
items[].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 items in items for this response. |
Raw JSON schema
{
"type": "object",
"required": [
"items",
"rowCount"
],
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"managementAccountId",
"service",
"status"
],
"properties": {
"managementAccountId": {
"type": "string",
"description": "12-digit account number of the organization's management (payer) account."
},
"service": {
"type": "string",
"enum": [
"compute",
"database"
],
"description": "PS4C product line this projection belongs to."
},
"status": {
"type": "string",
"enum": [
"valid",
"expired"
],
"description": "Projection lifecycle state. `expired` means the planning cycle has lapsed and a\nnew projection should be triggered by the automated scheduler. When the stored\ndocument has no `status`, the server returns `valid`."
},
"purchaseApprovalStatus": {
"type": "string",
"enum": [
"pending_approval",
"approved",
"paused"
],
"description": "Customer commitment approval state for this product line. Absent or unrecognized\nstored values are returned as `pending_approval`."
},
"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": {
"type": "string",
"enum": [
"conservative",
"balanced",
"max_savings"
],
"description": "Coverage target policy.\n- `conservative` — lower coverage target (~65%)\n- `balanced` — moderate coverage target (~80%)\n- `max_savings` — aggressive coverage target (~90%)\n"
},
"term": {
"type": "string",
"enum": [
"one_year",
"three_year"
],
"description": "Commitment term length."
},
"paymentOption": {
"type": "string",
"enum": [
"no_upfront",
"partial_upfront",
"all_upfront",
null
],
"nullable": true
},
"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)."
},
"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",
"nullable": true
},
"planningCycleEndDate": {
"type": "string",
"format": "date",
"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)."
},
"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)."
},
"scheduledDate": {
"type": "string",
"format": "date"
},
"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)."
},
"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)."
},
"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)."
},
"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."
}
}
}
},
"pageToken": {
"type": "string",
"nullable": true
},
"rowCount": {
"type": "integer",
"format": "int64",
"description": "Number of items 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 | 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. |
Aliases: listawsplannedpurchases