> ## 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 tree of spans

> Retrieves tree of all the spans under specific trace id.

## OpenAPI

````json GET /trace-tree
{
  "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": {
    "/trace-tree": {
      "get": {
        "parameters": [
          {
            "name": "trace_id",
            "in": "query",
            "required": "true",
            "schema": {
              "type": "string"
            }
          }
        ],
        "summary": "Query tree of spans",
        "description": "Retrieves tree of all the spans under specific trace id.",
        "operationId": "query_trace_tree",
        "tags": [
          "Telemetries Query Service v1.4.0 > query_telemetries"
        ],
        "responses": {
          "200": {
            "description": "A tree of spans under the trace",
            "content": {
              "application/json": {
                "schema": {
                  "required": [
                    "tree"
                  ],
                  "type": "object",
                  "properties": {
                    "root_trace": {
                      "$ref": "#/components/schemas/RootTraceResult"
                    },
                    "functions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SpansTree"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "The trace id doesn't exist"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RootTraceResult": {
        "description": "Extended TraceResult used as root_trace in the trace-tree response. Inherits from RootTrace so that linked_from and links_to are arrays of full Trace objects (not just IDs), giving the caller all necessary context about related traces in a single response.\n",
        "allOf": [
          {
            "$ref": "#/components/schemas/RootTrace"
          },
          {
            "type": "object",
            "properties": {
              "event": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        ]
      },
      "SpansTree": {
        "type": "object",
        "required": [
          "value",
          "children"
        ],
        "properties": {
          "value": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SpanResult"
              }
            ]
          },
          "children": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SpansTree"
            }
          }
        }
      },
      "RootTrace": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseTrace"
          },
          {
            "type": "object",
            "description": "Extended trace returned as root_trace in the trace-tree response. The linked_from and links_to arrays contain full Trace objects (not just IDs) so that the caller can display name, timing, and status of related traces without a secondary lookup. The items are BaseTrace objects (not RootTrace) to avoid recursive nesting.\n",
            "properties": {
              "linked_from": {
                "type": "array",
                "nullable": "true",
                "items": {
                  "$ref": "#/components/schemas/Trace"
                },
                "description": "Full Trace objects for each trace that links TO this trace (reverse direction of links_to). For event traces, these are the batch traces created from this event.\n"
              },
              "links_to": {
                "type": "array",
                "nullable": "true",
                "items": {
                  "$ref": "#/components/schemas/Trace"
                },
                "description": "Full Trace objects for the traces this trace links TO. For batch traces, these are the event traces that originated this batch.\n"
              }
            }
          }
        ]
      },
      "Event": {
        "type": "object",
        "description": "CloudEvent compatible event that triggered the Pipeline or Function",
        "properties": {
          "event_id": {
            "type": "string",
            "description": "ID of the event",
            "x-otel-loc": "event.id"
          },
          "event_type": {
            "type": "string",
            "description": "Type of the event",
            "x-otel-loc": "event.type"
          },
          "event_source": {
            "type": "string",
            "description": "Source of the event",
            "x-otel-loc": "event.source"
          },
          "event_subject": {
            "type": "string",
            "description": "Name of the Kafka Topic where the event was consumed",
            "x-otel-loc": "event.subject"
          }
        }
      },
      "SpanResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Span"
          },
          {
            "type": "object",
            "properties": {
              "attributes": {
                "type": "object",
                "description": "Mapping of addition attributes stored on the"
              },
              "resource": {
                "$ref": "#/components/schemas/TelemetryResource"
              },
              "event": {
                "$ref": "#/components/schemas/Event"
              },
              "error": {
                "$ref": "#/components/schemas/Error"
              }
            }
          }
        ]
      },
      "BaseTrace": {
        "type": "object",
        "description": "Base trace fields shared by all trace representations",
        "properties": {
          "trace_id": {
            "type": "string",
            "description": "ID of the Trace"
          },
          "start_time": {
            "type": "integer",
            "format": "int64",
            "description": "Start time of the Trace since epoch in micro sec"
          },
          "end_time": {
            "type": "integer",
            "format": "int64",
            "description": "End time of the Trace since epoch in micro sec"
          },
          "status": {
            "type": "string",
            "description": "Status of the Trace"
          },
          "trace_type": {
            "type": "string",
            "nullable": "true",
            "description": "Type of trace (init, batch, or event)"
          },
          "event": {
            "$ref": "#/components/schemas/Event",
            "description": "Event that triggered the Trace"
          },
          "resource": {
            "$ref": "#/components/schemas/TelemetryResource",
            "description": "Resource that produced the telemetry, as in OTEL specification"
          }
        }
      },
      "Trace": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseTrace"
          },
          {
            "type": "object",
            "description": "Trace with string-only link references (used in list endpoints and as linked-trace items)",
            "properties": {
              "linked_from": {
                "type": "array",
                "nullable": "true",
                "items": {
                  "type": "string"
                },
                "description": "a reverse direction of the \"links_to\" field of adjacent trace. For event traces, this contains the batch trace IDs that WERE CREATED FROM this event (i.e. event→batch links resolved via the AggregatedTracesLinks table).\n"
              },
              "links_to": {
                "type": "array",
                "nullable": "true",
                "items": {
                  "type": "string"
                },
                "description": "Trace IDs that this trace links TO. For batch traces, this contains the event trace IDs that ORIGINATED this batch and were processed as part of the batch execution (i.e. batch→event forward references written at aggregation time).\n"
              }
            }
          }
        ]
      },
      "Span": {
        "type": "object",
        "description": "Span building block showing an operation, i.e. Function execution",
        "properties": {
          "trace_id": {
            "type": "string",
            "description": "ID of the Trace this Span is associated with"
          },
          "span_id": {
            "type": "string",
            "description": "ID of the Span"
          },
          "parent_span_id": {
            "type": "string",
            "nullable": "true",
            "description": "ID of the parent Span. Empty if this is the root Span"
          },
          "start_time": {
            "type": "integer",
            "format": "int64",
            "description": "Start time of the Span since epoch in micro sec"
          },
          "end_time": {
            "type": "integer",
            "format": "int64",
            "description": "End time of the Span since epoch in micro sec"
          },
          "span_name": {
            "type": "string",
            "description": "Name of the Span (i.e. function name, request URL)"
          },
          "span_status": {
            "type": "string"
          },
          "scope": {
            "type": "string",
            "nullable": "true"
          },
          "attributes": {
            "type": "string",
            "description": "Mapping of addition attributes stored on the"
          },
          "links": {
            "type": "array",
            "nullable": "true",
            "items": {
              "type": "string"
            },
            "description": "OTEL Span links — the canonical OpenTelemetry `Span.links` field (see https://opentelemetry.io/docs/specs/otel/trace/api/#specifying-links). Carries trace IDs this span is causally linked to across trace boundaries. In our pipeline this is the INPUT signal: a batch span emits one OTEL Link per processed event (set by the runtime via `tracer.start_as_current_span(links=...)`), collected as-is by the telemetries-collector, and consumed by the traces-aggregator to deduce `trace_type=Batch` and to populate the `AggregatedTracesLinks` table (batch→event forward references). NOTE: this is distinct from any aggregated `links_to`/`linked_from` fields on Trace, which are derived from this OTEL signal at aggregation time.\n"
          },
          "span_type": {
            "nullable": "true",
            "type": "string",
            "description": "Type of the span (e.g. 'event', 'batch', 'init')"
          },
          "attached_trace_id": {
            "nullable": "true",
            "type": "string",
            "description": "Trace ID this span is attached to for filtering purposes"
          }
        }
      },
      "TelemetryResource": {
        "type": "object",
        "description": "Resource producing the telemetry, as in OTEL specification",
        "properties": {
          "tenant_id": {
            "type": "string",
            "description": "ID of the tenant",
            "example": "tenant.id",
            "x-otel-loc": "tenant.id"
          },
          "pipeline_id": {
            "type": "string",
            "description": "ID of the Pipeline",
            "example": "vastpipeline.id",
            "x-otel-loc": "vastpipeline.id"
          },
          "pipeline_name": {
            "type": "string",
            "description": "Name of the Pipeline",
            "x-otel-loc": "vastpipeline.name"
          },
          "pipeline_version": {
            "type": "string",
            "description": "Version of the Pipeline",
            "x-otel-loc": "vastpipeline.version"
          },
          "pipeline_revision_id": {
            "type": "string",
            "description": "ID of the Pipeline Revision",
            "x-otel-loc": "vastpipeline.rev_id"
          },
          "function_revision_id": {
            "type": "string",
            "description": "ID of the Function Revision",
            "x-otel-loc": "vastfunction.rev_id"
          },
          "pipeline_vrn": {
            "type": "string",
            "description": "VRN of the Pipeline"
          },
          "function_id": {
            "type": "string",
            "description": "ID of the Function",
            "x-otel-loc": "vastfunction.id"
          },
          "function_name": {
            "type": "string",
            "description": "Name of the Function",
            "x-otel-loc": "vastfunction.name"
          },
          "function_deployment_name": {
            "type": "string",
            "description": "Name of the Function Deployment as in Pipeline manifest",
            "x-otel-loc": "vastfunction.deployment_name"
          },
          "function_vrn": {
            "type": "string",
            "description": "VRN of the Function"
          },
          "function_version": {
            "type": "string",
            "description": "Version of the Function",
            "x-otel-loc": "vastfunction.version"
          },
          "function_host": {
            "type": "string",
            "description": "Name of the pod where the function is running",
            "x-otel-loc": "vastfunction.host"
          },
          "function_deployment_vrn": {
            "type": "string",
            "description": "VRN of the Function Deployment (i.e. the function used in the pipeline manifest)"
          },
          "sdk_version": {
            "type": "string",
            "description": "Serverless SDK installed in the user code",
            "x-otel-loc": "vastfunction.sdk_version"
          },
          "runtime_version": {
            "type": "string",
            "description": "Serverless runtime invoking user code",
            "x-otel-loc": "vastfunction.runtime_version"
          },
          "owner_vid": {
            "type": "integer",
            "format": "int64",
            "description": "The owner's vid associated with with the telemetry - the relevant pipeline owner",
            "x-otel-loc": "vastpipeline.owner_vid"
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Error that occurred during the Trace/Span",
        "properties": {
          "error_escaped": {
            "type": "boolean",
            "nullable": "true",
            "description": "Whether the error was thrown or not",
            "x-otel-loc": "exception.escaped"
          },
          "error_type": {
            "type": "string",
            "nullable": "true",
            "description": "Type of the error (Exception class in Python)",
            "x-otel-loc": "exception.type"
          },
          "error_message": {
            "type": "string",
            "nullable": "true",
            "description": "Message describing the error",
            "x-otel-loc": "exception.message"
          },
          "error_stacktrace": {
            "type": "string",
            "nullable": "true",
            "description": "Shows the stack of frames leading to the error",
            "x-otel-loc": "exception.stacktrace"
          }
        }
      }
    }
  }
}
````