Skip to main content

list-commitment-policies 

dci list-commitment-policies [flags]

Returns every commitment policy available to the tenant: the three built-in policies (conservative, balanced, max_savings) followed by the tenant's own custom policies.

Commitment policies are cloud-agnostic. A single catalog is shared by AWS and GCP, and the same policy may be assigned to AWS and GCP product lines alike.

Built-in policies are listed first, ordered from least to most aggressive target coverage; custom policies follow in creation order. Percentage parameters are expressed as 1–100, as entered in the DoiT Console. This differs from the coverage and utilization fields on recommendations and inventory, which are fractions from 0 to 1.

This endpoint is read-only. Custom policies are created, edited and deleted in the DoiT Console on the Commitment Policies page.

Flags​

FlagTypeDefaultExampleDescription
--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​

One page of the tenant's commitment policies.

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[].idstringPolicy identifier. Built-in policies use the fixed ids conservative, balanced and max_savings; custom policies have an opaque id.
items[].namestringDisplay name. Built-in names are fixed; custom names are chosen by the tenant.
items[].isBuiltInbooleantrue for the three immutable built-in policies, false for tenant-defined policies.
items[].targetCoveragenumber (double)Share of the optimal commitment the engine aims to purchase, as a percentage.
items[].lookbackDaysintegerDays of historical usage analyzed to build the recommendation baseline.
items[].ladderStepPercentnumber (double)Size of each incremental laddering step, as a percentage of the target commitment.
items[].ladderIntervalDaysintegerDays between consecutive laddering steps.
items[].bootstrapPercentnumber (double)Share of the target commitment purchased in the first (immediate) step, as a percentage.
pageTokenstringOpaque cursor for the next page. null when this is the last page.
rowCountinteger (int64)Total number of policies available to the tenant across all pages.
Raw JSON schema
{
  "type": "object",
  "required": [
    "items",
    "pageToken",
    "rowCount"
  ],
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A commitment-laddering policy, either built-in or defined by the tenant. Percentages are\n`1`–`100`, as entered in the DoiT Console, not the 0–1 fractions used by the recommendation and\ninventory coverage fields.",
        "required": [
          "id",
          "name",
          "isBuiltIn",
          "targetCoverage",
          "lookbackDays",
          "ladderStepPercent",
          "ladderIntervalDays",
          "bootstrapPercent"
        ],
        "properties": {
          "id": {
            "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": "Policy identifier. Built-in policies use the fixed ids `conservative`, `balanced` and `max_savings`; custom policies have an opaque id."
          },
          "name": {
            "type": "string",
            "description": "Display name. Built-in names are fixed; custom names are chosen by the tenant.",
            "example": "Balanced"
          },
          "isBuiltIn": {
            "type": "boolean",
            "description": "`true` for the three immutable built-in policies, `false` for tenant-defined policies."
          },
          "targetCoverage": {
            "type": "number",
            "format": "double",
            "minimum": 1,
            "maximum": 100,
            "description": "Share of the optimal commitment the engine aims to purchase, as a percentage.",
            "example": 80
          },
          "lookbackDays": {
            "type": "integer",
            "minimum": 1,
            "description": "Days of historical usage analyzed to build the recommendation baseline.",
            "example": 60
          },
          "ladderStepPercent": {
            "type": "number",
            "format": "double",
            "minimum": 1,
            "maximum": 100,
            "description": "Size of each incremental laddering step, as a percentage of the target commitment.",
            "example": 10
          },
          "ladderIntervalDays": {
            "type": "integer",
            "minimum": 1,
            "description": "Days between consecutive laddering steps.",
            "example": 7
          },
          "bootstrapPercent": {
            "type": "number",
            "format": "double",
            "minimum": 1,
            "maximum": 100,
            "description": "Share of the target commitment purchased in the first (immediate) step, as a percentage.",
            "example": 35
          }
        }
      }
    },
    "pageToken": {
      "type": "string",
      "description": "Opaque cursor for the next page. `null` when this is the last page.",
      "nullable": true
    },
    "rowCount": {
      "type": "integer",
      "format": "int64",
      "description": "Total number of policies available to the tenant across all pages."
    }
  }
}

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.
500, 50340API_SERVER_ERRORThe API failed to process the request. Retryable; contact DoiT support if it persists.

Aliases: listcommitmentpolicies