> For the complete documentation index, see [llms.txt](https://docs.nexthink.com/platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/kpi.md). # KPI A KPI widget shows a single number.
Examples of the KPI widget
## Data shape `` ## NQL structure {% hint style="info" %} Refer to the [Live Dashboards NQL examples](/platform/user-guide/live-dashboards/live-dashboards-nql-examples.md#livedashboardsnqlexamples-kpiwidget) documentation for query examples of KPI widgets. {% endhint %} Aggregation - most commonly used ``` ... summarize = ``` ## Configuring visualization fields specific to KPI widgets {% hint style="info" %} Refer to the [Managing Live Dashboards](/platform/user-guide/live-dashboards/managing-live-dashboards.md#filling-in-widget-visualization-fields) documentation to learn how to fill in the remaining configuration fields that are not specific to this widget. {% endhint %} After selecting the **KPI** option from the **Chart type** drop-down in the [Add widget](/platform/user-guide/live-dashboards/managing-live-dashboards.md#adding-widgets)/[Edit a widget](/platform/user-guide/live-dashboards/managing-live-dashboards.md#managing-widgets) pop-up: 1. Use the **Label (optional)** field to create the visible name of the KPI metric. * The text can contain special characters. There is a 50-character limit on the **Label** field. 2. Enter a **Widget description (optional)** to explain, for example, how the metric should be interpreted, calculated, or any subtleties to the metric. * The widget description appears by hovering over the info icon next to the KPI widget in the dashboard. 3. If applicable, select the option to **Display as percentage**. The system multiplies the number by 100 and adds the percent symbol. 4. Establish **Rating** thresholds to add a colored icon to the KPI widget for quick visual identification of issues. Choose from: * **1 threshold**: the KPI displays the rating as either **Good** or **Bad**.
1 Threshold example

1 threshold example

* The system evaluates thresholds with the >= operator. The example above is evaluated as follows: * **Good**: if the metric is < 0.2 * **Bad**: if the metric is >= 0.2 * Select **Invert** to invert the good and bad conditions. When inverted, the example above is evaluated as follows: * **Bad**: if the metric is < 0.2 * **Good**: if the metric is >= 0.2 * **2 thresholds**: the KPI displays a rating in one of three states: **Good**, **Average** or **Bad**.
2 thresholds example

2 thresholds example

* The system evaluates thresholds with the >= operator. The example above is evaluated as follows: * **Good**: if the metric is < 0.1 * **Average**: if the metric is >= 0.1 AND the metric is < 0.4 * **Bad**: if the metric is >= 0.4 * Select **Invert** to invert the good and bad conditions. When inverted, the example above is evaluated as follows: * **Bad**: if the metric is < 0.1 * **Average**: if the metric is >= 0.1 AND the metric is < 0.4 * **Good**: if the metric is >= 0.4 \ Only enter numeric values for the thresholds, such as decimals and integers, positive or negative numbers. For typed values, refer to the following table as the unit of the threshold value: | Typed values | Threshold values | | ------------ | --------------------------------------------------------------------------------- | | Percentages | Enter the threshold as a decimal. For example, 0.9 represents a threshold of 90%. | | Duration | The threshold value is interpreted as the number of seconds. | | Bytes | The threshold value is interpreted as the number of bytes. | *** RELATED TOPIC * [Line chart](/platform/user-guide/live-dashboards/widget-types/line-chart.md) * [Bar chart](/platform/user-guide/live-dashboards/widget-types/bar-chart.md) * [Single-metric gauge chart](/platform/user-guide/live-dashboards/widget-types/single-metric-gauge-chart.md) * [Multi-metric gauge chart](/platform/user-guide/live-dashboards/widget-types/multi-metric-gauge-chart.md) * [Table](/platform/user-guide/live-dashboards/widget-types/table.md) * [Heading](/platform/user-guide/live-dashboards/widget-types/heading.md) * [Filter widget](/platform/user-guide/live-dashboards/widget-types/filter-widget.md) * [Timeframe picker](/platform/user-guide/live-dashboards/widget-types/timeframe-picker.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/kpi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.