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

> Retrieves spans from DB based on the specified filters.

## OpenAPI

````json GET /traces
{
  "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": {
    "/traces": {
      "get": {
        "parameters": [
          {
            "$ref": "#/components/parameters/Cursor"
          },
          {
            "$ref": "#/components/parameters/Limit"
          },
          {
            "$ref": "#/components/parameters/StartTimeBefore"
          },
          {
            "$ref": "#/components/parameters/StartTimeAfter"
          },
          {
            "$ref": "#/components/parameters/PipelineId"
          },
          {
            "$ref": "#/components/parameters/PipelineName"
          },
          {
            "$ref": "#/components/parameters/PipelineVRN"
          },
          {
            "$ref": "#/components/parameters/TraceId"
          },
          {
            "name": "event_id",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "description": "ID of the CloudEvent compatible event triggering the Trace/Span"
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "description": "Type of the CloudEvent compatible event triggering the Trace/Span"
            }
          },
          {
            "name": "event_source",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "description": "Source of the CloudEvent compatible event triggering the Trace/Span"
            }
          },
          {
            "name": "trace_type",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "string",
              "description": "Type of trace to filter by (init, batch, event). Supports comma-separated values for multiple types (e.g., \"init,batch\")"
            }
          },
          {
            "name": "include_deleted",
            "in": "query",
            "required": "false",
            "schema": {
              "type": "boolean",
              "default": "true"
            },
            "description": "Include deleted pipelines in the results"
          },
          {
            "$ref": "#/components/parameters/OrderBy"
          },
          {
            "$ref": "#/components/parameters/ShowDeprecated"
          }
        ],
        "summary": "Query traces",
        "description": "Retrieves spans from DB based on the specified filters.",
        "operationId": "query_traces",
        "tags": [
          "Telemetries Query Service v1.4.0 > query_telemetries"
        ],
        "responses": {
          "200": {
            "description": "A list of Traces",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "pagination": {
                      "$ref": "#/components/schemas/Pagination"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/TraceResult"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Cursor": {
        "name": "cursor",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": "false",
        "schema": {
          "default": "100",
          "type": "integer"
        }
      },
      "StartTimeBefore": {
        "name": "start_time_before",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "integer",
          "format": "int64",
          "description": "Timestamp since epoch for which traces should start before (inclusive)"
        }
      },
      "StartTimeAfter": {
        "name": "start_time_after",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "integer",
          "format": "int64",
          "description": "Timestamp since epoch for which traces should start after (exclusive)"
        }
      },
      "PipelineId": {
        "name": "pipeline_id",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string",
          "description": "Pipeline ID associated with returned telemetries"
        }
      },
      "PipelineName": {
        "name": "pipeline_name",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string",
          "description": "Full name or regex pattern of the Pipeline"
        }
      },
      "PipelineVRN": {
        "name": "pipeline_vrn",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string",
          "description": "The pipeline's VRN"
        }
      },
      "TraceId": {
        "name": "trace_id",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string",
          "description": "ID of the Trace assoicated with the telemetries"
        }
      },
      "OrderBy": {
        "name": "order_by",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "default": "asc"
        },
        "description": "Sort order - ascending (asc) or descending (desc)"
      },
      "ShowDeprecated": {
        "name": "show_deprecated",
        "in": "query",
        "required": "false",
        "schema": {
          "type": "boolean"
        },
        "description": "Controls whether deprecated 5.4 (pre-aggregator) traces are merged into the results. When true, include results from the deprecated path in addition to the new aggregated path; when false, skip it. When omitted, the tenant global-config default (telemetries.traces.show_deprecated) is used. If the AggregatedTraces table has no rows, the deprecated path is queried regardless of this flag."
      }
    },
    "schemas": {
      "Pagination": {
        "allOf": [
          {
            "type": "object",
            "properties": {
              "next_cursor": {
                "type": "string",
                "description": "The cursor for the next page"
              },
              "previous_cursor": {
                "type": "string",
                "description": "The cursor for the last page"
              }
            }
          }
        ]
      },
      "TraceResult": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Trace"
          },
          {
            "type": "object",
            "properties": {
              "event": {
                "$ref": "#/components/schemas/Event"
              }
            }
          }
        ]
      },
      "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"
              }
            }
          }
        ]
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      },
      "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"
          }
        }
      }
    }
  }
}
````