> ## 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.

# Execute a report

> Execute a saved report and return metrics data based on the report's configuration.
The report's execution statistics (last_executed_at, execution_count) are automatically updated.

Optional config_override allows overriding specific parameters for this execution only.
If time_start and time_end are provided in the override, the saved timeframe is ignored.


## OpenAPI

````json POST /reports/{report_id}/execute
{
  "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": {
    "/reports/{report_id}/execute": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ReportId"
        }
      ],
      "post": {
        "tags": [
          "Telemetries Query Service v1.4.0 > reports"
        ],
        "summary": "Execute a report",
        "description": "Execute a saved report and return metrics data based on the report's configuration.\nThe report's execution statistics (last_executed_at, execution_count) are automatically updated.\n\nOptional config_override allows overriding specific parameters for this execution only.\nIf time_start and time_end are provided in the override, the saved timeframe is ignored.\n",
        "operationId": "execute_report",
        "requestBody": {
          "required": "false",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReportExecuteOverride"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Report executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportExecutionResponse"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "422": {
            "$ref": "#/components/responses/ValidationError"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ReportId": {
        "name": "report_id",
        "in": "path",
        "required": "true",
        "description": "Unique identifier of the report",
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "ReportExecuteOverride": {
        "type": "object",
        "additionalProperties": "false",
        "description": "Optional overrides for report execution. All fields are optional.",
        "properties": {
          "time_start": {
            "type": "string",
            "format": "date-time",
            "description": "Override start time (ISO 8601 format). If provided with time_end, ignores saved timeframe."
          },
          "time_end": {
            "type": "string",
            "format": "date-time",
            "description": "Override end time (ISO 8601 format). If provided with time_start, ignores saved timeframe."
          }
        }
      },
      "ReportExecutionResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/MultiMetricQueryResponse"
          },
          {
            "type": "object",
            "required": [
              "report_id",
              "report_name",
              "execution_time"
            ],
            "properties": {
              "report_id": {
                "type": "string",
                "format": "uuid",
                "description": "ID of the executed report"
              },
              "report_name": {
                "type": "string",
                "description": "Name of the executed report"
              },
              "display_config": {
                "type": "object",
                "description": "Display configuration for visualizing the report (chart type, colors, axes, etc.)"
              },
              "execution_time": {
                "type": "string",
                "format": "date-time",
                "description": "When the report was executed (ISO 8601 format)"
              }
            }
          }
        ]
      },
      "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"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "detail": {
            "type": "string"
          },
          "source": {
            "$ref": "#/components/schemas/ErrorSource"
          },
          "code": {
            "type": "string",
            "description": "Optional machine-readable error code for clients to branch on instead of parsing `detail`."
          }
        }
      },
      "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\"}"
          }
        }
      },
      "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)"
      },
      "ErrorSource": {
        "type": "object",
        "description": "Represents the underlying problem that made Data Engine raise the error",
        "properties": {
          "source_type": {
            "type": "string",
            "description": "The component where the error happened",
            "example": "kubernetes | vms | vdb | registry"
          },
          "source_name": {
            "type": "string",
            "description": "The name of the source compoenent",
            "example": "my-cluster"
          },
          "inner_error": {
            "type": "string",
            "description": "The error message from the source component",
            "example": "Failed to connect to the cluster"
          }
        }
      }
    },
    "responses": {
      "NotFoundError": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "ValidationError": {
        "description": "Validation Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationErrorResponse"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}
````