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

# List traces with cursor-based pagination



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/traces
openapi: 3.1.0
info:
  title: TruLayer API
  version: 0.1.0
  description: |
    Trace ingestion, evaluation, query, and feedback API for TruLayer AI.

    ### Authentication

    Two auth schemes coexist: SDK API keys (`Authorization: Bearer tl_...`)
    and Clerk session JWTs (dashboard). Routes marked "requires Clerk auth"
    in their summary are unreachable via API key.

    ### Roles (TRU-234)

    Dashboard requests carry one of three organization roles: `owner`,
    `member`, `viewer`. Endpoints enforce role allowlists, not rank
    comparisons. See `docs/security.md` for the full role-permission
    matrix.

    - **owner** — full control including billing, member management,
      destructive deletes on failure-rules/model-routes/webhooks/eval-rules,
      control-loop execution, and DLQ resolution.
    - **member** — read + write (ingest, feedback, evals, API keys,
      projects, failure-rules, model-routes, webhooks).
    - **viewer** — read-only dashboard access plus compliance read access
      to `/v1/audit-log` and `/v1/dlq`.
servers:
  - url: https://api.trulayer.ai
    description: Production
  - url: http://localhost:8080
    description: Local development
security:
  - BearerAuth: []
tags:
  - name: health
  - name: ingest
  - name: traces
  - name: metrics
  - name: feedback
  - name: evals
  - name: eval-rules
  - name: control
  - name: apikeys
  - name: model-routes
  - name: datasets
  - name: search
  - name: anomaly
  - name: webhooks
  - name: failure-rules
  - name: eval-runs
  - name: ci
  - name: otlp
  - name: billing
  - name: deprecations
  - name: audit
  - name: failures
  - name: projects
  - name: compliance
  - name: dsr
  - name: policies
  - name: members
paths:
  /v1/traces:
    get:
      tags:
        - traces
      summary: List traces with cursor-based pagination
      operationId: listTraces
      parameters:
        - name: project_id
          in: query
          schema:
            type: string
            format: uuid
        - name: model
          in: query
          schema:
            type: string
        - name: error
          in: query
          schema:
            type: boolean
        - name: failure_type
          in: query
          description: >-
            Filter traces with spans matching this failure type (e.g. timeout,
            rate_limit, invalid_response, context_length)
          schema:
            type: string
            enum:
              - timeout
              - rate_limit
              - invalid_response
              - context_length
        - name: from
          in: query
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          schema:
            type: string
            format: date-time
        - name: latency_min
          in: query
          description: >-
            Minimum trace latency in milliseconds (inclusive). Must be a
            non-negative integer.
          schema:
            type: integer
            minimum: 0
        - name: latency_max
          in: query
          description: >-
            Maximum trace latency in milliseconds (inclusive). Must be a
            non-negative integer and greater than or equal to latency_min when
            both are supplied.
          schema:
            type: integer
            minimum: 0
        - name: token_count_min
          in: query
          description: |
            Minimum total token count (prompt + completion, summed across
            spans) for the trace (inclusive). Must be a non-negative
            integer. Traces ingested before TRU-250 report
            `total_token_count = 0` and are therefore excluded by any
            non-zero minimum.
          schema:
            type: integer
            minimum: 0
        - name: token_count_max
          in: query
          description: |
            Maximum total token count for the trace (inclusive). Must be a
            non-negative integer and greater than or equal to
            `token_count_min` when both are supplied.
          schema:
            type: integer
            minimum: 0
        - name: tag_key
          in: query
          description: |
            Filter traces whose `tags` column contains the
            `tag_key` → `tag_value` pair (TRU-215). Must be supplied
            together with `tag_value`; providing only one side returns
            400 `error.tags_filter_incomplete`.
          schema:
            type: string
        - name: tag_value
          in: query
          description: |
            Filter value paired with `tag_key`. See `tag_key` for
            constraints.
          schema:
            type: string
        - name: cursor
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
      responses:
        '200':
          description: Trace list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    TraceListResponse:
      type: object
      required:
        - traces
        - has_more
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
        next_cursor:
          type: string
          nullable: true
        has_more:
          type: boolean
    Trace:
      type: object
      required:
        - id
        - project_id
        - error
        - tags
        - started_at
      properties:
        id:
          type: string
          format: uuid
        project_id:
          type: string
          format: uuid
        session_id:
          type: string
          nullable: true
        external_id:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        input:
          type: string
          nullable: true
        output:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        latency_ms:
          type: integer
          nullable: true
        cost:
          type: number
          nullable: true
        total_token_count:
          description: |
            Sum of prompt_tokens + completion_tokens across every span on
            the trace, computed at ingest time (TRU-250). Zero when no
            span reports token usage. Traces ingested before the column
            existed remain at zero until re-ingested. Queryable via
            `token_count_min` / `token_count_max` on `GET /v1/traces`.
          type: integer
          nullable: true
        prompt_tokens_total:
          description: >-
            Sum of prompt tokens across every span on the trace, computed at
            ingest time.
          type: integer
          nullable: true
        completion_tokens_total:
          description: >-
            Sum of completion tokens across every span on the trace, computed at
            ingest time.
          type: integer
          nullable: true
        error:
          type: string
          nullable: true
        tags:
          type: array
          items:
            type: string
        tag_map:
          description: |
            User-defined key→value tag map persisted to the dedicated
            `tags` column (TRU-215). Omitted when the trace has no
            tags. Pre-TRU-215 traces stay without this field until
            re-ingested.
          type: object
          additionalProperties:
            type: string
        metadata:
          type: object
          additionalProperties: true
        span_count:
          type: integer
        control_loop_depth:
          description: |
            Number of executed retry control_actions rows attached to this
            trace (TRU-362). Escalations are excluded from the count —
            once an attempt is auto-converted to `escalate`, it does not
            advance the depth. Omitted on the trace list response;
            populated only on the trace detail response.
          type: integer
          nullable: true
        spans:
          type: array
          items:
            $ref: '#/components/schemas/Span'
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
          nullable: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
    Span:
      type: object
      required:
        - id
        - created_at
        - tenant_id
        - trace_id
        - name
        - type
      properties:
        id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        tenant_id:
          type: string
          format: uuid
        trace_id:
          type: string
          format: uuid
        parent_span_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        type:
          description: |
            Span type. Matches the `type` JSON key produced by the query
            handler (model.Span.Type) and the SDK ingestion convention.
          type: string
          enum:
            - llm
            - tool
            - retrieval
            - other
            - default
        input:
          type: string
          nullable: true
        output:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        latency_ms:
          type: integer
          nullable: true
        cost:
          type: number
          nullable: true
        error:
          description: |
            Nullable error message string. Null when the span succeeded.
            Matches the `error` JSON key on model.Span (*string with
            omitempty); previously declared `boolean`, which was spec
            drift from before TRU-18.
          type: string
          nullable: true
        prompt_tokens:
          type: integer
          nullable: true
        completion_tokens:
          type: integer
          nullable: true
        metadata:
          type: object
          additionalProperties: true
        start_time:
          type: string
          format: date-time
          nullable: true
        end_time:
          type: string
          format: date-time
          nullable: true
        otel_trace_id:
          type: string
          nullable: true
        otel_span_id:
          type: string
          nullable: true
  responses:
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: SDK API key (`tl_...`) or Clerk session JWT

````