---
updatedAt: 2026-10-12T08:41:01.000Z
agentTools:
  projectIndex: https://developer.doit.com/llms.txt
---

# 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.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "DoiT Cloud Intelligence",
    "description": "Programmatic access to DoiT Platform",
    "version": "v1"
  },
  "servers": [
    {
      "url": "https://api.doit.com"
    }
  ],
  "security": [
    {
      "api_key": []
    },
    {
      "tenantId": [],
      "api_key": []
    }
  ],
  "tags": [
    {
      "name": "Widgets (Beta)",
      "description": "Beta. Read precomputed current-month cloud spend and forecast metrics. Widget results are\nrefreshed in the background; reading a widget returns the latest cached result and never\nstarts a synchronous refresh. Use the list operation to discover the complete catalogue."
    }
  ],
  "paths": {
    "/analytics/v1/widgets": {
      "get": {
        "tags": [
          "Widgets (Beta)"
        ],
        "summary": "List widgets",
        "description": "Returns the complete catalogue of preset widgets supported by the Analytics Widgets API.\nEach entry contains a customer-specific `id` and a stable customer-facing `alias`; either\nvalue can be passed to the get-widget operation. An `id` can vary by customer or service\ntier, while an `alias` remains stable.\n\nAuthenticate with `Authorization: Bearer <token>`. Omit `X-Tenant-Id` when the credential\nresolves to one customer. When the credential can act on multiple customers, send\n`X-Tenant-Id: <tenant-id>` to select the customer. A `403` response means the caller or\nselected customer is not authorized or entitled to use this API.",
        "operationId": "listWidgets",
        "parameters": [
          {
            "$ref": "#/components/parameters/tenantId"
          }
        ],
        "responses": {
          "200": {
            "description": "OK - The complete supported widget catalogue.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WidgetList"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "instance",
          "code",
          "retryable"
        ],
        "additionalProperties": true,
        "description": "RFC 9457 Problem Details — standard DoiT error envelope for all non-2xx responses.",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://developer.doit.com/errors/not_found"
          },
          "title": {
            "type": "string",
            "example": "Resource not found"
          },
          "status": {
            "type": "integer",
            "example": 404
          },
          "detail": {
            "type": "string",
            "example": "customer not found"
          },
          "instance": {
            "type": "string",
            "format": "uri",
            "example": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
          },
          "code": {
            "type": "string",
            "pattern": "^([a-z][a-z0-9_]*|[a-z][a-z0-9]*(?:-[a-z0-9]+)*\\.[a-z][a-z0-9_]*)$",
            "example": "not_found"
          },
          "retryable": {
            "type": "boolean",
            "example": false
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "issue"
              ],
              "properties": {
                "issue": {
                  "type": "string",
                  "pattern": "^[a-z][a-z0-9_]*$"
                },
                "field": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          },
          "docsUrl": {
            "type": "string",
            "format": "uri",
            "nullable": true
          }
        }
      },
      "WidgetItem": {
        "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": {
            "$ref": "#/components/schemas/WidgetKind"
          }
        }
      },
      "WidgetList": {
        "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": {
              "$ref": "#/components/schemas/WidgetItem"
            }
          },
          "rowCount": {
            "type": "integer",
            "description": "Number of entries in `items`.",
            "format": "int64",
            "minimum": 0,
            "example": 2
          }
        }
      },
      "WidgetKind": {
        "type": "string",
        "description": "Determines which property is populated in the widget's `result`.",
        "enum": [
          "monetary_metric"
        ]
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid credentials.",
        "headers": {
          "WWW-Authenticate": {
            "description": "Bearer challenge per RFC 6750.",
            "schema": {
              "type": "string",
              "example": "Bearer realm=\"api.doit.com\""
            }
          },
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/unauthorized",
              "title": "Unauthorized",
              "status": 401,
              "detail": "missing or invalid bearer token",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "unauthorized",
              "retryable": false
            }
          }
        }
      },
      "Forbidden": {
        "description": "Authenticated but not authorized to perform this request.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/forbidden",
              "title": "Forbidden",
              "status": 403,
              "detail": "caller does not have permission to access this customer's commitments",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "forbidden",
              "retryable": false
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Unexpected server error.",
        "headers": {
          "Request-Id": {
            "$ref": "#/components/headers/RequestId"
          },
          "Content-Language": {
            "$ref": "#/components/headers/ContentLanguage"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://developer.doit.com/errors/internal_error",
              "title": "Internal server error",
              "status": 500,
              "detail": "an unexpected error occurred",
              "instance": "https://api.doit.com/requests/req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9",
              "code": "internal_error",
              "retryable": true
            }
          }
        }
      }
    },
    "parameters": {
      "tenantId": {
        "in": "header",
        "name": "X-Tenant-Id",
        "required": false,
        "description": "Customer (tenant) ID for the request. This is separate from authentication: you still pass your personal or service account API token in the `Authorization` header (`Bearer <token>`). See [Get Started](https://developer.doit.com/docs/start).\n\n**When to omit (most callers):** If your personal or service account token belongs to a single customer, omit this header. The API resolves that customer from the token.\n\n**When to send:** If your credential can access more than one customer, set `X-Tenant-Id` to the customer ID you want to act on. A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.",
        "schema": {
          "type": "string",
          "example": "Kp2mN8qL4vR0sT1wX3yZ"
        }
      }
    },
    "securitySchemes": {
      "api_key": {
        "type": "apiKey",
        "name": "Authorization",
        "description": "Use the \"Bearer <API_KEY>\" format or sign in for autofill",
        "in": "header"
      },
      "tenantId": {
        "type": "apiKey",
        "name": "X-Tenant-Id",
        "description": "Customer (tenant) ID for the request. Separate from your API token: always authenticate with `Authorization: Bearer <token>` (personal or service account). See [Get Started](https://developer.doit.com/docs/start). Omit when your token is scoped to a single customer (resolved automatically). A service account can select an active direct or nested descendant of its home customer; the endpoint's normal permissions, entitlements, and resource-ownership checks still apply. A service-account target outside that customer subtree returns `403 Forbidden`. Prefer this header over the legacy `customerContext` query parameter, which only applies to legacy API keys and is ignored by personal and service account tokens.",
        "in": "header"
      }
    },
    "headers": {
      "RequestId": {
        "description": "DoiT request identifier for support and log correlation. Format `req_<ULID>`.",
        "schema": {
          "type": "string",
          "pattern": "^req_[0-9A-HJKMNP-TV-Z]{26}$",
          "example": "req_01HX9P2KQVJ8Z3M4T5N6V7W8Y9"
        }
      },
      "ContentLanguage": {
        "description": "Language of the response body. Always `en` for this API.",
        "schema": {
          "type": "string",
          "enum": [
            "en"
          ]
        }
      }
    }
  },
  "x-samples-languages": [
    "curl",
    "go",
    "node",
    "python"
  ],
  "x-cli-config": {
    "security": "oauth2",
    "params": {
      "client_id": "cli"
    }
  }
}
```