Skip to main content

get-commitment-policy 

dci get-commitment-policy <policyId>

Returns one commitment policy by id, with its creation and last-update times and the list of account × product-line scopes it is explicitly assigned to across AWS and GCP.

assignments lists explicit assignments only. An account whose settings have not yet been materialized falls back to balanced implicitly and does not appear here, even though the settings endpoints report it as balanced. On AWS the assignment is currently recorded per tenant and applied to every onboarded organization, so each organization appears once per product line. The list is not paginated.

Resolving assignments reads every onboarded account on both clouds. If either cloud cannot be queried the request fails rather than returning a partial list.

  • policyId — Commitment policy id. Built-in policies use conservative, balanced or max_savings; custom policies have an opaque id returned by the list endpoint.

Output​

The commitment policy with its assignments.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

FieldTypeDescription
createdTimestring (date-time)When the policy was created, RFC 3339 UTC. null if unknown.
updatedTimestring (date-time)When the policy was last written, RFC 3339 UTC. For custom policies this is the last edit; for built-in policies it also advances when DoiT re-publishes the catalog, even if the parameters did not change. null if unknown.
assignmentsarray of objectScopes explicitly assigned to this policy across AWS and GCP, sorted by cloud, accountId, service, region. Empty when the policy is not assigned anywhere.
assignments[].cloudstringCloud the scope belongs to. One of: "aws", "gcp".
assignments[].accountIdstringAWS management account id or GCP billing account id, matching managementAccountId / billingAccountId elsewhere in this API.
assignments[].servicestringProduct line the policy applies to. compute and database are AWS Savings Plan lines (GCP also has compute); cloud_sql is GCP only. One of: "compute", "database", "cloud_sql".
assignments[].regionstringRegion scope in lower_snake_case wire form (for example us_east1) for product lines assigned per region (GCP cloud_sql). null for every scope assigned per account (all AWS scopes, GCP compute); the settings endpoints report the same scope as global.
idstringPolicy identifier. Built-in policies use the fixed ids conservative, balanced and max_savings; custom policies have an opaque id.
namestringDisplay name. Built-in names are fixed; custom names are chosen by the tenant.
isBuiltInbooleantrue for the three immutable built-in policies, false for tenant-defined policies.
targetCoveragenumber (double)Share of the optimal commitment the engine aims to purchase, as a percentage.
lookbackDaysintegerDays of historical usage analyzed to build the recommendation baseline.
ladderStepPercentnumber (double)Size of each incremental laddering step, as a percentage of the target commitment.
ladderIntervalDaysintegerDays between consecutive laddering steps.
bootstrapPercentnumber (double)Share of the target commitment purchased in the first (immediate) step, as a percentage.
Raw JSON schema
{
  "allOf": [
    {
      "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
        }
      }
    },
    {
      "type": "object",
      "required": [
        "createdTime",
        "updatedTime",
        "assignments"
      ],
      "properties": {
        "createdTime": {
          "type": "string",
          "format": "date-time",
          "description": "When the policy was created, RFC 3339 UTC. `null` if unknown.",
          "nullable": true,
          "example": "2026-08-20T09:12:31Z"
        },
        "updatedTime": {
          "type": "string",
          "format": "date-time",
          "description": "When the policy was last written, RFC 3339 UTC. For custom policies this is the last edit; for built-in policies it also advances when DoiT re-publishes the catalog, even if the parameters did not change. `null` if unknown.",
          "nullable": true,
          "example": "2026-08-20T09:12:31Z"
        },
        "assignments": {
          "type": "array",
          "description": "Scopes explicitly assigned to this policy across AWS and GCP, sorted by `cloud`, `accountId`, `service`, `region`. Empty when the policy is not assigned anywhere.",
          "items": {
            "type": "object",
            "description": "One account × product-line scope a policy is explicitly assigned to, on either cloud.",
            "required": [
              "cloud",
              "accountId",
              "service",
              "region"
            ],
            "properties": {
              "cloud": {
                "type": "string",
                "enum": [
                  "aws",
                  "gcp"
                ],
                "description": "Cloud the scope belongs to.",
                "x-enumDescriptions": {
                  "aws": "An AWS organization (management account).",
                  "gcp": "A GCP billing account."
                }
              },
              "accountId": {
                "type": "string",
                "description": "AWS management account id or GCP billing account id, matching `managementAccountId` / `billingAccountId` elsewhere in this API.",
                "example": "123456789012"
              },
              "service": {
                "type": "string",
                "enum": [
                  "compute",
                  "database",
                  "cloud_sql"
                ],
                "description": "Product line the policy applies to. `compute` and `database` are AWS Savings Plan lines (GCP also has `compute`); `cloud_sql` is GCP only."
              },
              "region": {
                "type": "string",
                "description": "Region scope in `lower_snake_case` wire form (for example `us_east1`) for product lines assigned per region (GCP `cloud_sql`). `null` for every scope assigned per account (all AWS scopes, GCP `compute`); the settings endpoints report the same scope as `global`.",
                "nullable": true,
                "example": "us_east1"
              }
            }
          }
        }
      }
    }
  ]
}

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: getcommitmentpolicy