Skip to main content

get-widget 

dci get-widget <widgetId>

Returns the latest precomputed cached result for one widget. This read does not refresh or recompute the widget synchronously.

Use either the customer-specific id returned by the list-widgets operation or one of these stable aliases:

  • current-month-cloud-spend — total cloud spend accumulated during the current calendar month.
  • current-month-cloud-forecast — forecast of total cloud spend for the current calendar month.

The two concrete alias requests are:

  • GET https://api.doit.com/analytics/v1/widgets/current-month-cloud-spend
  • GET https://api.doit.com/analytics/v1/widgets/current-month-cloud-forecast

Authenticate with Authorization: Bearer &lt;token&gt;. Omit X-Tenant-Id when the credential resolves to one customer. When the credential can act on multiple customers, send X-Tenant-Id: &lt;tenant-id&gt; to select the customer. A 403 response means the caller or selected customer is not authorized or entitled to use this API.

The result's period.endTime is exclusive. Monetary amount values are decimal strings and currency values are ISO 4217 currency codes. monthToMonthGrowthPercentage and monthToMonthGrowthAmount are both null when no comparable prior-period value exists.

  • widgetId — Stable widget alias or customer-specific widget ID returned by listWidgets. Use current-month-cloud-spend for current-month accumulated spend or current-month-cloud-forecast for the current-month forecast.

Output​

OK - The widget and its latest precomputed result.

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

FieldTypeDescription
idstringCustomer- and tier-specific widget id. This value can vary between customers.
aliasstringStable customer-facing widget identifier.
typestringWhether the widget is supplied by DoiT or defined by a customer. One of: "custom", "preset".
kindstringDetermines which property is populated in the widget's result. One of: "monetary_metric".
generateTimestring (date-time)Time when the cached result was generated by the background computation.
resultobjectComputed widget result. The populated property corresponds to kind.
result.monetaryMetricobjectA monetary value over a period and its comparison with the equivalent prior period. monthToMonthGrowthPercentage and monthToMonthGrowthAmount are both null when no comparable prior-period value exists, such as when prior-period spend is zero.
result.monetaryMetric.valueobjectCurrent-period monetary value. amount is a decimal string and currency is an ISO 4217 code.
result.monetaryMetric.value.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
result.monetaryMetric.value.currencystringISO 4217 currency code.
result.monetaryMetric.periodobjectUTC date-time range covered by the widget result. endTime is exclusive.
result.monetaryMetric.period.startTimestring (date-time)Inclusive start of the period.
result.monetaryMetric.period.endTimestring (date-time)Exclusive end of the period.
result.monetaryMetric.monthToMonthGrowthPercentagenumber (double)Percentage change from the comparable prior period, or null when no comparison is available.
result.monetaryMetric.monthToMonthGrowthAmountobjectAbsolute monetary change from the comparable prior period, or null when no comparison is available.
result.monetaryMetric.monthToMonthGrowthAmount.amountstringDecimal monetary amount at ISO 4217 minor-unit precision (string).
result.monetaryMetric.monthToMonthGrowthAmount.currencystringISO 4217 currency code.

Example response (--output json)​

{
  "id": "widget-example-spend-01",
  "alias": "current-month-cloud-spend",
  "type": "preset",
  "kind": "monetary_metric",
  "generateTime": "2026-09-24T11:48:10.319Z",
  "result": {
    "monetaryMetric": {
      "value": {
        "amount": "865.24",
        "currency": "USD"
      },
      "period": {
        "startTime": "2026-09-01T00:00:00Z",
        "endTime": "2026-10-01T00:00:00Z"
      },
      "monthToMonthGrowthPercentage": 12.34,
      "monthToMonthGrowthAmount": {
        "amount": "94.88",
        "currency": "USD"
      }
    }
  }
}
Raw JSON schema
{
  "type": "object",
  "description": "Widget metadata and its latest precomputed cached result.",
  "required": [
    "id",
    "alias",
    "type",
    "kind",
    "generateTime",
    "result"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Customer- and tier-specific widget id. This value can vary between customers.",
      "example": "widget-example-spend-01"
    },
    "alias": {
      "type": "string",
      "description": "Stable customer-facing widget identifier.",
      "example": "current-month-cloud-spend"
    },
    "type": {
      "type": "string",
      "description": "Whether the widget is supplied by DoiT or defined by a customer.",
      "enum": [
        "custom",
        "preset"
      ]
    },
    "kind": {
      "type": "string",
      "description": "Determines which property is populated in the widget's `result`.",
      "enum": [
        "monetary_metric"
      ]
    },
    "generateTime": {
      "type": "string",
      "format": "date-time",
      "description": "Time when the cached result was generated by the background computation.",
      "example": "2026-09-24T11:48:10.319Z"
    },
    "result": {
      "type": "object",
      "description": "Computed widget result. The populated property corresponds to `kind`.",
      "required": [
        "monetaryMetric"
      ],
      "properties": {
        "monetaryMetric": {
          "type": "object",
          "description": "A monetary value over a period and its comparison with the equivalent prior period.\n`monthToMonthGrowthPercentage` and `monthToMonthGrowthAmount` are both `null` when no\ncomparable prior-period value exists, such as when prior-period spend is zero.",
          "required": [
            "value",
            "period",
            "monthToMonthGrowthPercentage",
            "monthToMonthGrowthAmount"
          ],
          "properties": {
            "value": {
              "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": "Current-period monetary value. `amount` is a decimal string and `currency` is an ISO 4217 code."
            },
            "period": {
              "type": "object",
              "description": "UTC date-time range covered by the widget result. `endTime` is exclusive.",
              "required": [
                "startTime",
                "endTime"
              ],
              "properties": {
                "startTime": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Inclusive start of the period.",
                  "example": "2026-09-01T00:00:00Z"
                },
                "endTime": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Exclusive end of the period.",
                  "example": "2026-10-01T00:00:00Z"
                }
              }
            },
            "monthToMonthGrowthPercentage": {
              "type": "number",
              "format": "double",
              "nullable": true,
              "description": "Percentage change from the comparable prior period, or `null` when no comparison is available.",
              "example": 12.34
            },
            "monthToMonthGrowthAmount": {
              "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"
                    }
                  }
                }
              ],
              "nullable": true,
              "description": "Absolute monetary change from the comparable prior period, or `null` when no comparison is available."
            }
          }
        }
      }
    }
  }
}

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