> ## Documentation Index
> Fetch the complete documentation index at: https://kb.vastdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query multiple metrics with aggregation

## OpenAPI

````json GET /metrics
{
  "openapi": "3.0.3",
  "info": {
    "title": "VAST DataEngine API",
    "description": "Combined OpenAPI specification for Document360: Provisioning, Telemetries Query, Telemetries Collector, and shared common components.",
    "version": "1.4.0"
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "Provisioning Service (Local development server)"
    },
    {
      "url": "http://localhost:8080/query_telemetries",
      "description": "Telemetries Query Service (Local development server)"
    },
    {
      "url": "http://localhost:8080/telemetries",
      "description": "Telemetries Collector Service (Local development server)"
    }
  ],
  "tags": [
    {
      "name": "Provisioning Service v1.4.0",
      "description": "Provisioning Service API"
    },
    {
      "name": "Provisioning Service v1.4.0 > dataEngine",
      "description": "Data Engine lifecycle"
    },
    {
      "name": "Provisioning Service v1.4.0 > setup_provisioning",
      "description": "Deprecated provisioning setup"
    },
    {
      "name": "Provisioning Service v1.4.0 > pipelines",
      "description": "Pipelines"
    },
    {
      "name": "Provisioning Service v1.4.0 > pipelineRevisions",
      "description": "Pipeline revisions"
    },
    {
      "name": "Provisioning Service v1.4.0 > functions",
      "description": "Functions"
    },
    {
      "name": "Provisioning Service v1.4.0 > functionRevisions",
      "description": "Function revisions"
    },
    {
      "name": "Provisioning Service v1.4.0 > functionRevisionsDeprecated",
      "description": "Deprecated function revision endpoints"
    },
    {
      "name": "Provisioning Service v1.4.0 > triggers",
      "description": "Triggers"
    },
    {
      "name": "Provisioning Service v1.4.0 > topics",
      "description": "Topics"
    },
    {
      "name": "Provisioning Service v1.4.0 > containerRegistries",
      "description": "Container registries"
    },
    {
      "name": "Provisioning Service v1.4.0 > kubernetesClusters",
      "description": "Kubernetes clusters"
    },
    {
      "name": "Provisioning Service v1.4.0 > kubernetesSecrets",
      "description": "Kubernetes secrets"
    },
    {
      "name": "Provisioning Service v1.4.0 > mtlsAuthenticationCredentials",
      "description": "mTLS authentication credentials"
    },
    {
      "name": "Provisioning Service v1.4.0 > dashboard",
      "description": "Dashboard"
    },
    {
      "name": "Provisioning Service v1.4.0 > reports",
      "description": "Saved reports"
    },
    {
      "name": "Telemetries Collector Service v1.4.0",
      "description": "API for collecting OTEL signals (traces, logs and metrics)"
    },
    {
      "name": "Telemetries Collector Service v1.4.0 > collect_telemetries",
      "description": "Collect OTEL signals"
    },
    {
      "name": "Telemetries Query Service v1.4.0",
      "description": "API for querying traces, logs and metrics"
    },
    {
      "name": "Telemetries Query Service v1.4.0 > query_telemetries",
      "description": "Query traces and logs"
    },
    {
      "name": "Telemetries Query Service v1.4.0 > metrics",
      "description": "Query metrics"
    },
    {
      "name": "Telemetries Query Service v1.4.0 > reports",
      "description": "Saved reports"
    }
  ],
  "paths": {
    "/metrics": {
      "get": {
        "summary": "Query multiple metrics with aggregation",
        "operationId": "query_metrics",
        "tags": [
          "Telemetries Query Service v1.4.0 > metrics"
        ],
        "parameters": [
          {
            "name": "metric_names",
            "in": "query",
            "required": "true",
            "schema": {
              "type": "string"
            },
            "description": "Comma-separated list of metric names (1-10 metrics, e.g. \"http_requests,memory_usage,dataengine.function.invocations\"). Allows alphanumeric characters, dots, colons, and underscores."
          },
          {
            "name": "aggregation",
            "in": "query",
            "required": "false",
            "schema": {
              "$ref": "#/components/schemas/Aggregation",
              "default": "avg"
            },
            "description": "Aggregation method (defaults to 'avg')"
          },
          {
            "name": "pipeline",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string"
            },
            "description": "Pipeline name filter (optional)"
          },
          {
            "name": "function",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string"
            },
            "description": "Function name filter (optional)"
          },
          {
            "name": "function_deployment",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string"
            },
            "description": "Function deployment name filter (optional)"
          },
          {
            "name": "metric_type",
            "in": "query",
            "required": "false",
            "schema": {
              "$ref": "#/components/schemas/MetricType"
            },
            "description": "Filter by metric type (optional)"
          },
          {
            "name": "group_by",
            "in": "query",
            "required": "false",
            "schema": {
              "$ref": "#/components/schemas/GroupBy"
            },
            "description": "Group metrics by dimension (function_name or pipeline_name)"
          },
          {
            "name": "top_k",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "integer",
              "minimum": "1",
              "maximum": "100"
            },
            "description": "Return only the top K groups with highest values (requires group_by, mutually exclusive with bottom_k)"
          },
          {
            "name": "bottom_k",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "integer",
              "minimum": "1",
              "maximum": "100"
            },
            "description": "Return only the bottom K groups with lowest values (requires group_by, mutually exclusive with top_k)"
          },
          {
            "name": "timeframe",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string"
            },
            "description": "Time window like '30s', '5m', '1h', '7d'. Defaults to '1h' if neither timeframe nor time_start/time_end are specified."
          },
          {
            "name": "time_start",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Start time for query"
          },
          {
            "name": "time_end",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "End time for query"
          },
          {
            "name": "max_points",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "integer",
              "minimum": "1",
              "maximum": "100",
              "default": "60"
            },
            "description": "Maximum data points to return"
          }
        ],
        "responses": {
          "200": {
            "description": "Multi-metric query result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MultiMetricQueryResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Aggregation": {
        "type": "string",
        "enum": [
          "sum",
          "avg",
          "min",
          "max",
          "p50",
          "p95",
          "p99"
        ],
        "description": "Aggregation method for metrics. Percentile aggregations (p50, p95, p99) are only valid for Histogram metrics."
      },
      "MetricType": {
        "type": "string",
        "enum": [
          "Counter",
          "Histogram",
          "Gauge",
          "UpDownCounter"
        ],
        "description": "Type of metric (Counter, Histogram, Gauge, UpDownCounter)"
      },
      "GroupBy": {
        "type": "string",
        "enum": [
          "function_name",
          "pipeline_name",
          "function_deployment_name"
        ],
        "description": "Dimension to group metrics by (function_name, pipeline_name, or function_deployment_name)"
      },
      "MultiMetricQueryResponse": {
        "type": "object",
        "required": [
          "query",
          "results"
        ],
        "properties": {
          "query": {
            "type": "object",
            "required": [
              "metric_names",
              "aggregation",
              "time_range",
              "bucket_size_seconds"
            ],
            "properties": {
              "metric_names": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Metrics that were queried"
              },
              "aggregation": {
                "type": "string",
                "description": "Aggregation method used"
              },
              "time_range": {
                "type": "object",
                "required": [
                  "start",
                  "end"
                ],
                "properties": {
                  "start": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Query start time"
                  },
                  "end": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Query end time"
                  }
                }
              },
              "bucket_size_seconds": {
                "type": "integer",
                "description": "Size of time buckets in seconds"
              },
              "filters": {
                "type": "object",
                "properties": {
                  "pipeline": {
                    "type": "string",
                    "description": "Pipeline filter applied"
                  },
                  "function": {
                    "type": "string",
                    "description": "Function filter applied"
                  },
                  "function_deployment": {
                    "type": "string",
                    "description": "Function deployment name filter applied"
                  },
                  "metric_type": {
                    "type": "string",
                    "description": "Metric type filter applied"
                  },
                  "group_by": {
                    "$ref": "#/components/schemas/GroupBy",
                    "description": "Grouping dimension applied"
                  },
                  "top_k": {
                    "type": "integer",
                    "description": "Top K groups filter applied (highest values)"
                  },
                  "bottom_k": {
                    "type": "integer",
                    "description": "Bottom K groups filter applied (lowest values)"
                  }
                },
                "description": "Optional filters that were applied"
              }
            }
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "metric_name",
                "metric_type",
                "groups"
              ],
              "properties": {
                "metric_name": {
                  "type": "string",
                  "description": "Name of the metric"
                },
                "metric_type": {
                  "type": "string",
                  "description": "Type of metric (Counter, Gauge, etc.)"
                },
                "metric_unit": {
                  "type": "string",
                  "description": "Unit of the metric (ms, bytes, percent, etc.)"
                },
                "metric_description": {
                  "type": "string",
                  "description": "Human-readable description of the metric"
                },
                "scope": {
                  "type": "string",
                  "description": "OpenTelemetry scope name (e.g., \"vast-runtime\" for automatic metrics, \"user\" for custom metrics)"
                },
                "groups_found": {
                  "type": "array",
                  "nullable": "true",
                  "items": {
                    "type": "string"
                  },
                  "description": "List of unique group values found (only present when group_by is used)"
                },
                "groups": {
                  "type": "array",
                  "description": "Array of grouped metric data. Contains one or more groups depending on query grouping.",
                  "items": {
                    "type": "object",
                    "required": [
                      "statistics",
                      "prop_list",
                      "data"
                    ],
                    "properties": {
                      "group": {
                        "type": "string",
                        "nullable": "true",
                        "description": "The value of the grouping dimension for this group (only present when group_by is used)"
                      },
                      "statistics": {
                        "type": "object",
                        "required": [
                          "total_points",
                          "raw_points_count"
                        ],
                        "properties": {
                          "total_points": {
                            "type": "integer",
                            "description": "Number of aggregated data points for this metric"
                          },
                          "raw_points_count": {
                            "type": "integer",
                            "description": "Number of raw metric points before aggregation for this metric"
                          }
                        }
                      },
                      "prop_list": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Column names for data array",
                        "example": [
                          "timestamp",
                          "value",
                          "count"
                        ]
                      },
                      "data": {
                        "type": "array",
                        "items": {
                          "type": "array",
                          "items": {}
                        },
                        "description": "Data rows in prop_list column order"
                      }
                    }
                  }
                }
              }
            },
            "description": "Per-metric results array"
          }
        }
      },
      "ValidationErrorResponse": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string",
            "description": "String representation of a mapping between field names and error messages",
            "example": "{\"url\": \"URL must include a protocol\", \"port\": \"Port must be an integer\"}"
          }
        }
      }
    },
    "responses": {
      "ValidationError": {
        "description": "Validation Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationErrorResponse"
            }
          }
        }
      }
    }
  }
}
````