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

# Get trace span

> Retrieve one hydrated span.

> [!NOTE]
>
> **Guia relacionado**: Guia de Traces. Consulte o [guia de Traces](/docs/pt-BR/ai-studio/observability/traces.md) para um passo a passo com exemplos.


## OpenAPI

````yaml get /v3/traces/{trace_id}/spans/{span_id}
openapi: 3.1.0
info:
  title: Toqan Router API
  version: '2.0'
  description: Toqan Router API documentation
servers:
  - url: https://router.toqan.ai/eu
    description: Frankfurt (Europe)
  - url: https://router.toqan.ai/br
    description: São Paulo (Brazil)
security:
  - ApiKey: []
tags:
  - description: >-
      API keys authenticate programmatic access to the workspace. They expose
      opaque tokens, per-domain access grants, and budget and rate-limit
      constraints.
    name: API keys
  - name: Logs
    description: >-
      OpenTelemetry log query API. Search, filter, aggregate, and facet log
      records ingested via OTLP.
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: Telemetry
    description: >-
      Unified query envelope for traces, metrics, and logs. One request shape,
      one filter dialect, and one response shape per source, validated by a
      per-source registry.
  - name: Traces
    description: >-
      Query and inspect ingested trace data: search trace summaries, aggregate
      metrics, and read individual traces and their spans.
  - name: Views
    description: Saved filters and columns for workspace observability pages.
  - description: List models available through the AI Router.
    name: Models
  - name: Alerts
    description: >-
      Alerts evaluate a telemetry metric on a fixed interval and fire
      notifications through notifiers when the value breaches a threshold. Each
      breach opens a trigger that tracks the incident until the value recovers.
  - name: Annotation Queues
    description: Annotation queues collect spans for human review.
  - name: Budgets
    description: >-
      Budgets govern spend, token usage, and request rate across six scopes:
      workspace, project, identity, API key, provider, and model. Every
      applicable budget is enforced, and the most restrictive limit applies per
      dimension.
  - name: Files
    description: File upload and retrieval operations.
  - name: Guardrail Rules
    description: >-
      Guardrail Rules conditionally enforce evaluators and plugins for AI
      Gateway traffic. Rules may be scoped to a project or the whole workspace.
  - name: Identities
    description: >-
      Identities represent end users from your system for usage and engagement
      tracking.
  - name: Management keys
    description: >-
      Management keys are workspace-scoped credentials that authenticate
      programmatic access to workspace administration surfaces (API keys,
      budgets). Unlike project-scoped API keys, a management key always operates
      at the workspace level.
  - name: MCP Gateway
    description: >-
      Register upstream MCP servers, discover and sync their tools, and assemble
      gateways that expose a curated tool surface to MCP clients.
  - name: Model Catalog
    description: >-
      Browse the Toqan Router model catalog: every model Toqan Router offers,
      across every provider, with pricing, capabilities and benchmark data. List
      endpoints only return models that are not deprecated. This API is public,
      requires no authentication, and is rate limited to 120 requests per minute
      per IP. Responses carry a 5-minute cache-control max-age.
  - name: Monitors
    description: >-
      Monitors are custom observability dashboards for traces, runtime metrics,
      and logs. Each monitor holds widgets that chart one telemetry query. List
      the metrics, operations, and dimensions available to your workspace with
      `GET /v3/telemetry/capabilities`, or start from a preset with `GET
      /v2/monitors/presets`.
  - name: Notifiers
    description: Notifier destinations used to send delivery and workflow notifications.
  - name: Routing Rules
    description: >-
      Routing Rules conditionally select models and enforce request plugins for
      AI Gateway traffic. Rules are evaluated by ascending priority and may be
      scoped to a project or the whole workspace.
  - name: Threads
    description: Threads group related trace invocations and their aggregate usage
  - name: Smart Routers
    description: >-
      Create and manage workspace Smart Routers. A Smart Router selects a model
      from an eligible pool for each request according to a quality, balanced,
      or cost profile.
  - name: Responses
  - name: Embeddings
  - description: Beta. Run typed classification questions against a classify model.
    name: Classify
  - description: Beta. Run classification decisions with the classify contract.
    name: Decisions
  - description: >-
      Run large offline workloads as JSONL batches and download
      OpenAI-compatible result files.
    name: Batches
