openapi: 3.1.0
info:
  title: LangWatch Agents Trace API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
- url: https://app.langwatch.ai
security:
- project_api_key: []
tags:
- name: Trace
paths:
  /api/trace/{id}:
    get:
      description: Returns single trace details based on the ID supplied
      parameters:
      - name: id
        in: path
        description: ID of trace to share
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trace details with spans and evaluations
          content:
            application/json:
              schema:
                type: object
                properties:
                  trace_id:
                    type: string
                    example: trace_BKZL_X0TKSD4oa1aBJTc_
                  project_id:
                    type: string
                    example: KAXYxPR8MUgTcP8CF193y
                  metadata:
                    type: object
                    properties:
                      sdk_version:
                        type: string
                        example: 0.1.11
                      sdk_language:
                        type: string
                        example: python
                  timestamps:
                    type: object
                    properties:
                      started_at:
                        type: integer
                        example: 1721382486868
                      inserted_at:
                        type: integer
                        example: 1721382492894
                      updated_at:
                        type: integer
                        example: 1721382492894
                  input:
                    type: object
                    properties:
                      value:
                        type: string
                        example: hi
                  output:
                    type: object
                    properties:
                      value:
                        type: string
                        example: Hey there! 👋😊
                  metrics:
                    type: object
                    properties:
                      first_token_ms:
                        type: integer
                        example: 1449
                      total_time_ms:
                        type: integer
                        example: 1543
                      prompt_tokens:
                        type: integer
                        example: 20
                      completion_tokens:
                        type: integer
                        example: 7
                      tokens_estimated:
                        type: boolean
                        example: true
                  error:
                    type: object
                    nullable: true
                    properties:
                      stacktrace:
                        type: array
                        items:
                          type: string
                      message:
                        type: string
                      has_error:
                        type: boolean
                    example: null
                  indexing_md5s:
                    type: array
                    items:
                      type: string
                    example:
                    - cccd21e0b70c706034dfd9f7772816a3
                  spans:
                    type: array
                    items:
                      type: object
                      properties:
                        trace_id:
                          type: string
                          example: trace_BKZL_X0TKSD4oa1aBJTc_
                        span_id:
                          type: string
                          example: span_h1xUkcUJilhudDrLeQbR_
                        timestamps:
                          type: object
                          properties:
                            finished_at:
                              type: integer
                              example: 1721382488392
                            updated_at:
                              type: integer
                              example: 1721382492027
                            started_at:
                              type: integer
                              example: 1721382486895
                            first_token_at:
                              type: integer
                              example: 1721382488317
                            inserted_at:
                              type: integer
                              example: 1721382492027
                        type:
                          type: string
                          example: llm
                        error:
                          type: object
                          nullable: true
                          properties:
                            stacktrace:
                              type: array
                              items:
                                type: string
                            message:
                              type: string
                            has_error:
                              type: boolean
                          example: null
                        params:
                          type: object
                          properties:
                            stream:
                              type: boolean
                              example: true
                            temperature:
                              type: number
                              example: 1
                        project_id:
                          type: string
                          example: KAXYxPR8MUgTcP8CF193y
                        parent_id:
                          type: string
                          nullable: true
                          example: span_ijZNjUMTz3ys0Z0YKwF_T
                        name:
                          type: string
                          nullable: true
                          example: null
                        model:
                          type: string
                          example: openai/gpt-4o
                        metrics:
                          type: object
                          properties:
                            tokens_estimated:
                              type: boolean
                              example: true
                            completion_tokens:
                              type: integer
                              example: 7
                            prompt_tokens:
                              type: integer
                              example: 20
                        input:
                          type: object
                          properties:
                            type:
                              type: string
                              example: chat_messages
                            value:
                              type: array
                              items:
                                type: object
                                properties:
                                  role:
                                    type: string
                                    example: system
                                  content:
                                    type: string
                                    example: You are a helpful assistant that only reply in short tweet-like responses, using lots of emojis.
                              example:
                              - role: system
                                content: You are a helpful assistant that only reply in short tweet-like responses, using lots of emojis.
                              - role: user
                                content: hi
                        output:
                          type: object
                          properties:
                            type:
                              type: string
                              example: chat_messages
                            value:
                              type: array
                              items:
                                type: object
                                properties:
                                  role:
                                    type: string
                                    example: assistant
                                  content:
                                    type: string
                                    example: Hey there! 👋😊
                              example:
                              - role: assistant
                                content: Hey there! 👋😊
                  evaluations:
                    type: array
                    items:
                      type: object
                      properties:
                        evaluation_id:
                          type: string
                          example: check_VCagriZHNWICSOM09dXjM
                        name:
                          type: string
                          example: Ragas Answer Relevancy
                        type:
                          type: string
                          example: ragas/answer_relevancy
                        trace_id:
                          type: string
                          example: trace_BKZL_X0TKSD4oa1aBJTc_
                        project_id:
                          type: string
                          example: KAXYxPR8MUgTcP8CF193y
                        status:
                          type: string
                          example: error
                        timestamps:
                          type: object
                          properties:
                            updated_at:
                              type: integer
                              example: 1721383657788
                            inserted_at:
                              type: integer
                              example: 1721382493358
                        error:
                          type: object
                          properties:
                            stacktrace:
                              type: array
                              items:
                                type: string
                              example:
                              - 'TypeError: fetch failed'
                            message:
                              type: string
                              example: fetch failed
                            has_error:
                              type: boolean
                              example: true
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Trace
  /api/trace/{id}/share:
    post:
      description: Returns a public path for a trace
      parameters:
      - name: id
        in: path
        description: ID of trace to share
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Public path created
          content:
            application/json:
              schema:
                type: object
                properties:
                  path:
                    type: string
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Trace
  /api/trace/{id}/unshare:
    post:
      description: Deletes a public path for a trace
      parameters:
      - name: id
        in: path
        description: ID of trace to unshare
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Public path deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        '400':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Trace
components:
  schemas:
    Error:
      required:
      - error
      - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  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}.'