[comment]: # ({8c8dd5c7-978cbb20})
# 28 Top hosts

[comment]: # ({/8c8dd5c7-978cbb20})

[comment]: # ({4e99026f-c5138763})
### Description

These parameters and the possible property values for the respective dashboard widget field objects allow to configure the [*Top hosts*](/manual/web_interface/frontend_sections/dashboards/widgets/top_hosts) widget in `dashboard.create` and `dashboard.update` methods.

::: noteimportant
Widget `fields` properties are not validated during the creation or update of a dashboard.
This allows users to modify [built-in widgets](/manual/web_interface/frontend_sections/dashboards/widgets) and create [custom widgets](/devel/modules/tutorials/widget), but also introduces the risk of creating or updating widgets incorrectly.
To ensure the successful creation or update of the *Top hosts* widget, please refer to the parameter behavior outlined in the tables below.
:::

[comment]: # ({/4e99026f-c5138763})

[comment]: # ({6c1cb502-224c01f4})
### Parameters

The following parameters are supported for the *Top hosts* widget.

|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Refresh interval*|<|0|rf_rate|0 - No refresh;<br>10 - 10 seconds;<br>30 - 30 seconds;<br>60 - *(default)* 1 minute;<br>120 - 2 minutes;<br>600 - 10 minutes;<br>900 - 15 minutes.|
|*Host groups*|<|2|groupids.0|[Host group](/manual/api/reference/hostgroup/get) ID.<br><br>Note: To configure multiple host groups, create a dashboard widget field object for each host group with an incremented number in the property name.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|<|*Host groups (Widget)*|1|groupids.\_reference|Instead of [Host group](/manual/api/reference/hostgroup/get) ID:<br>`ABCDE._hostgroupids` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its *Reference* parameter set to "`ABCDE`") as the data source for host groups.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|*Hosts*|<|3|hostids.0|[Host](/manual/api/reference/host/get) ID.<br><br>Note: To configure multiple hosts, create a dashboard widget field object for each host with an incremented number in the property name. For multiple hosts, the parameter *Host groups* must either be not configured at all or configured with at least one host group that the configured hosts belong to.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|<|*Hosts (Widget/Dashboard)*|1|hostids.\_reference|Instead of [Host](/manual/api/reference/host/get) ID:<br>`DASHBOARD.hostids` - set the dashboard [host selector](/manual/web_interface/frontend_sections/dashboards/widgets#override-host) as the data source for hosts;<br>`ABCDE._hostids` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its *Reference* parameter set to "`ABCDE`") as the data source for hosts.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|*Host tags*|<|<|<|<|
|<|*Evaluation type*|0|evaltype|0 - *(default)* And/Or;<br>2 - Or.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|^|*Tag name*|1|tags.0.tag|Any string value.<br><br>Note: The number in the property name references tag order in the tag evaluation list.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if configuring *Host tags*<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|^|*Operator*|0|tags.0.operator|0 - Contains;<br>1 - Equals;<br>2 - Does not contain;<br>3 - Does not equal;<br>4 - Exists;<br>5 - Does not exist.<br><br>Note: The number in the property name references tag order in the tag evaluation list.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if configuring *Host tags*<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|^|*Tag value*|1|tags.0.value|Any string value.<br><br>Note: The number in the property name references tag order in the tag evaluation list.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if configuring *Host tags*<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|
|*Show hosts in maintenance*|<|0|maintenance|0 - *(default)* Disabled;<br>1 - Enabled.|
|*Columns* (see below)|<|<|<|<|
|*Order by*|<|0|column|Column numeric value from the configured columns.|
|*Order*|<|0|order|2 - *(default)* Top N;<br>3 - Bottom N.|
|*Host limit*|<|0|show_lines|Possible values range from 1-1000.<br><br>Default: 10.<br><br>This parameter is not supported if configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object).|

[comment]: # ({/6c1cb502-224c01f4})

[comment]: # ({e8e68707-8266fc04})
#### Columns

Columns have common parameters and additional parameters depending on the configuration of the parameter *Data*.

::: noteclassic
For all parameters related to columns the number in the property name (e.g. columns.0.name) references a column for which the parameter is configured.
:::

