Skip to main content

get-commitment 

dci get-commitment <id>

Returns a commitment by the specified Id.

  • id — Commitment ID as shown by dci list-commitments.

Examples​

# Show one commitment with its periods, attainment, and forecast.
dci get-commitment <commitment-id>
# The full record as JSON, including per-period marketplace limits.
dci get-commitment <commitment-id> --output json
# Just the totals.
dci get-commitment <commitment-id> --fields name,currency,totalCommitmentValue,totalCurrentAttainment,totalForecastValue --output json

Output​

OK - Commitment returned.

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

FieldTypeDescription
idstringThe unique identifier of the commitment.
namestringThe name of the commitment.
startDatestring (date-time)The start date of the commitment.
endDatestring (date-time)The end date of the commitment.
currencystringThe currency of the commitment (e.g., USD).
cloudProviderstringThe cloud provider associated with the commitment. One of: "google-cloud", "amazon-web-services", "microsoft-azure".
totalCommitmentValuenumber (double)The total value of the commitment across all periods.
totalCurrentAttainmentnumber (double)The total attained spend across all periods, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments. Rollover between periods is excluded, so excess or shortfall carried into a later period is not counted again; each period's carried amount is reported separately in periods[].rolloverFromPrevPeriod. Equals the sum of periods[].cashAttainment.
totalMarketplaceSpendnumber (double)The total marketplace spend across all periods.
totalForecastValuenumber (double)The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast.
periodsarray of objectThe list of commitment periods.
periods[].startDatestring (date-time)The start date of the period.
periods[].endDatestring (date-time)The end date of the period.
periods[].commitmentValuenumber (double)The commitment value for this period.
periods[].marketplaceLimitPercentagenumber (double)The marketplace limit as a percentage (0-100).
periods[].marketplaceSpendnumber (double)The marketplace spend within this period.
periods[].marketplaceLimitAmountnumber (double)The marketplace limit in absolute currency for this period, derived as commitmentValue * marketplaceLimitPercentage / 100.
periods[].forecastValuenumber (double)The projected spend at the end of this period, based on a linear regression over the period's total spend series. 0 when insufficient history is available to compute a forecast.
periods[].cashAttainmentnumber (double)This period's own attained spend, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments, excluding anything carried in from the previous period. Summed across periods it equals totalCurrentAttainment. To measure the period against its commitmentValue the way the console does, use cashAttainment + rolloverFromPrevPeriod + shortfallRollover; the period's remaining amount is commitmentValue minus that. Excess carried out to the next period is not deducted from this period.
periods[].rolloverFromPrevPeriodnumber (double)The amount carried into this period from the previous period under the commitment's rollover terms. Positive for excess rollover, negative for shortfall rollover, 0 when nothing was carried (always 0 for the first period). amazon-web-services commitments no longer roll over, so this is 0 for them unless the commitment was last calculated before that change. Not included in cashAttainment or totalCurrentAttainment.
periods[].shortfallRollovernumber (double)The part of this period's shortfall carried forward to the next period under the commitment's shortfall rollover terms, where it appears as a negative rolloverFromPrevPeriod. 0 when nothing was carried forward, including while the period is still open and for the last period. The console counts this amount as met within this period. Not included in cashAttainment or totalCurrentAttainment.
createTimeinteger (int64)The creation time in milliseconds since epoch.
updateTimeinteger (int64)The last update time in milliseconds since epoch.
Raw JSON schema
{
  "type": "object",
  "description": "A commitment contract.",
  "properties": {
    "id": {
      "type": "string",
      "description": "The unique identifier of the commitment."
    },
    "name": {
      "type": "string",
      "description": "The name of the commitment."
    },
    "startDate": {
      "type": "string",
      "format": "date-time",
      "example": "2024-03-10T23:00:00Z",
      "description": "The start date of the commitment."
    },
    "endDate": {
      "type": "string",
      "format": "date-time",
      "example": "2024-03-10T23:00:00Z",
      "description": "The end date of the commitment."
    },
    "currency": {
      "type": "string",
      "description": "The currency of the commitment (e.g., USD).",
      "example": "USD"
    },
    "cloudProvider": {
      "type": "string",
      "description": "The cloud provider associated with the commitment.",
      "enum": [
        "google-cloud",
        "amazon-web-services",
        "microsoft-azure"
      ]
    },
    "totalCommitmentValue": {
      "type": "number",
      "format": "double",
      "description": "The total value of the commitment across all periods."
    },
    "totalCurrentAttainment": {
      "type": "number",
      "format": "double",
      "description": "The total attained spend across all periods, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments. Rollover between periods is excluded, so excess or shortfall carried into a later period is not counted again; each period's carried amount is reported separately in `periods[].rolloverFromPrevPeriod`. Equals the sum of `periods[].cashAttainment`."
    },
    "totalMarketplaceSpend": {
      "type": "number",
      "format": "double",
      "description": "The total marketplace spend across all periods."
    },
    "totalForecastValue": {
      "type": "number",
      "format": "double",
      "description": "The total projected spend at the end of the commitment, summed across all periods. 0 when insufficient history is available to compute a forecast."
    },
    "periods": {
      "type": "array",
      "description": "The list of commitment periods.",
      "items": {
        "type": "object",
        "description": "A single period within a commitment.",
        "properties": {
          "startDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-03-10T23:00:00Z",
            "description": "The start date of the period."
          },
          "endDate": {
            "type": "string",
            "format": "date-time",
            "example": "2024-03-10T23:00:00Z",
            "description": "The end date of the period."
          },
          "commitmentValue": {
            "type": "number",
            "format": "double",
            "description": "The commitment value for this period."
          },
          "marketplaceLimitPercentage": {
            "type": "number",
            "format": "double",
            "description": "The marketplace limit as a percentage (0-100)."
          },
          "marketplaceSpend": {
            "type": "number",
            "format": "double",
            "description": "The marketplace spend within this period."
          },
          "marketplaceLimitAmount": {
            "type": "number",
            "format": "double",
            "description": "The marketplace limit in absolute currency for this period, derived as commitmentValue * marketplaceLimitPercentage / 100."
          },
          "forecastValue": {
            "type": "number",
            "format": "double",
            "description": "The projected spend at the end of this period, based on a linear regression over the period's total spend series. 0 when insufficient history is available to compute a forecast."
          },
          "cashAttainment": {
            "type": "number",
            "format": "double",
            "description": "This period's own attained spend, on a cash basis. This is eligible spend (including capped marketplace spend and credits) plus adjustments, excluding anything carried in from the previous period. Summed across periods it equals `totalCurrentAttainment`. To measure the period against its `commitmentValue` the way the console does, use `cashAttainment + rolloverFromPrevPeriod + shortfallRollover`; the period's remaining amount is `commitmentValue` minus that. Excess carried out to the next period is not deducted from this period."
          },
          "rolloverFromPrevPeriod": {
            "type": "number",
            "format": "double",
            "description": "The amount carried into this period from the previous period under the commitment's rollover terms. Positive for excess rollover, negative for shortfall rollover, 0 when nothing was carried (always 0 for the first period). amazon-web-services commitments no longer roll over, so this is 0 for them unless the commitment was last calculated before that change. Not included in `cashAttainment` or `totalCurrentAttainment`."
          },
          "shortfallRollover": {
            "type": "number",
            "format": "double",
            "description": "The part of this period's shortfall carried forward to the next period under the commitment's shortfall rollover terms, where it appears as a negative `rolloverFromPrevPeriod`. 0 when nothing was carried forward, including while the period is still open and for the last period. The console counts this amount as met within this period. Not included in `cashAttainment` or `totalCurrentAttainment`."
          }
        }
      }
    },
    "createTime": {
      "type": "integer",
      "format": "int64",
      "description": "The creation time in milliseconds since epoch."
    },
    "updateTime": {
      "type": "integer",
      "format": "int64",
      "description": "The last update time in milliseconds since epoch."
    }
  }
}

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.

Aliases: getcommitment