openapi: 3.1.0
info:
  title: LangWatch Agents Traces API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
- url: https://app.langwatch.ai
security:
- project_api_key: []
tags:
- name: Traces
paths:
  /api/trace/search:
    post:
      summary: Search traces
      description: Search for traces based on given criteria
      tags:
      - Traces
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
  /api/traces/search:
    post:
      responses:
        '200':
          description: Matching traces with pagination
          content:
            application/json:
              schema:
                type: object
                properties:
                  traces:
                    type: array
                    items: {}
                  pagination:
                    type: object
                    properties:
                      totalHits:
                        type: number
                      scrollId:
                        type: string
                    required:
                    - totalHits
                required:
                - traces
                - pagination
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
      operationId: postApiTracesSearch
      parameters: []
      description: Search traces for a project
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                filters:
                  type: object
                  properties:
                    topics.topics:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    topics.subtopics:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.user_id:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.thread_id:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.customer_id:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.labels:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.key:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.value:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    metadata.prompt_ids:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    traces.origin:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    traces.error:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    traces.name:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    spans.type:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    spans.model:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.evaluator_id:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.evaluator_id.guardrails_only:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.evaluator_id.has_passed:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.evaluator_id.has_score:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.evaluator_id.has_label:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.passed:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.score:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.state:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    evaluations.label:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    events.event_type:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    events.metrics.key:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    events.metrics.value:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    events.event_details.key:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                    annotations.hasAnnotation:
                      anyOf:
                      - type: array
                        items:
                          type: string
                      - type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      - type: object
                        additionalProperties:
                          type: object
                          additionalProperties:
                            type: array
                            items:
                              type: string
                  additionalProperties: false
                  default: {}
                traceIds:
                  type: array
                  items:
                    type: string
                negateFilters:
                  type: boolean
                pageOffset:
                  type: number
                pageSize:
                  type: number
                groupBy:
                  type: string
                sortBy:
                  type: string
                sortDirection:
                  type: string
                updatedAt:
                  type: number
                scrollId:
                  type:
                  - string
                  - 'null'
                startDate:
                  anyOf:
                  - type: number
                  - type: string
                endDate:
                  anyOf:
                  - type: number
                  - type: string
                format:
                  type: string
                  enum:
                  - digest
                  - json
                  description: 'Output format: ''digest'' (AI-readable trace digest) or ''json'' (full raw data)'
                includeSpans:
                  type: boolean
                  description: When true, fetches full span data for each trace. Useful for bulk export. Default false.
                llmMode:
                  type: boolean
              required:
              - startDate
              - endDate
      tags:
      - Traces
  /api/traces/{traceId}:
    get:
      responses:
        '200':
          description: Trace detail with spans, evaluations, and ASCII tree
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '404':
          description: Trace not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                - message
        '409':
          description: Ambiguous trace ID prefix — the prefix matches more than one trace
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  candidateTraceIds:
                    type: array
                    items:
                      type: string
                required:
                - message
                - candidateTraceIds
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
      operationId: getApiTracesByTraceId
      parameters:
      - name: traceId
        in: path
        description: The trace ID — either the full 32-char ID or a unique prefix (≥ 8 chars). Prefix lookup is scoped to the authenticated project.
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: 'Output format: ''digest'' (default, AI-readable) or ''json'' (full raw data)'
        required: false
        schema:
          type: string
          enum:
          - digest
          - json
      - name: llmMode
        in: query
        description: 'Deprecated: use format=digest instead'
        required: false
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
          - '1'
          - '0'
      description: Get a single trace by ID.
      tags:
      - Traces
components:
  schemas:
    EvaluationTimestamps:
      type: object
      properties:
        finished_at:
          type: integer
        updated_at:
          type: integer
    Metadata:
      type: object
      properties:
        sdk_language:
          type: string
        sdk_version:
          type: string
    Output:
      type: object
      properties:
        value:
          type: string
    Metrics:
      type: object
      properties:
        tokens_estimated:
          type: boolean
        completion_tokens:
          type: integer
        prompt_tokens:
          type: integer
        total_cost:
          type: number
        total_time_ms:
          type: integer
        first_token_ms:
          type: integer
          nullable: true
    Trace:
      type: object
      properties:
        trace_id:
          type: string
        project_id:
          type: string
        timestamps:
          $ref: '#/components/schemas/Timestamps'
        input:
          $ref: '#/components/schemas/Input'
        output:
          $ref: '#/components/schemas/Output'
        metadata:
          $ref: '#/components/schemas/Metadata'
        metrics:
          $ref: '#/components/schemas/Metrics'
        indexing_md5s:
          type: array
          items:
            type: string
        error:
          type: string
          nullable: true
        evaluations:
          type: array
          items:
            $ref: '#/components/schemas/Evaluation'
        contexts:
          type: array
          items: {}
    Timestamps:
      type: object
      properties:
        inserted_at:
          type: integer
        started_at:
          type: integer
        updated_at:
          type: integer
    SearchResponse:
      type: object
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Input:
      type: object
      properties:
        value:
          type: string
    SearchRequest:
      type: object
      properties:
        query:
          type: string
        startDate:
          type: string
          format: date-time
        endDate:
          type: string
          format: date-time
        pageSize:
          type: integer
          example: 1000
        scrollId:
          type: string
          example: '123'
        filters:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    Evaluation:
      type: object
      properties:
        evaluation_id:
          type: string
        score:
          type: number
        timestamps:
          $ref: '#/components/schemas/EvaluationTimestamps'
        evaluator_id:
          type: string
        name:
          type: string
        details:
          type: string
        passed:
          type: boolean
        label:
          type: string
          nullable: true
        type:
          type: string
        status:
          type: string
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: 'Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI.'
    admin_api_key:
      type: http
      scheme: bearer
      description: 'Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.'