paths:
  /v3/traces/{trace_id}/spans/{span_id}:
    get:
      tags:
        - Traces
      summary: Get trace span
      description: Retrieve one hydrated span.
      operationId: TracesGetSpan
      parameters:
        - name: trace_id
          in: path
          description: 'Optional: queue items predating trace_id capture only have the span.'
          required: true
          schema:
            type: string
        - name: span_id
          in: path
          required: true
          schema:
            type: string
        - name: all_accessible_projects
          in: query
          description: Spans every project the caller belongs to instead of the active one.
          schema:
            type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTraceSpanResponse'
        '401':
          description: >-
            Authentication required. See
            https://router.toqan.ai/docs/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The resource does not exist. See
            https://router.toqan.ai/docs/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKey: []
components:
  schemas:
    GetTraceSpanResponse:
      type: object
      properties:
        span:
          $ref: '#/components/schemas/SpanDetail'
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        code:
          type: integer
          description: Numeric error code, when one is available.
        details:
          type: array
          items: {}
          description: Additional error details, when the service reports any.
      required:
        - message
    SpanDetail:
      type: object
      properties:
        summary:
          $ref: '#/components/schemas/SpanSummary'
        attributes:
          type: object
    SpanSummary:
      type: object
      properties:
        object:
          type: string
        trace_id:
          type: string
        span_id:
          type: string
        parent_span_id:
          type: string
        name:
          type: string
        type:
          type: string
        operation:
          type: string
        status:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        duration_ms:
          type: number
          format: double
        provider:
          type: string
        model:
          type: string
        usage:
          $ref: '#/components/schemas/TraceUsage'
        cost:
          $ref: '#/components/schemas/TraceCost'
        has_detail:
          type: boolean
        level:
          type: integer
          format: int32
        has_children:
          type: boolean
        trace_framework:
          type: string
          description: Framework that produced the trace, recorded on the root span.
        leading_span_type:
          type: string
          description: Span type assigned at ingest when the trace has one.
        guardrail_enabled:
          type: boolean
          description: Whether the span is an evaluator span running as a guardrail.
        finish_reasons:
          type: array
          items:
            type: string
          description: >-
            Why the span's generation stopped, for example stop, length or
            content_filter.
        rule_attributes:
          type: object
    TraceUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
          format: uint32
        completion_tokens:
          type: integer
          format: uint32
        total_tokens:
          type: integer
          format: uint32
        prompt_cached_tokens:
          type: integer
          format: uint32
        prompt_audio_tokens:
          type: integer
          format: uint32
        completion_reasoning_tokens:
          type: integer
          format: uint32
        completion_audio_tokens:
          type: integer
          format: uint32
        completion_accepted_prediction_tokens:
          type: integer
          format: uint32
        completion_rejected_prediction_tokens:
          type: integer
          format: uint32
        prompt_cache_creation_tokens:
          type: integer
          format: uint32
    TraceCost:
      type: object
      properties:
        input:
          type: number
          format: double
        output:
          type: number
          format: double
        cache_read:
          type: number
          format: double
        cache_write:
          type: number
          format: double
        reasoning:
          type: number
          format: double
        web_search:
          type: number
          format: double
        total:
          type: number
          format: double
        currency:
          type: string
        cached:
          type: number
          format: double
        audio_input:
          type: number
          format: double
        audio_output:
          type: number
          format: double
        accepted_prediction:
          type: number
          format: double
        rejected_prediction:
          type: number
          format: double
        billable:
          type: boolean
        pricing_tier:
          type: string
        threshold_exceeded:
          type: boolean
        integration_id:
          type: string
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.