# TOPK.LIST

> Return the items in a Top-K list, most frequent first, optionally with their counts.

URL: https://docs.hotkv.com/commands/topk-list/

```
TOPK.LIST key [WITHCOUNT]
```

- Group: Top-K
- Complexity: O(k log k), k being the list size
- HotKV Cloud: all plans
- On-Premise: no license needed

`TOPK.LIST` returns the items currently kept by the Top-K at `key`, ordered
by estimated count, highest first.

## Options

| Option | Effect |
| --- | --- |
| `WITHCOUNT` | Follow each item with its estimated count. |

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Default | Array of items (bulk strings) | Same |
| `WITHCOUNT` | Flat array: item, count, item, count, ... | Same |

The list holds fewer than `topk` items until enough distinct items were
seen.

Error replies: `TopK: key does not exist`, `WITHCOUNT keyword expected` for
any other option, and `WRONGTYPE`.

## Examples

```
127.0.0.1:6379> TOPK.RESERVE trending 3 50 4 0.9
OK
127.0.0.1:6379> TOPK.INCRBY trending hotkv 10 redis 4
1) (nil)
2) (nil)
127.0.0.1:6379> TOPK.LIST trending
1) "hotkv"
2) "redis"
127.0.0.1:6379> TOPK.LIST trending WITHCOUNT
1) "hotkv"
2) (integer) 10
3) "redis"
4) (integer) 4
```

## Compatibility

Same as `TOPK.LIST` in RedisBloom.

## See also

[TOPK.QUERY](https://docs.hotkv.com/commands/topk-query/index.md), [TOPK.COUNT](https://docs.hotkv.com/commands/topk-count/index.md), [TOPK.ADD](https://docs.hotkv.com/commands/topk-add/index.md)