list-aws-organizations
dci list-aws-organizations [flags]
Returns all AWS organizations (accounts) accessible to the authenticated tenant. Use as the entry point to discover AWS organization account IDs, and organization-level onboarding status of the available commitment types and savings metrics.
Each item includes metadata, trailing 30-day aggregate statistics, precomputed YTD/lifetime savings totals per Savings Plan (SP) type, and estimated monthly potential savings (monthlyPotentialSavings) per SP type from the latest projection. Sum across items for customer-level totals.
The managementAccountId of each item is the positional argument every organization-scoped
command takes (list-aws-member-accounts, list-aws-savings-plans,
list-aws-reserved-instances, list-aws-recommendations, list-aws-planned-purchases).
Fetch the organizations first, then run the per-organization commands.
Examples
# The AWS organizations visible to the active customer, with onboarding status and savings metrics; the entry point for every other `*-aws-*` command.
dci list-aws-organizations
# Just the IDs and names, to pick a `<management-account-id>`.
dci list-aws-organizations --fields managementAccountId,displayName --output json
# Every page as JSON, for scripts (sum the items for customer-level totals).
dci list-aws-organizations --all --output json
# Browse in the full-screen viewer.
dci list-aws-organizations -M interactive
Flags
| Flag | Type | Default | Example | Description |
|---|---|---|---|---|
--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 AWS Organizations. One item per AWS organization.
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 AWS organization's management (payer) account. |
items[].displayName | string | Human-readable account name, if available. Defaults to the AWS Organizations account name; may be overridden by a custom name set on the asset in the DoiT Console. Null when no name is available. |
items[].onboardingStatus | object | PerfectScale for Commitments onboarding status for each commitment type on the AWS organization (compute, database). A commitment type is omitted when it is not onboarded. When done, inventory and recommendations for that commitment type are available. |
items[].onboardingStatus.compute | object | |
items[].onboardingStatus.compute.status | string | Current onboarding lifecycle stage for this product line. One of: "not_started", "onboarding", "done", "error". |
items[].onboardingStatus.compute.onboardingStartedAt | string (date-time) | When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started. |
items[].onboardingStatus.database | object | |
items[].onboardingStatus.database.status | string | Current onboarding lifecycle stage for this product line. One of: "not_started", "onboarding", "done", "error". |
items[].onboardingStatus.database.onboardingStartedAt | string (date-time) | When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started. |
items[].savingsPlansSyncTime | string (date-time) | Timestamp of the last successful Savings Plan inventory sync. Null when a sync has not completed yet. |
items[].stats30d | object | Trailing 30-day aggregate metrics (esr, savings), broken down by SP type. |
items[].stats30d.compute | object | Minimal 30-day aggregate. Only esr and savings are persisted at this granularity. Responses are denominated in USD. |
items[].stats30d.compute.esr | number (double) | Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, 0.187 is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available. |
items[].stats30d.compute.savings | object | Total savings realized over the last 30 days from active commitments (USD). Nested fields omitted — see the raw JSON schema. |
items[].stats30d.database | object | Minimal 30-day aggregate. Only esr and savings are persisted at this granularity. Responses are denominated in USD. |
items[].stats30d.database.esr | number (double) | Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, 0.187 is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available. |
items[].stats30d.database.savings | object | Total savings realized over the last 30 days from active commitments (USD). Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals | object | Year-to-date and lifetime savings per Savings Plan (SP) type. Same values as returned by GET /ps4commitments/v1/aws/organizations/\{managementAccountId\} for this organization, so callers can sum totals across AWS organizations without making an extra get-by-id call per organization. Lifetime is bounded by each AWS organization's PerfectScale for Commitments onboarding start date. |
items[].savingsTotals.compute | object | Running savings figures derived server-side from the full monthly stats history, as the sum of onDemandCost - costWithSavings per month. lifetime starts at PerfectScale for Commitments onboarding; ytd starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated. |
items[].savingsTotals.compute.ytd | object | Year-to-date realized savings. Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals.compute.lifetime | object | Lifetime realized savings since onboarding. Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals.database | object | Running savings figures derived server-side from the full monthly stats history, as the sum of onDemandCost - costWithSavings per month. lifetime starts at PerfectScale for Commitments onboarding; ytd starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated. |
items[].savingsTotals.database.ytd | object | Year-to-date realized savings. Nested fields omitted — see the raw JSON schema. |
items[].savingsTotals.database.lifetime | object | Lifetime realized savings since onboarding. Nested fields omitted — see the raw JSON schema. |
items[].monthlyPotentialSavings | object | Estimated monthly additional savings per SP type for this AWS organization from the latest purchase projection. |
items[].monthlyPotentialSavings.compute | object | |
items[].monthlyPotentialSavings.compute.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].monthlyPotentialSavings.compute.currency | string | ISO 4217 currency code. |
items[].monthlyPotentialSavings.database | object | |
items[].monthlyPotentialSavings.database.amount | string | Decimal monetary amount at ISO 4217 minor-unit precision (string). |
items[].monthlyPotentialSavings.database.currency | string | ISO 4217 currency code. |
pageToken | string | |
rowCount | integer (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": [
"managementAccountId"
],
"properties": {
"managementAccountId": {
"type": "string",
"description": "12-digit account number of the AWS organization's management (payer) account.",
"example": "123456789012"
},
"displayName": {
"type": "string",
"description": "Human-readable account name, if available. Defaults to the AWS Organizations account name; may be overridden by a custom name set on the asset in the DoiT Console. Null when no name is available.",
"nullable": true,
"example": "Acme Prod"
},
"onboardingStatus": {
"allOf": [
{
"type": "object",
"description": "PerfectScale for Commitments onboarding status for each commitment type on the AWS organization (`compute`, `database`). A commitment type is omitted when it is not onboarded. When `done`, inventory and recommendations for that commitment type are available.",
"properties": {
"compute": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Current onboarding lifecycle stage for this product line.",
"enum": [
"not_started",
"onboarding",
"done",
"error"
],
"x-enumDescriptions": {
"not_started": "This commitment type has not begun onboarding.",
"onboarding": "Onboarding is in progress (inventory and models still initializing).",
"done": "Onboarding completed, commitments and recommendations are available.",
"error": "Onboarding failed, check the DoiT Console or contact support for remediation."
}
},
"onboardingStartedAt": {
"type": "string",
"format": "date-time",
"description": "When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started.",
"nullable": true
}
}
},
"database": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"description": "Current onboarding lifecycle stage for this product line.",
"enum": [
"not_started",
"onboarding",
"done",
"error"
],
"x-enumDescriptions": {
"not_started": "This commitment type has not begun onboarding.",
"onboarding": "Onboarding is in progress (inventory and models still initializing).",
"done": "Onboarding completed, commitments and recommendations are available.",
"error": "Onboarding failed, check the DoiT Console or contact support for remediation."
}
},
"onboardingStartedAt": {
"type": "string",
"format": "date-time",
"description": "When PerfectScale for Commitments first began tracking commitments for this commitment type. Bounds lifetime savings totals and onboarding history in the DoiT Console. Omitted or null when onboarding has not started.",
"nullable": true
}
}
}
}
}
]
},
"savingsPlansSyncTime": {
"type": "string",
"format": "date-time",
"description": "Timestamp of the last successful Savings Plan inventory sync. Null when a sync has not completed yet.",
"nullable": true,
"example": "2026-01-01T00:00:00.000Z"
},
"stats30d": {
"type": "object",
"description": "Trailing 30-day aggregate metrics (`esr`, `savings`), broken down by SP type.",
"properties": {
"compute": {
"type": "object",
"description": "Minimal 30-day aggregate. Only `esr` and `savings` are persisted at this granularity. Responses are denominated in USD.",
"properties": {
"esr": {
"type": "number",
"format": "double",
"description": "Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, `0.187` is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available.",
"nullable": true,
"example": 0.187
},
"savings": {
"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 savings realized over the last 30 days from active commitments (USD)."
}
}
},
"database": {
"type": "object",
"description": "Minimal 30-day aggregate. Only `esr` and `savings` are persisted at this granularity. Responses are denominated in USD.",
"properties": {
"esr": {
"type": "number",
"format": "double",
"description": "Effective Savings Rate (ESR) over the last 30 days, as a fraction from 0 to 1 (for example, `0.187` is 18.7%). Measures what share of eligible spend is saved through active commitments compared with equivalent on-demand cost. Higher ESR means greater realized savings. Null when not yet available.",
"nullable": true,
"example": 0.187
},
"savings": {
"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 savings realized over the last 30 days from active commitments (USD)."
}
}
}
}
},
"savingsTotals": {
"type": "object",
"description": "Year-to-date and lifetime savings per Savings Plan (SP) type. Same values as returned by `GET /ps4commitments/v1/aws/organizations/{managementAccountId}` for this organization, so callers can sum totals across AWS organizations without making an extra get-by-id call per organization. Lifetime is bounded by each AWS organization's PerfectScale for Commitments onboarding start date.",
"properties": {
"compute": {
"type": "object",
"required": [
"ytd",
"lifetime"
],
"description": "Running savings figures derived server-side from the full monthly stats history, as the sum of `onDemandCost - costWithSavings` per month. `lifetime` starts at PerfectScale for Commitments onboarding; `ytd` starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated.",
"properties": {
"ytd": {
"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": "Year-to-date realized savings."
},
"lifetime": {
"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": "Lifetime realized savings since onboarding."
}
}
},
"database": {
"type": "object",
"required": [
"ytd",
"lifetime"
],
"description": "Running savings figures derived server-side from the full monthly stats history, as the sum of `onDemandCost - costWithSavings` per month. `lifetime` starts at PerfectScale for Commitments onboarding; `ytd` starts at the later of January 1 of the current year and onboarding. Months before the bound are excluded; the bound month and the current month are prorated.",
"properties": {
"ytd": {
"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": "Year-to-date realized savings."
},
"lifetime": {
"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": "Lifetime realized savings since onboarding."
}
}
}
}
},
"monthlyPotentialSavings": {
"allOf": [
{
"type": "object",
"description": "Estimated monthly additional savings per Savings Plan (SP) type, taken from the latest PerfectScale for Commitments purchase projection. Unlike `savingsTotals` (realized YTD/lifetime savings), this is a forward-looking estimate of the monthly savings achievable if the recommended commitments are purchased. For member accounts, the AWS organization figure is attributed by each member account's share of trailing-60-day SP-eligible on-demand cost. A per-SP-type value of `0.00` means the latest projection is missing, expired, or empty. The field is omitted entirely only for accounts that have never had potential savings computed.",
"properties": {
"compute": {
"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"
}
}
},
"database": {
"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": "Estimated monthly additional savings per SP type for this AWS organization from the latest purchase projection."
}
}
}
},
"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 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. |
| 500, 503 | 40 | API_SERVER_ERROR | The API failed to process the request. Retryable; contact DoiT support if it persists. |
Related
- get-aws-organization — Get an AWS organization
- list-aws-member-accounts — List member accounts under an AWS organization
- list-aws-organizations-settings — List account and commitment settings per AWS organization
- list-aws-savings-plans — List AWS Savings Plans
- list-aws-recommendations — List AWS recommendations
- API reference: GET /ps4commitments/v1/aws/organizations
Aliases: listawsorganizations