list-widgets

dci list-widgets

Returns the complete catalogue of preset widgets supported by the Analytics Widgets API. Each entry contains a customer-specific id and a stable customer-facing alias; either value can be passed to the get-widget operation. An id can vary by customer or service tier, while an alias remains stable.

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

Output

OK - The complete supported widget catalogue.

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	Supported widgets. Use an item's stable alias or customer-specific id with getWidget.
items[].id	string	Customer- and tier-specific widget id. This value is accepted by getWidget and can vary between customers.
items[].alias	string	Stable customer-facing widget identifier. This value is also accepted by getWidget.
items[].name	string	Human-readable widget name.
items[].description	string	What the widget value represents.
items[].type	string	Whether the widget is supplied by DoiT or defined by a customer. One of: "custom", "preset".
items[].kind	string	Determines which property is populated in the widget's result. One of: "monetary_metric".
rowCount	integer (int64)	Number of entries in items.

Example response (--output json)

{
  "items": [
    {
      "id": "widget-example-spend-01",
      "alias": "current-month-cloud-spend",
      "name": "Current Month Cloud Spend",
      "description": "Total cloud spend accumulated during the current calendar month.",
      "type": "preset",
      "kind": "monetary_metric"
    },
    {
      "id": "widget-example-forecast-01",
      "alias": "current-month-cloud-forecast",
      "name": "Current Month Cloud Forecast",
      "description": "Forecast of total cloud spend for the current calendar month.",
      "type": "preset",
      "kind": "monetary_metric"
    }
  ],
  "rowCount": 2
}

Raw JSON schema

{
  "type": "object",
  "description": "Complete catalogue of widgets supported for the selected customer.",
  "required": [
    "items",
    "rowCount"
  ],
  "properties": {
    "items": {
      "type": "array",
      "description": "Supported widgets. Use an item's stable `alias` or customer-specific `id` with getWidget.",
      "items": {
        "type": "object",
        "description": "Catalogue entry for one widget, without its computed result.",
        "required": [
          "id",
          "alias",
          "name",
          "description",
          "type",
          "kind"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Customer- and tier-specific widget id. This value is accepted by getWidget and can vary between customers.",
            "example": "widget-example-spend-01"
          },
          "alias": {
            "type": "string",
            "description": "Stable customer-facing widget identifier. This value is also accepted by getWidget.",
            "example": "current-month-cloud-spend"
          },
          "name": {
            "type": "string",
            "description": "Human-readable widget name.",
            "example": "Current Month Cloud Spend"
          },
          "description": {
            "type": "string",
            "description": "What the widget value represents.",
            "example": "Total cloud spend accumulated during the current calendar month."
          },
          "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"
            ]
          }
        }
      }
    },
    "rowCount": {
      "type": "integer",
      "description": "Number of entries in `items`.",
      "format": "int64",
      "minimum": 0,
      "example": 2
    }
  }
}

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
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	40	API_SERVER_ERROR	The API failed to process the request. Retryable; contact DoiT support if it persists.

Related

• get-widget — Get a widget
• API reference: GET /analytics/v1/widgets

Aliases: listwidgets