Skip to main content

list-aws-savings-plans 

dci list-aws-savings-plans <managementAccountId> [flags]

Returns a paginated list of Savings Plans for the specified AWS organization. Optionally filter by plan type (type) and state (status). Omit both filters to return all plans for the AWS organization.

  • managementAccountId — 12-digit AWS management (payer) account ID (the account that owns the AWS Organization) that scopes the request.

Filters: --type (compute, ec2_instance, sagemaker, database) and --status (active, expired, queued, queued_returning, pending_return, returning, payment_pending, payment_failed). Omit both to return every plan.

Examples​

# Savings Plans across the organization, with commitment, utilization and last-month savings.
dci list-aws-savings-plans <management-account-id>
# Active Compute Savings Plans only.
dci list-aws-savings-plans <management-account-id> --type compute --status active
# Every page as JSON, for scripts.
dci list-aws-savings-plans <management-account-id> --all --output json
# Browse in the full-screen viewer.
dci list-aws-savings-plans <management-account-id> -M interactive

Flags​

FlagTypeDefaultExampleDescription
--typestringFilter by Savings Plan type. Omit to include all types. One of: "compute", "ec2_instance", "sagemaker", "database".
--statusstringFilter by Savings Plan lifecycle state. Omit to include all states. One of: "pending_return", "returning", "active", "expired", "queued", "queued_returning", "payment_failed", "payment_pending".
--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 Savings Plans.

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[].commitmentIdstringSavings Plan ID (AWS-assigned GUID).
items[].savingsPlanArnstringFull ARN (Amazon Resource Name) of the Savings Plan, when known. null when DoiT doesn’t have the ARN stored yet.
items[].savingsPlanTypestringSavings Plan type. Values match the AWS Savings Plans API in snake_case, plus database. One of: "compute", "ec2_instance", "sagemaker", "database".
items[].statestringSavings Plan lifecycle state. Values match the AWS Savings Plans API in snake_case. One of: "pending_return", "returning", "active", "expired", "queued", "queued_returning", "payment_failed", "payment_pending".
items[].paymentOptionstringUpfront payment structure for this Savings Plan. One of: "no_upfront", "partial_upfront", "all_upfront".
items[].termDurationstringCommitment term length for this Savings Plan.
items[].commitmentobjectHourly commitment amount.
items[].commitment.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
items[].commitment.currencystringISO 4217 currency code.
items[].upfrontPaymentAmountobjectUpfront payment amount. Null or omitted when payment option is no_upfront.
items[].upfrontPaymentAmount.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
items[].upfrontPaymentAmount.currencystringISO 4217 currency code.
items[].recurringPaymentAmountobjectRecurring (typically hourly or monthly) payment amount after any upfront.
items[].recurringPaymentAmount.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
items[].recurringPaymentAmount.currencystringISO 4217 currency code.
items[].ec2InstanceFamilystringEC2 instance family for ec2_instance plans (for example, m5). Null for other plan types.
items[].regionstringAWS region for plans that are region-scoped (for example, us-east-1). Null when not applicable.
items[].startTimestring (date-time)When the Savings Plan started or is scheduled to start. Null when unknown.
items[].endTimestring (date-time)When the Savings Plan ends or ended. Null when unknown.
items[].lastMonthUtilizationnumber (double)Utilization percentage (0–1) in the last full calendar month. Null when not yet available.
items[].lastMonthSavingsobjectRealized savings in the last full calendar month. Null if not yet available.
items[].lastMonthSavings.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
items[].lastMonthSavings.currencystringISO 4217 currency code.
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",
        "required": [
          "commitmentId",
          "savingsPlanType",
          "state"
        ],
        "properties": {
          "commitmentId": {
            "type": "string",
            "description": "Savings Plan ID (AWS-assigned GUID)."
          },
          "savingsPlanArn": {
            "type": "string",
            "description": "Full ARN (Amazon Resource Name) of the Savings Plan, when known. `null` when DoiT doesn’t have the ARN stored yet.",
            "nullable": true
          },
          "savingsPlanType": {
            "type": "string",
            "description": "Savings Plan type. Values match the AWS Savings Plans API in snake_case, plus `database`.",
            "enum": [
              "compute",
              "ec2_instance",
              "sagemaker",
              "database"
            ],
            "x-enumDescriptions": {
              "compute": "Compute Savings Plans that apply across eligible compute usage.",
              "ec2_instance": "EC2 Instance Savings Plans scoped to a family and region.",
              "sagemaker": "SageMaker Savings Plans.",
              "database": "Database Savings Plans for eligible database spend."
            }
          },
          "state": {
            "type": "string",
            "description": "Savings Plan lifecycle state. Values match the AWS Savings Plans API in snake_case.",
            "enum": [
              "pending_return",
              "returning",
              "active",
              "expired",
              "queued",
              "queued_returning",
              "payment_failed",
              "payment_pending"
            ],
            "x-enumDescriptions": {
              "pending_return": "Return has been requested and is waiting to complete.",
              "returning": "Return is in progress.",
              "active": "Plan is active and providing coverage.",
              "expired": "Plan term has ended.",
              "queued": "Plan is queued to start at a future time.",
              "queued_returning": "Queued plan that is also pending return.",
              "payment_failed": "Purchase or renewal payment failed.",
              "payment_pending": "Purchase or renewal payment is pending."
            }
          },
          "paymentOption": {
            "type": "string",
            "description": "Upfront payment structure for this Savings Plan.",
            "enum": [
              "no_upfront",
              "partial_upfront",
              "all_upfront"
            ],
            "x-enumDescriptions": {
              "no_upfront": "All charges paid monthly; no upfront payment.",
              "partial_upfront": "A portion paid upfront; remainder billed monthly.",
              "all_upfront": "Full commitment paid upfront."
            }
          },
          "termDuration": {
            "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 length for this Savings Plan."
          },
          "commitment": {
            "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 amount."
          },
          "upfrontPaymentAmount": {
            "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": "Upfront payment amount. Null or omitted when payment option is `no_upfront`."
          },
          "recurringPaymentAmount": {
            "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": "Recurring (typically hourly or monthly) payment amount after any upfront."
          },
          "ec2InstanceFamily": {
            "type": "string",
            "description": "EC2 instance family for `ec2_instance` plans (for example, `m5`). Null for other plan types.",
            "nullable": true
          },
          "region": {
            "type": "string",
            "description": "AWS region for plans that are region-scoped (for example, `us-east-1`). Null when not applicable.",
            "nullable": true
          },
          "startTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the Savings Plan started or is scheduled to start. Null when unknown.",
            "nullable": true
          },
          "endTime": {
            "type": "string",
            "format": "date-time",
            "description": "When the Savings Plan ends or ended. Null when unknown.",
            "nullable": true
          },
          "lastMonthUtilization": {
            "type": "number",
            "format": "double",
            "description": "Utilization percentage (0–1) in the last full calendar month. Null when not yet available.",
            "nullable": true
          },
          "lastMonthSavings": {
            "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": "Realized savings in the last full calendar month. Null if not yet available."
          }
        }
      }
    },
    "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: listawssavingsplans