> ## Documentation Index > Fetch the complete documentation index at: https://ancplua.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get apiv1traces spans > Get spans for a trace ## OpenAPI ````yaml /api-reference/openapi.yaml get /api/v1/traces/{traceId}/spans openapi: 3.0.0 info: title: QYL Observability API version: '2026-01-26' servers: - url: https://api.staging.qyl.dev description: QYL Staging API variables: {} - url: https://api.qyl.dev description: QYL Production API variables: {} security: [] tags: - name: Streaming - name: Traces - name: Logs - name: Metrics - name: Sessions - name: Errors - name: Deployments - name: Services - name: Health - name: Workspaces - name: Onboarding - name: Configurator - name: Issues - name: Workflows - name: Search - name: Alerts paths: /api/v1/traces/{traceId}/spans: get: tags: - Traces description: Get spans for a trace operationId: TracesApi_getSpans parameters: - name: traceId in: path required: true schema: $ref: '#/components/schemas/Qyl.Common.TraceId' - name: limit in: query required: false description: Page size schema: type: integer format: int32 minimum: 1 maximum: 1000 default: 100 explode: false - name: cursor in: query required: false description: Cursor schema: type: string explode: false responses: '200': description: The request has succeeded. content: application/json: schema: type: object required: - items - has_more properties: items: type: array items: $ref: '#/components/schemas/Qyl.Storage.SpanRecord' description: List of items in this page next_cursor: type: string description: Cursor for the next page (null if no more pages) prev_cursor: type: string description: Cursor for the previous page (null if first page) has_more: type: boolean description: Whether there are more items available description: Cursor-based paginated response wrapper '404': description: Resource not found (404) headers: X-Trace-Id: required: false description: Trace ID for correlation schema: type: string X-Request-Id: required: false description: Request ID for support schema: type: string content: application/json: schema: $ref: '#/components/schemas/Qyl.Common.Errors.NotFoundError' '500': description: Internal server error (500) headers: X-Trace-Id: required: false description: Trace ID for correlation schema: type: string X-Request-Id: required: false description: Request ID for support schema: type: string content: application/json: schema: $ref: '#/components/schemas/Qyl.Common.Errors.InternalServerError' components: schemas: Qyl.Common.TraceId: type: string minLength: 32 maxLength: 32 pattern: ^[a-f0-9]{32}$ description: Unique trace identifier (32 lowercase hex characters) example: 0af7651916cd43dd8448eb211c80319c x-csharp-type: TraceId x-csharp-struct: true x-duckdb-type: VARCHAR(32) Qyl.Storage.SpanRecord: type: object required: - spanId - traceId - name - kind - startTimeUnixNano - endTimeUnixNano - durationNs - statusCode properties: spanId: allOf: - $ref: '#/components/schemas/Qyl.Common.SpanId' description: Unique span identifier x-duckdb-primary-key: true x-duckdb-column: span_id traceId: allOf: - $ref: '#/components/schemas/Qyl.Common.TraceId' description: Trace identifier x-duckdb-index: idx_spans_trace_id x-duckdb-column: trace_id parentSpanId: allOf: - $ref: '#/components/schemas/Qyl.Common.SpanId' description: Parent span identifier (null for root spans) x-duckdb-column: parent_span_id sessionId: allOf: - $ref: '#/components/schemas/Qyl.Common.SessionId' description: Session identifier for grouping related traces x-promoted: true x-duckdb-index: idx_spans_session_id x-duckdb-column: session_id name: type: string minLength: 1 description: Human-readable span name x-duckdb-column: name kind: allOf: - $ref: '#/components/schemas/Qyl.OTel.Enums.SpanKind' description: Span kind x-duckdb-column: kind startTimeUnixNano: type: integer format: int64 description: Start timestamp in nanoseconds since epoch x-duckdb-index: idx_spans_start_time x-duckdb-column: start_time_unix_nano endTimeUnixNano: type: integer format: int64 description: End timestamp in nanoseconds since epoch x-duckdb-column: end_time_unix_nano durationNs: allOf: - $ref: '#/components/schemas/Qyl.Common.DurationNs' description: Duration in nanoseconds x-duckdb-column: duration_ns statusCode: allOf: - $ref: '#/components/schemas/Qyl.OTel.Enums.SpanStatusCode' description: Span status code x-duckdb-column: status_code statusMessage: type: string description: Status message (only for ERROR status) x-duckdb-column: status_message serviceName: type: string description: Service name from resource attributes x-promoted: true x-duckdb-index: idx_spans_service_name x-duckdb-column: service_name genAiProviderName: type: string description: >- GenAI provider name (e.g., openai, anthropic) - OTel 1.40: gen_ai.provider.name x-promoted: true x-duckdb-index: idx_spans_gen_ai_provider_name x-duckdb-column: gen_ai_provider_name genAiRequestModel: type: string description: Requested model name x-promoted: true x-duckdb-index: idx_spans_gen_ai_request_model x-duckdb-column: gen_ai_request_model genAiResponseModel: type: string description: Actual response model name x-promoted: true x-duckdb-column: gen_ai_response_model genAiInputTokens: allOf: - $ref: '#/components/schemas/Qyl.Common.TokenCount' description: Input/prompt tokens x-promoted: true x-duckdb-column: gen_ai_input_tokens genAiOutputTokens: allOf: - $ref: '#/components/schemas/Qyl.Common.TokenCount' description: Output/completion tokens x-promoted: true x-duckdb-column: gen_ai_output_tokens genAiTemperature: allOf: - $ref: '#/components/schemas/Qyl.Common.Temperature' description: Request temperature x-promoted: true x-duckdb-column: gen_ai_temperature genAiStopReason: type: string description: Response finish reason x-promoted: true x-duckdb-column: gen_ai_stop_reason genAiToolName: type: string description: Tool name for tool calls x-promoted: true x-duckdb-column: gen_ai_tool_name genAiToolCallId: type: string description: Tool call ID x-promoted: true x-duckdb-column: gen_ai_tool_call_id genAiCostUsd: allOf: - $ref: '#/components/schemas/Qyl.Common.CostUsd' description: Estimated cost in USD x-promoted: true x-duckdb-column: gen_ai_cost_usd attributesJson: type: string description: All span attributes as JSON x-duckdb-type: VARCHAR x-duckdb-column: attributes_json resourceJson: type: string description: Resource attributes as JSON x-duckdb-type: VARCHAR x-duckdb-column: resource_json baggageJson: type: string description: >- W3C Baggage key-value pairs as JSON for cross-cutting concern propagation x-duckdb-type: VARCHAR x-duckdb-column: baggage_json schemaUrl: type: string description: >- OTel semantic convention schema URL (e.g., https://opentelemetry.io/schemas/1.40.0) x-duckdb-type: VARCHAR(256) x-duckdb-column: schema_url createdAt: type: string format: date-time description: Row creation timestamp x-internal: true x-duckdb-type: TIMESTAMP DEFAULT now() x-duckdb-column: created_at description: OpenTelemetry span record for storage and query x-csharp-type: SpanRecord x-duckdb-table: spans Qyl.Common.Errors.NotFoundError: type: object required: - title properties: title: type: string enum: - Not Found resource_type: type: string description: The type of resource that was not found resource_id: type: string description: The identifier that was not found allOf: - $ref: '#/components/schemas/Qyl.Common.Errors.ProblemDetails' description: Resource not found (404) Qyl.Common.Errors.InternalServerError: type: object required: - title properties: title: type: string enum: - Internal Server Error error_code: type: string description: Error code for support reference allOf: - $ref: '#/components/schemas/Qyl.Common.Errors.ProblemDetails' description: Internal server error (500) Qyl.Common.SpanId: type: string minLength: 16 maxLength: 16 pattern: ^[a-f0-9]{16}$ description: Unique span identifier (16 lowercase hex characters) example: b7ad6b7169203331 x-csharp-type: SpanId x-csharp-struct: true x-duckdb-type: VARCHAR(16) Qyl.Common.SessionId: type: string minLength: 1 maxLength: 128 description: Unique session identifier x-csharp-type: SessionId x-csharp-struct: true x-duckdb-type: VARCHAR(128) Qyl.OTel.Enums.SpanKind: type: number enum: - 0 - 1 - 2 - 3 - 4 - 5 description: Span kind describing the relationship between spans Qyl.Common.DurationNs: type: integer format: int64 minimum: 0 description: Duration in nanoseconds x-csharp-type: long x-duckdb-type: UBIGINT Qyl.OTel.Enums.SpanStatusCode: type: number enum: - 0 - 1 - 2 description: Span status code Qyl.Common.TokenCount: type: integer format: int64 minimum: 0 description: Token count (for LLM operations) x-csharp-type: long x-duckdb-type: BIGINT Qyl.Common.Temperature: type: number format: double minimum: 0 maximum: 2 description: Temperature setting for LLM requests (0.0-2.0) x-csharp-type: double x-duckdb-type: DOUBLE Qyl.Common.CostUsd: type: number format: double minimum: 0 description: Cost in USD (floating point) x-csharp-type: double x-duckdb-type: DOUBLE Qyl.Common.Errors.ProblemDetails: type: object required: - type - title - status properties: type: type: string format: uri description: A URI reference identifying the problem type default: about:blank title: type: string description: A short, human-readable summary of the problem type status: type: integer format: int32 description: >- The HTTP status code (informational only, actual code set by subtype) detail: type: string description: A human-readable explanation specific to this occurrence instance: type: string format: uri description: A URI reference identifying the specific occurrence timestamp: type: string format: date-time description: Timestamp of the error description: RFC 7807 Problem Details for HTTP APIs ````