diff --git a/apps/emqx_prometheus/src/emqx_prometheus_api.erl b/apps/emqx_prometheus/src/emqx_prometheus_api.erl
index 47a5b0299..89bfa6e6a 100644
--- a/apps/emqx_prometheus/src/emqx_prometheus_api.erl
+++ b/apps/emqx_prometheus/src/emqx_prometheus_api.erl
@@ -126,6 +126,7 @@ security() ->
         false -> []
     end.
 
+%% erlfmt-ignore
 fields(mode) ->
     [
         {mode,
@@ -133,7 +134,21 @@ fields(mode) ->
                 hoconsc:enum(?PROM_DATA_MODES),
                 #{
                     default => node,
-                    desc => <<"Metrics format mode.">>,
+                    desc => <<"
+Metrics format mode.
+
+`node`:
+Return metrics from local node. And it is the default behaviour if `mode` not specified.
+
+`all_nodes_aggregated`:
+Return metrics for all nodes.
+And if possible, calculate the arithmetic sum or logical sum of the indicators of all nodes.
+
+`all_nodes_unaggregated`:
+Return metrics from all nodes, and the metrics are not aggregated.
+The node name will be included in the returned results to
+indicate that certain metrics were returned on a certain node.
+">>,
                     in => query,
                     required => false,
                     example => node