# KPI
A KPI widget shows a single number.
## Data shape
``
## NQL structure
{% hint style="info" %}
Refer to the [Live Dashboards NQL examples](https://docs.nexthink.com/platform/user-guide/live-dashboards-nql-examples#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](https://docs.nexthink.com/platform/user-guide/managing-live-dashboards#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](https://docs.nexthink.com/platform/user-guide/managing-live-dashboards#adding-widgets)/[Edit a widget](https://docs.nexthink.com/platform/user-guide/managing-live-dashboards#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
* 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
* 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](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/line-chart)
* [Bar chart](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/bar-chart)
* [Single-metric gauge chart](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/single-metric-gauge-chart)
* [Multi-metric gauge chart](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/multi-metric-gauge-chart)
* [Table](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/table)
* [Heading](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/heading)
* [Filter widget](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/filter-widget)
* [Timeframe picker](https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/timeframe-picker)
---
# Agent Instructions: 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:
```
GET https://docs.nexthink.com/platform/user-guide/live-dashboards/widget-types/kpi.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