[comment]: # ({/e8e68707-8266fc04})

[comment]: # ({e35e7f37-bba2be85})
The following parameters are supported for all columns.

|Parameter|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*Name*|1|columns.0.name|Any string value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required*|
|*Data*|0|columns.0.data|1 - Item value;<br>2 - Host name;<br>3 - Text.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required*|
|*Base color*|1|columns.0.base_color|Hexadecimal color code (e.g. `FF0000`).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required*|

[comment]: # ({/e35e7f37-bba2be85})

[comment]: # ({02077e27-5843843c})
##### Item value

The following parameters are supported if *Data* is set to "Item value".

::: noteclassic
The first number in the *Thresholds* property name (e.g. columnsthresholds.0.color.0) references the column for which thresholds are configured, while the second number references threshold place in a list, sorted in ascending order.
However, if thresholds are configured in a different order, the values will be sorted in ascending order after updating widget configuration in Zabbix frontend (e.g. `"threshold.0.threshold":"5"` → `"threshold.0.threshold":"1"`; `"threshold.1.threshold":"1"` → `"threshold.1.threshold": "5"`).
:::

|Parameter|<|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-|--------|--|--------|-------------------------------|
|*Item*|<|1 |columns.0.item|Valid item name.<br><br>When configuring the widget on a [template dashboard](/manual/api/reference/templatedashboard/object), only items configured on the template should be set.|
|*Display item value as*|<|0|columns.0.display_value_as|0 - *(default)* Numeric;<br>1 - Text;<br>2 - Binary.|
|*Display*|<|0|columns.0.display|1 - *(default)* As is;<br>2 - Bar;<br>3 - Indicators;<br>6 - Sparkline.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric"|
|*Min*|<|1|columns.0.min|Any numeric value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Bar" or "Indicators"|
|*Max*|<|1|columns.0.max|Any numeric value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Bar" or "Indicators"|
|*Decimal places*|<|0|columns.0.decimal_places|Possible values range from 0-10.<br><br>Default: 2.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric"|
|*Sparkline*|<|<|<|<|
|<|*Width*|0|columns.0.sparkline.width|Possible values range from 0-10.<br><br>Default: 1.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"|
|^|*Fill*|0|columns.0.sparkline.fill|Possible values range from 0-10.<br><br>Default: 3.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"|
|^|*Color*|1|columns.0.sparkline.color|Hexadecimal color code (e.g. `FF0000`).<br><br>Default: `42A5F5`.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"|
|^|*Time period*|1|columns.0.sparkline.time_period.\_reference|`DASHBOARD._timeperiod` - set the dashboard [time period selector](/manual/web_interface/time_period_selector) as the data source;<br>`ABCDE._timeperiod` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its `reference` parameter equal to `ABCDE`) as the data source.<br><br>Default: `DASHBOARD._timeperiod`<br><br>Alternatively, you can set the time period only in the *From* and *To* parameters.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"|
|^|*From*|1|columns.0.sparkline.time_period.from|Valid time string in absolute (`YYYY-MM-DD hh:mm:ss`) or [relative](/manual/web_interface/time_period_selector) time syntax (`now`, `now/d`, `now/w-1w`, etc.).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"<br>- *required* if `columns.0.sparkline.time_period.to` is set|
|^|*To*|1|columns.0.sparkline.time_period.to|Valid time string in absolute (`YYYY-MM-DD hh:mm:ss`) or [relative](/manual/web_interface/time_period_selector) time syntax (`now`, `now/d`, `now/w-1w`, etc.).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"<br>- *required* if `columns.0.sparkline.time_period.from` is set|
|^|*History data*|0|columns.0.sparkline.history|0 - *(default)* Auto;<br>1 - History;<br>2 - Trends.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric" and *Display* is set to "Sparkline"|
|*Thresholds*|<|<|<|<|
|<|*Color*|1|columnsthresholds.0.color.0|Hexadecimal color code (e.g. `FF0000`).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric"|
|^|*Threshold*|1|columnsthresholds.0.threshold.0|Any string value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric"|
|*Highlights*|<|<|<|<|
|<|*Color*|1|columns.0.highlights.0.color|Hexadecimal color code (e.g. `FF0000`).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Text"|
|^|*Pattern*|1|columns.0.highlights.0.pattern|Any string value.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Text"|
|*Show thumbnail*|<|0|columns.0.show_thumbnail|0 - *(default)* Disabled;<br>1 - Enabled.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Binary"|
|*Aggregation function*|<|0|columns.0.aggregate_function|0 - *(default)* not used;<br>1 - min;<br>2 - max;<br>3 - avg;<br>4 - count;<br>5 - sum;<br>6 - first;<br>7 - last.|
|*Time period*|<|1|columns.0.time_period.\_reference|`DASHBOARD._timeperiod` - set the dashboard [time period selector](/manual/web_interface/time_period_selector) as the data source;<br>`ABCDE._timeperiod` - set a [compatible widget](/manual/web_interface/frontend_sections/dashboards/widgets#widget-compatibility) (with its `reference` parameter equal to `ABCDE`) as the data source.<br><br>Default: `DASHBOARD._timeperiod`<br><br>Alternatively, you can set the time period only in the *From* and *To* parameters.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Aggregation function* is set to "min", "max", "avg", "count", "sum", "first", "last"|
|<|*From*|1|columns.0.time_period.from|Valid time string in absolute (`YYYY-MM-DD hh:mm:ss`) or [relative](/manual/web_interface/time_period_selector) time syntax (`now`, `now/d`, `now/w-1w`, etc.).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Time period* is not set and *Aggregation function* is set to "min", "max", "avg", "count", "sum", "first", "last"<br>- *required* if `columns.0.time_period.to` is set|
|^|*To*|1|columns.0.time_period.to|Valid time string in absolute (`YYYY-MM-DD hh:mm:ss`) or [relative](/manual/web_interface/time_period_selector) time syntax (`now`, `now/d`, `now/w-1w`, etc.).<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Time period* is not set and *Aggregation function* is set to "min", "max", "avg", "count", "sum", "first", "last"<br>- *required* if `columns.0.time_period.from` is set|
|*History data*|<|0|columns.0.history|0 - *(default)* Auto;<br>1 - History;<br>2 - Trends.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *supported* if *Display item value as* is set to "Numeric"|
|*Reference*|<|1|reference|Any string value consisting of 5 characters (e.g., `ABCDE` or `JBPNL`). This value must be unique within the dashboard to which the widget belongs.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required*|

[comment]: # ({/02077e27-5843843c})

[comment]: # ({55d0acdb-18fd738d})
##### Text

The following parameters are supported if *Data* is set to "Text".

|Parameter|[type](/manual/api/reference/dashboard/object#dashboard-widget-field)|name|value|
|-----|-|-----|-------------------|
|*Text*|1|columns.0.text|Any string value, including macros.<br>Supported macros: {HOST.\*}, {INVENTORY.\*}.<br><br>[Parameter behavior](/manual/api/reference_commentary#parameter-behavior):<br>- *required* if *Data* is set to "Text"|

[comment]: # ({/55d0acdb-18fd738d})

[comment]: # ({e7eaa526-c274247c})
### Examples

The following examples aim to only describe the configuration of the dashboard widget field objects for the *Top hosts* widget.
For more information on configuring a dashboard, see [`dashboard.create`](/manual/api/reference/dashboard/create).

[comment]: # ({/e7eaa526-c274247c})

[comment]: # ({ec72cf7d-2e9b79c3})
#### Configuring a *Top hosts* widget

Configure a *Top hosts* widget that displays top hosts by CPU utilization in host group "4".
In addition, configure the following custom columns: "Host name", "CPU utilization in %", "1m avg", "5m avg", "15m avg", "Processes".

[Request](/manual/api#performing-requests):

```json
{
    "jsonrpc": "2.0",
    "method": "dashboard.create",
    "params": {
        "name": "My dashboard",
        "display_period": 30,
        "auto_start": 1,
        "pages": [
            {
                "widgets": [
                    {
                        "type": "tophosts",
                        "name": "Top hosts",
                        "x": 0,
                        "y": 0,
                        "width": 36,
                        "height": 5,
                        "view_mode": 0,
                        "fields": [
                            {
                                "type": 2,
                                "name": "groupids.0",
                                "value": 4
                            },
                            {
                                "type": 1,
                                "name": "columns.0.name",
                                "value": "Host"
                            },
                            {
                                "type": 0,
                                "name": "columns.0.data",
                                "value": 2
                            },
                            {
                                "type": 1,
                                "name": "columns.0.base_color",
                                "value": "FFFFFF"
                            },
                            {
                                "type": 1,
                                "name": "columns.1.name",
                                "value": "CPU utilization in %"
                            },
                            {
                                "type": 0,
                                "name": "columns.1.data",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "columns.1.base_color",
                                "value": "4CAF50"
                            },
                            {
                                "type": 1,
                                "name": "columns.1.item",
                                "value": "CPU utilization"
                            },
                            {
                                "type": 0,
                                "name": "columns.1.display",
                                "value": 3
                            },
                            {
                                "type": 1,
                                "name": "columns.1.min",
                                "value": "0"
                            },
                            {
                                "type": 1,
                                "name": "columns.1.max",
                                "value": "100"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.color.0",
                                "value": "FFFF00"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.threshold.0",
                                "value": "50"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.color.1",
                                "value": "FF8000"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.threshold.1",
                                "value": "80"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.color.2",
                                "value": "FF4000"
                            },
                            {
                                "type": 1,
                                "name": "columnsthresholds.1.threshold.2",
                                "value": "90"
                            },
                            {
                                "type": 1,
                                "name": "columns.2.name",
                                "value": "1m avg"
                            },
                            {
                                "type": 0,
                                "name": "columns.2.data",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "columns.2.base_color",
                                "value": "FFFFFF"
                            },
                            {
                                "type": 1,
                                "name": "columns.2.item",
                                "value": "Load average (1m avg)"
                            },
                            {
                                "type": 1,
                                "name": "columns.3.name",
                                "value": "5m avg"
                            },
                            {
                                "type": 0,
                                "name": "columns.3.data",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "columns.3.base_color",
                                "value": "FFFFFF"
                            },
                            {
                                "type": 1,
                                "name": "columns.3.item",
                                "value": "Load average (5m avg)"
                            },
                            {
                                "type": 1,
                                "name": "columns.4.name",
                                "value": "15m avg"
                            },
                            {
                                "type": 0,
                                "name": "columns.4.data",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "columns.4.base_color",
                                "value": "FFFFFF"
                            },
                            {
                                "type": 1,
                                "name": "columns.4.item",
                                "value": "Load average (15m avg)"
                            },
                            {
                                "type": 1,
                                "name": "columns.5.name",
                                "value": "Processes"
                            },
                            {
                                "type": 0,
                                "name": "columns.5.data",
                                "value": 1
                            },
                            {
                                "type": 1,
                                "name": "columns.5.base_color",
                                "value": "FFFFFF"
                            },
                            {
                                "type": 1,
                                "name": "columns.5.item",
                                "value": "Number of processes"
                            },
                            {
                                "type": 0,
                                "name": "columns.5.decimal_places",
                                "value": 0
                            },
                            {
                                "type": 0,
                                "name": "column",
                                "value": 1
                            }
                        ]
                    }
                ]
            }
        ],
        "userGroups": [
            {
                "usrgrpid": 7,
                "permission": 2
            }
        ],
        "users": [
            {
                "userid": 1,
                "permission": 3
            }
        ]
    },
    "id": 1
}
```

Response:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "dashboardids": [
            "3"
        ]
    },
    "id": 1
}
```

[comment]: # ({/ec72cf7d-2e9b79c3})

[comment]: # ({e9d30322-d8c32fe2})
### See also

-   [Dashboard widget field](/manual/api/reference/dashboard/object#dashboard-widget-field)
-   [`dashboard.create`](/manual/api/reference/dashboard/create)
-   [`dashboard.update`](/manual/api/reference/dashboard/update)

[comment]: # ({/e9d30322-d8c32fe2})