openapi.yml

openapi: 3.0.1
info:
  title: langfuse
  version: ''
  description: >-
    ## Authentication


    Authenticate with the API using [Basic
    Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API
    keys in the project settings:


    - username: Langfuse Public Key

    - password: Langfuse Secret Key


    ## Exports


    - OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
paths:
  /api/public/annotation-queues:
    get:
      description: Get all annotation queues
      operationId: annotationQueues_listQueues
      tags:
        - AnnotationQueues
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAnnotationQueues'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: Create an annotation queue
      operationId: annotationQueues_createQueue
      tags:
        - AnnotationQueues
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueue'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationQueueRequest'
  /api/public/annotation-queues/{queueId}:
    get:
      description: Get an annotation queue by ID
      operationId: annotationQueues_getQueue
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueue'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/annotation-queues/{queueId}/items:
    get:
      description: Get items for a specific annotation queue
      operationId: annotationQueues_listQueueItems
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: status
          in: query
          description: Filter by status
          required: false
          schema:
            $ref: '#/components/schemas/AnnotationQueueStatus'
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedAnnotationQueueItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: Add an item to an annotation queue
      operationId: annotationQueues_createQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAnnotationQueueItemRequest'
  /api/public/annotation-queues/{queueId}/items/{itemId}:
    get:
      description: Get a specific item from an annotation queue
      operationId: annotationQueues_getQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    patch:
      description: Update an annotation queue item
      operationId: annotationQueues_updateQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnnotationQueueItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAnnotationQueueItemRequest'
    delete:
      description: Remove an item from an annotation queue
      operationId: annotationQueues_deleteQueueItem
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
        - name: itemId
          in: path
          description: The unique identifier of the annotation queue item
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAnnotationQueueItemResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/annotation-queues/{queueId}/assignments:
    post:
      description: Create an assignment for a user to an annotation queue
      operationId: annotationQueues_createQueueAssignment
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
    delete:
      description: Delete an assignment for a user to an annotation queue
      operationId: annotationQueues_deleteQueueAssignment
      tags:
        - AnnotationQueues
      parameters:
        - name: queueId
          in: path
          description: The unique identifier of the annotation queue
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
  /api/public/integrations/blob-storage:
    get:
      description: >-
        Get all blob storage integrations for the organization (requires
        organization-scoped API key)
      operationId: blobStorageIntegrations_getBlobStorageIntegrations
      tags:
        - BlobStorageIntegrations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    put:
      description: >-
        Create or update a blob storage integration for a specific project
        (requires organization-scoped API key). The configuration is validated
        by performing a test upload to the bucket.
      operationId: blobStorageIntegrations_upsertBlobStorageIntegration
      tags:
        - BlobStorageIntegrations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBlobStorageIntegrationRequest'
  /api/public/integrations/blob-storage/{id}:
    get:
      description: >-
        Get the sync status of a blob storage integration by integration ID
        (requires organization-scoped API key)
      operationId: blobStorageIntegrations_getBlobStorageIntegrationStatus
      tags:
        - BlobStorageIntegrations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationStatusResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: >-
        Delete a blob storage integration by ID (requires organization-scoped
        API key)
      operationId: blobStorageIntegrations_deleteBlobStorageIntegration
      tags:
        - BlobStorageIntegrations
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/comments:
    post:
      description: >-
        Create a comment. Comments may be attached to different object types
        (trace, observation, session, prompt).
      operationId: comments_create
      tags:
        - Comments
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCommentResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCommentRequest'
    get:
      description: Get all comments
      operationId: comments_get
      tags:
        - Comments
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit
          required: false
          schema:
            type: integer
            nullable: true
        - name: objectType
          in: query
          description: >-
            Filter comments by object type (trace, observation, session, prompt).
          required: false
          schema:
            type: string
            nullable: true
        - name: objectId
          in: query
          description: >-
            Filter comments by object id. If objectType is not provided, an
            error will be thrown.
          required: false
          schema:
            type: string
            nullable: true
        - name: authorUserId
          in: query
          description: Filter comments by author user id.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCommentsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/comments/{commentId}:
    get:
      description: Get a comment by id
      operationId: comments_get-by-id
      tags:
        - Comments
      parameters:
        - name: commentId
          in: path
          description: The unique langfuse identifier of a comment
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Comment'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/dataset-items:
    post:
      description: Create a dataset item
      operationId: datasetItems_create
      tags:
        - DatasetItems
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetItemRequest'
    get:
      description: >-
        Get dataset items. Optionally specify a version to get the items as they
        existed at that point in time.

        Note: If version parameter is provided, datasetName must also be
        provided.
      operationId: datasetItems_list
      tags:
        - DatasetItems
      parameters:
        - name: datasetName
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sourceTraceId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sourceObservationId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: version
          in: query
          description: >-
            ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
            "2026-01-21T14:35:42Z").

            If provided, returns state of dataset at this timestamp.

            If not provided, returns the latest version. Requires datasetName to
            be specified.
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasetItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/dataset-items/{id}:
    get:
      description: Get a dataset item
      operationId: datasetItems_get
      tags:
        - DatasetItems
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: >-
        Delete a dataset item and all its run items. This action is irreversible.
      operationId: datasetItems_delete
      tags:
        - DatasetItems
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDatasetItemResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/dataset-run-items:
    post:
      description: Create a dataset run item
      operationId: datasetRunItems_create
      tags:
        - DatasetRunItems
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetRunItem'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRunItemRequest'
    get:
      description: List dataset run items
      operationId: datasetRunItems_list
      tags:
        - DatasetRunItems
      parameters:
        - name: datasetId
          in: query
          required: true
          schema:
            type: string
        - name: runName
          in: query
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasetRunItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/v2/datasets:
    get:
      description: Get all datasets
      operationId: datasets_list
      tags:
        - Datasets
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasets'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: Create a dataset
      operationId: datasets_create
      tags:
        - Datasets
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRequest'
  /api/public/v2/datasets/{datasetName}:
    get:
      description: Get a dataset
      operationId: datasets_get
      tags:
        - Datasets
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/datasets/{datasetName}/runs/{runName}:
    get:
      description: Get a dataset run and its items
      operationId: datasets_getRun
      tags:
        - Datasets
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
        - name: runName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetRunWithItems'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: Delete a dataset run and all its run items. This action is irreversible.
      operationId: datasets_deleteRun
      tags:
        - Datasets
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
        - name: runName
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDatasetRunResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/datasets/{datasetName}/runs:
    get:
      description: Get dataset runs
      operationId: datasets_getRuns
      tags:
        - Datasets
      parameters:
        - name: datasetName
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDatasetRuns'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/health:
    get:
      description: Check health of API and database
      operationId: health_health
      tags:
        - Health
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '503':
          description: ''
  /api/public/ingestion:
    post:
      description: >-
        **Legacy endpoint for batch ingestion for Langfuse Observability.**


        -> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`).
        Learn more: https://langfuse.com/integrations/native/opentelemetry


        Within each batch, there can be multiple events.

        Each event has a type, an id, a timestamp, metadata and a body.

        Internally, we refer to this as the "event envelope" as it tells us
        something about the event but not the trace.

        We use the event id within this envelope to deduplicate messages to
        avoid processing the same event twice, i.e. the event id should be
        unique per request.

        The event.body.id is the ID of the actual trace and will be used for
        updates and will be visible within the Langfuse App.

        I.e. if you want to update a trace, you'd use the same body id, but
        separate event IDs.


        Notes:

        - Introduction to data model:
        https://langfuse.com/docs/observability/data-model

        - Batch sizes are limited to 3.5 MB in total. You need to adjust the
        number of events per batch accordingly.

        - The API does not return a 4xx status code for input errors. Instead,
        it responds with a 207 status code, which includes a list of the
        encountered errors.
      operationId: ingestion_batch
      tags:
        - Ingestion
      parameters: []
      responses:
        '207':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IngestionResponse'
              examples:
                Example1:
                  value:
                    successes:
                      - id: abcdef-1234-5678-90ab
                        status: 201
                    errors: []
                Example2:
                  value:
                    successes:
                      - id: abcdef-1234-5678-90ab
                        status: 201
                    errors: []
                Example3:
                  value:
                    successes:
                      - id: abcdef-1234-5678-90ab
                        status: 201
                    errors: []
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                batch:
                  type: array
                  items:
                    $ref: '#/components/schemas/IngestionEvent'
                  description: >-
                    Batch of tracing events to be ingested. Discriminated by
                    attribute `type`.
                metadata:
                  nullable: true
                  description: >-
                    Optional. Metadata field used by the Langfuse SDKs for
                    debugging.
              required:
                - batch
            examples:
              Example1:
                value:
                  batch:
                    - id: abcdef-1234-5678-90ab
                      timestamp: '2022-01-01T00:00:00.000Z'
                      type: trace-create
                      body:
                        id: abcdef-1234-5678-90ab
                        timestamp: '2022-01-01T00:00:00.000Z'
                        environment: production
                        name: My Trace
                        userId: 1234-5678-90ab-cdef
                        input: My input
                        output: My output
                        sessionId: 1234-5678-90ab-cdef
                        release: 1.0.0
                        version: 1.0.0
                        metadata: My metadata
                        tags:
                          - tag1
                          - tag2
                        public: true
              Example2:
                value:
                  batch:
                    - id: abcdef-1234-5678-90ab
                      timestamp: '2022-01-01T00:00:00.000Z'
                      type: span-create
                      body:
                        id: abcdef-1234-5678-90ab
                        traceId: 1234-5678-90ab-cdef
                        startTime: '2022-01-01T00:00:00.000Z'
                        environment: test
              Example3:
                value:
                  batch:
                    - id: abcdef-1234-5678-90ab
                      timestamp: '2022-01-01T00:00:00.000Z'
                      type: score-create
                      body:
                        id: abcdef-1234-5678-90ab
                        traceId: 1234-5678-90ab-cdef
                        name: My Score
                        value: 0.9
                        environment: default
  /api/public/metrics:
    get:
      description: >-
        Get metrics from the Langfuse project using a query object.


        Consider using the [v2 metrics
        endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for
        better performance.


        For more details, see the [Metrics API
        documentation](https://langfuse.com/docs/metrics/features/metrics-api).
      operationId: legacy_metricsV1_metrics
      tags:
        - LegacyMetricsV1
      parameters:
        - name: query
          in: query
          description: >-
            JSON string containing the query parameters with the following
            structure:

            ```json

            {
              "view": string,           // Required. One of "traces", "observations", "scores-numeric", "scores-categorical"
              "dimensions": [           // Optional. Default: []
                {
                  "field": string       // Field to group by, e.g. "name", "userId", "sessionId"
                }
              ],
              "metrics": [              // Required. At least one metric must be provided
                {
                  "measure": string,    // What to measure, e.g. "count", "latency", "value"
                  "aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram"
                }
              ],
              "filters": [              // Optional. Default: []
                {
                  "column": string,     // Column to filter on
                  "operator": string,   // Operator, e.g. "=", ">", "<", "contains"
                  "value": any,         // Value to compare against
                  "type": string,       // Data type, e.g. "string", "number", "stringObject"
                  "key": string         // Required only when filtering on metadata
                }
              ],
              "timeDimension": {        // Optional. Default: null. If provided, results will be grouped by time
                "granularity": string   // One of "minute", "hour", "day", "week", "month", "auto"
              },
              "fromTimestamp": string,  // Required. ISO datetime string for start of time range
              "toTimestamp": string,    // Required. ISO datetime string for end of time range
              "orderBy": [              // Optional. Default: null
                {
                  "field": string,      // Field to order by
                  "direction": string   // "asc" or "desc"
                }
              ],
              "config": {               // Optional. Query-specific configuration
                "bins": number,         // Optional. Number of bins for histogram (1-100), default: 10
                "row_limit": number     // Optional. Row limit for results (1-1000)
              }
            }

            ```
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/legacyMetricsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/observations/{observationId}:
    get:
      description: Get a observation
      operationId: legacy_observationsV1_get
      tags:
        - LegacyObservationsV1
      parameters:
        - name: observationId
          in: path
          description: >-
            The unique langfuse identifier of an observation, can be an event,
            span or generation
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsView'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/observations:
    get:
      description: >-
        Get a list of observations.


        Consider using the [v2 observations
        endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations)
        for cursor-based pagination and field selection.
      operationId: legacy_observationsV1_getMany
      tags:
        - LegacyObservationsV1
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit.
          required: false
          schema:
            type: integer
            nullable: true
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: userId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: type
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: traceId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: level
          in: query
          description: >-
            Optional filter for observations with a specific level (e.g.
            "DEBUG", "DEFAULT", "WARNING", "ERROR").
          required: false
          schema:
            $ref: '#/components/schemas/ObservationLevel'
            nullable: true
        - name: parentObservationId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for observations where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: fromStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time on or after this
            datetime (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time before this datetime
            (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: version
          in: query
          description: Optional filter to only include observations with a certain version.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON string containing an array of filter conditions. When provided,
            this takes precedence over query parameter filters (userId, name,
            type, level, environment, fromStartTime, ...).


            ## Filter Structure

            Each filter condition has the following structure:

            ```json

            [
              {
                "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                "column": string,         // Required. Column to filter on (see available columns below)
                "operator": string,       // Required. Operator based on type:
                                          // - datetime: ">", "<", ">=", "<="
                                          // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - stringOptions: "any of", "none of"
                                          // - categoryOptions: "any of", "none of"
                                          // - arrayOptions: "any of", "none of", "all of"
                                          // - number: "=", ">", "<", ">=", "<="
                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - numberObject: "=", ">", "<", ">=", "<="
                                          // - boolean: "=", "<>"
                                          // - null: "is null", "is not null"
                "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
                "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
              }
            ]

            ```


            ## Available Columns


            ### Core Observation Fields

            - `id` (string) - Observation ID

            - `type` (string) - Observation type (SPAN, GENERATION, EVENT)

            - `name` (string) - Observation name

            - `traceId` (string) - Associated trace ID

            - `startTime` (datetime) - Observation start time

            - `endTime` (datetime) - Observation end time

            - `environment` (string) - Environment tag

            - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)

            - `statusMessage` (string) - Status message

            - `version` (string) - Version tag


            ### Performance Metrics

            - `latency` (number) - Latency in seconds (calculated: end_time -
            start_time)

            - `timeToFirstToken` (number) - Time to first token in seconds

            - `tokensPerSecond` (number) - Output tokens per second


            ### Token Usage

            - `inputTokens` (number) - Number of input tokens

            - `outputTokens` (number) - Number of output tokens

            - `totalTokens` (number) - Total tokens (alias: `tokens`)


            ### Cost Metrics

            - `inputCost` (number) - Input cost in USD

            - `outputCost` (number) - Output cost in USD

            - `totalCost` (number) - Total cost in USD


            ### Model Information

            - `model` (string) - Provided model name

            - `promptName` (string) - Associated prompt name

            - `promptVersion` (number) - Associated prompt version


            ### Structured Data

            - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
            key-value pairs. Use `key` parameter to filter on specific metadata
            keys.


            ### Associated Trace Fields (requires join with traces table)

            - `userId` (string) - User ID from associated trace

            - `traceName` (string) - Name from associated trace

            - `traceEnvironment` (string) - Environment from associated trace

            - `traceTags` (arrayOptions) - Tags from associated trace


            ## Filter Examples

            ```json

            [
              {
                "type": "string",
                "column": "type",
                "operator": "=",
                "value": "GENERATION"
              },
              {
                "type": "number",
                "column": "latency",
                "operator": ">=",
                "value": 2.5
              },
              {
                "type": "stringObject",
                "column": "metadata",
                "key": "environment",
                "operator": "=",
                "value": "production"
              }
            ]

            ```
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/legacyObservationsViews'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/scores:
    post:
      description: Create a score (supports both trace and session scores)
      operationId: legacy_scoreV1_create
      tags:
        - LegacyScoreV1
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/legacyCreateScoreResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/legacyCreateScoreRequest'
  /api/public/scores/{scoreId}:
    delete:
      description: Delete a score (supports both trace and session scores)
      operationId: legacy_scoreV1_delete
      tags:
        - LegacyScoreV1
      parameters:
        - name: scoreId
          in: path
          description: The unique langfuse identifier of a score
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/llm-connections:
    get:
      description: Get all LLM connections in a project
      operationId: llmConnections_list
      tags:
        - LlmConnections
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedLlmConnections'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    put:
      description: >-
        Create or update an LLM connection. The connection is upserted on
        provider.
      operationId: llmConnections_upsert
      tags:
        - LlmConnections
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LlmConnection'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertLlmConnectionRequest'
  /api/public/llm-connections/{id}:
    delete:
      description: >-
        Delete an LLM connection by id. Evaluators that depend on the deleted
        connection are automatically paused.
      operationId: llmConnections_delete
      tags:
        - LlmConnections
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteLlmConnectionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/media/{mediaId}:
    get:
      description: Get a media record
      operationId: media_get
      tags:
        - Media
      parameters:
        - name: mediaId
          in: path
          description: The unique langfuse identifier of a media record
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    patch:
      description: Patch a media record
      operationId: media_patch
      tags:
        - Media
      parameters:
        - name: mediaId
          in: path
          description: The unique langfuse identifier of a media record
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchMediaBody'
  /api/public/media:
    post:
      description: Get a presigned upload URL for a media record
      operationId: media_getUploadUrl
      tags:
        - Media
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaUploadUrlResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMediaUploadUrlRequest'
  /api/public/v2/metrics:
    get:
      description: >-
        Get metrics from the Langfuse project using a query object. V2 endpoint
        with optimized performance.


        ## V2 Differences

        - Supports `observations`, `scores-numeric`, and `scores-categorical`
        views only (traces view not supported)

        - Direct access to tags and release fields on observations

        - Backwards-compatible: traceName, traceRelease, traceVersion dimensions
        are still available on observations view

        - High cardinality dimensions are not supported and will return a 400
        error (see below)


        For more details, see the [Metrics API
        documentation](https://langfuse.com/docs/metrics/features/metrics-api).


        ## Available Views


        ### observations

        Query observation-level data (spans, generations, events).


        **Dimensions:**

        - `environment` - Deployment environment (e.g., production, staging)

        - `type` - Type of observation (SPAN, GENERATION, EVENT)

        - `name` - Name of the observation

        - `level` - Logging level of the observation

        - `version` - Version of the observation

        - `tags` - User-defined tags

        - `release` - Release version

        - `traceName` - Name of the parent trace (backwards-compatible)

        - `traceRelease` - Release version of the parent trace
        (backwards-compatible, maps to release)

        - `traceVersion` - Version of the parent trace (backwards-compatible,
        maps to version)

        - `providedModelName` - Name of the model used

        - `promptName` - Name of the prompt used

        - `promptVersion` - Version of the prompt used

        - `startTimeMonth` - Month of start_time in YYYY-MM format


        **Measures:**

        - `count` - Total number of observations

        - `latency` - Observation latency (milliseconds)

        - `streamingLatency` - Generation latency from completion start to end
        (milliseconds)

        - `inputTokens` - Sum of input tokens consumed

        - `outputTokens` - Sum of output tokens produced

        - `totalTokens` - Sum of all tokens consumed

        - `outputTokensPerSecond` - Output tokens per second

        - `tokensPerSecond` - Total tokens per second

        - `inputCost` - Input cost (USD)

        - `outputCost` - Output cost (USD)

        - `totalCost` - Total cost (USD)

        - `timeToFirstToken` - Time to first token (milliseconds)

        - `countScores` - Number of scores attached to the observation


        ### scores-numeric

        Query numeric and boolean score data.


        **Dimensions:**

        - `environment` - Deployment environment

        - `name` - Name of the score (e.g., accuracy, toxicity)

        - `source` - Origin of the score (API, ANNOTATION, EVAL)

        - `dataType` - Data type (NUMERIC, BOOLEAN)

        - `configId` - Identifier of the score config

        - `timestampMonth` - Month in YYYY-MM format

        - `timestampDay` - Day in YYYY-MM-DD format

        - `value` - Numeric value of the score

        - `traceName` - Name of the parent trace

        - `tags` - Tags

        - `traceRelease` - Release version

        - `traceVersion` - Version

        - `observationName` - Name of the associated observation

        - `observationModelName` - Model name of the associated observation

        - `observationPromptName` - Prompt name of the associated observation

        - `observationPromptVersion` - Prompt version of the associated
        observation


        **Measures:**

        - `count` - Total number of scores

        - `value` - Score value (for aggregations)


        ### scores-categorical

        Query categorical score data. Same dimensions as scores-numeric except
        uses `stringValue` instead of `value`.


        **Measures:**

        - `count` - Total number of scores


        ## High Cardinality Dimensions

        The following dimensions cannot be used as grouping dimensions in v2
        metrics API as they can cause performance issues.

        Use them in filters instead.


        **observations view:**

        - `id` - Use traceId filter to narrow down results

        - `traceId` - Use traceId filter instead

        - `userId` - Use userId filter instead

        - `sessionId` - Use sessionId filter instead

        - `parentObservationId` - Use parentObservationId filter instead


        **scores-numeric / scores-categorical views:**

        - `id` - Use specific filters to narrow down results

        - `traceId` - Use traceId filter instead

        - `userId` - Use userId filter instead

        - `sessionId` - Use sessionId filter instead

        - `observationId` - Use observationId filter instead


        ## Aggregations

        Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,
        `p50`, `p75`, `p90`, `p95`, `p99`, `histogram`


        ## Time Granularities

        Available granularities for timeDimension: `auto`, `minute`, `hour`,
        `day`, `week`, `month`

        - `auto` bins the data into approximately 50 buckets based on the time
        range
      operationId: metrics_metrics
      tags:
        - Metrics
      parameters:
        - name: query
          in: query
          description: >-
            JSON string containing the query parameters with the following
            structure:

            ```json

            {
              "view": string,           // Required. One of "observations", "scores-numeric", "scores-categorical"
              "dimensions": [           // Optional. Default: []
                {
                  "field": string       // Field to group by (see available dimensions above)
                }
              ],
              "metrics": [              // Required. At least one metric must be provided
                {
                  "measure": string,    // What to measure (see available measures above)
                  "aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram"
                }
              ],
              "filters": [              // Optional. Default: []
                {
                  "column": string,     // Column to filter on (any dimension field)
                  "operator": string,   // Operator based on type:
                                        // - datetime: ">", "<", ">=", "<="
                                        // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                        // - stringOptions: "any of", "none of"
                                        // - arrayOptions: "any of", "none of", "all of"
                                        // - number: "=", ">", "<", ">=", "<="
                                        // - stringObject/numberObject: same as string/number with required "key"
                                        // - boolean: "=", "<>"
                                        // - null: "is null", "is not null"
                  "value": any,         // Value to compare against
                  "type": string,       // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                  "key": string         // Required only for stringObject/numberObject types (e.g., metadata filtering)
                }
              ],
              "timeDimension": {        // Optional. Default: null. If provided, results will be grouped by time
                "granularity": string   // One of "auto", "minute", "hour", "day", "week", "month"
              },
              "fromTimestamp": string,  // Required. ISO datetime string for start of time range
              "toTimestamp": string,    // Required. ISO datetime string for end of time range (must be after fromTimestamp)
              "orderBy": [              // Optional. Default: null
                {
                  "field": string,      // Field to order by (dimension or metric alias)
                  "direction": string   // "asc" or "desc"
                }
              ],
              "config": {               // Optional. Query-specific configuration
                "bins": number,         // Optional. Number of bins for histogram aggregation (1-100), default: 10
                "row_limit": number     // Optional. Maximum number of rows to return (1-1000), default: 100
              }
            }

            ```
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsV2Response'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/models:
    post:
      description: Create a model
      operationId: models_create
      tags:
        - Models
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateModelRequest'
    get:
      description: Get all models
      operationId: models_list
      tags:
        - Models
      parameters:
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedModels'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/models/{id}:
    get:
      description: Get a model
      operationId: models_get
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: >-
        Delete a model. Cannot delete models managed by Langfuse. You can create
        your own definition with the same modelName to override the definition
        though.
      operationId: models_delete
      tags:
        - Models
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/v2/observations:
    get:
      description: >-
        Get a list of observations with cursor-based pagination and flexible
        field selection.


        ## Cursor-based Pagination

        This endpoint uses cursor-based pagination for efficient traversal of
        large datasets.

        The cursor is returned in the response metadata and should be passed in
        subsequent requests

        to retrieve the next page of results.


        ## Field Selection

        Use the `fields` parameter to control which observation fields are
        returned:

        - `core` - Always included: id, traceId, startTime, endTime, projectId,
        parentObservationId, type

        - `basic` - name, level, statusMessage, version, environment,
        bookmarked, public, userId, sessionId

        - `time` - completionStartTime, createdAt, updatedAt

        - `io` - input, output

        - `metadata` - metadata (truncated to 200 chars by default, use
        `expandMetadata` to get full values)

        - `model` - providedModelName, internalModelId, modelParameters

        - `usage` - usageDetails, costDetails, totalCost

        - `prompt` - promptId, promptName, promptVersion

        - `metrics` - latency, timeToFirstToken


        If not specified, `core` and `basic` field groups are returned.


        ## Filters

        Multiple filtering options are available via query parameters or the
        structured `filter` parameter.

        When using the `filter` parameter, it takes precedence over individual
        query parameter filters.
      operationId: observations_getMany
      tags:
        - Observations
      parameters:
        - name: fields
          in: query
          description: >-
            Comma-separated list of field groups to include in the response.

            Available groups: core, basic, time, io, metadata, model, usage,
            prompt, metrics.

            If not specified, `core` and `basic` field groups are returned.

            Example: "basic,usage,model"
          required: false
          schema:
            type: string
            nullable: true
        - name: expandMetadata
          in: query
          description: |-
            Comma-separated list of metadata keys to return non-truncated.
            By default, metadata values over 200 characters are truncated.
            Use this parameter to retrieve full values for specific keys.
            Example: "key1,key2"
          required: false
          schema:
            type: string
            nullable: true
        - name: limit
          in: query
          description: Number of items to return per page. Maximum 1000, default 50.
          required: false
          schema:
            type: integer
            nullable: true
        - name: cursor
          in: query
          description: >-
            Base64-encoded cursor for pagination. Use the cursor from the
            previous response to get the next page.
          required: false
          schema:
            type: string
            nullable: true
        - name: parseIoAsJson
          in: query
          description: |-
            **Deprecated.** Setting this to `true` will return a 400 error.
            Input/output fields are always returned as raw strings.
            Remove this parameter or set it to `false`.
          required: false
          schema:
            type: boolean
            nullable: true
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: userId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: type
          in: query
          description: >-
            Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
            "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
            "GUARDRAIL")
          required: false
          schema:
            type: string
            nullable: true
        - name: traceId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: level
          in: query
          description: >-
            Optional filter for observations with a specific level (e.g.
            "DEBUG", "DEFAULT", "WARNING", "ERROR").
          required: false
          schema:
            $ref: '#/components/schemas/ObservationLevel'
            nullable: true
        - name: parentObservationId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for observations where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: fromStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time on or after this
            datetime (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toStartTime
          in: query
          description: >-
            Retrieve only observations with a start_time before this datetime
            (ISO 8601).
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: version
          in: query
          description: Optional filter to only include observations with a certain version.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON string containing an array of filter conditions. When provided,
            this takes precedence over query parameter filters (userId, name,
            type, level, environment, fromStartTime, ...).


            ## Filter Structure

            Each filter condition has the following structure:

            ```json

            [
              {
                "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                "column": string,         // Required. Column to filter on (see available columns below)
                "operator": string,       // Required. Operator based on type:
                                          // - datetime: ">", "<", ">=", "<="
                                          // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - stringOptions: "any of", "none of"
                                          // - categoryOptions: "any of", "none of"
                                          // - arrayOptions: "any of", "none of", "all of"
                                          // - number: "=", ">", "<", ">=", "<="
                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - numberObject: "=", ">", "<", ">=", "<="
                                          // - boolean: "=", "<>"
                                          // - null: "is null", "is not null"
                "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
                "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
              }
            ]

            ```


            ## Available Columns


            ### Core Observation Fields

            - `id` (string) - Observation ID

            - `type` (string) - Observation type (SPAN, GENERATION, EVENT)

            - `name` (string) - Observation name

            - `traceId` (string) - Associated trace ID

            - `startTime` (datetime) - Observation start time

            - `endTime` (datetime) - Observation end time

            - `environment` (string) - Environment tag

            - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)

            - `statusMessage` (string) - Status message

            - `version` (string) - Version tag

            - `userId` (string) - User ID

            - `sessionId` (string) - Session ID


            ### Trace-Related Fields

            - `traceName` (string) - Name of the parent trace

            - `traceTags` (arrayOptions) - Tags from the parent trace

            - `tags` (arrayOptions) - Alias for traceTags


            ### Performance Metrics

            - `latency` (number) - Latency in seconds (calculated: end_time -
            start_time)

            - `timeToFirstToken` (number) - Time to first token in seconds

            - `tokensPerSecond` (number) - Output tokens per second


            ### Token Usage

            - `inputTokens` (number) - Number of input tokens

            - `outputTokens` (number) - Number of output tokens

            - `totalTokens` (number) - Total tokens (alias: `tokens`)


            ### Cost Metrics

            - `inputCost` (number) - Input cost in USD

            - `outputCost` (number) - Output cost in USD

            - `totalCost` (number) - Total cost in USD


            ### Model Information

            - `model` (string) - Provided model name (alias:
            `providedModelName`)

            - `promptName` (string) - Associated prompt name

            - `promptVersion` (number) - Associated prompt version


            ### Structured Data

            - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
            key-value pairs. Use `key` parameter to filter on specific metadata
            keys.


            ## Filter Examples

            ```json

            [
              {
                "type": "string",
                "column": "type",
                "operator": "=",
                "value": "GENERATION"
              },
              {
                "type": "number",
                "column": "latency",
                "operator": ">=",
                "value": 2.5
              },
              {
                "type": "stringObject",
                "column": "metadata",
                "key": "environment",
                "operator": "=",
                "value": "production"
              }
            ]

            ```
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObservationsV2Response'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/otel/v1/traces:
    post:
      description: >-
        **OpenTelemetry Traces Ingestion Endpoint**


        This endpoint implements the OTLP/HTTP specification for trace
        ingestion, providing native OpenTelemetry integration for Langfuse
        Observability.


        **Supported Formats:**

        - Binary Protobuf: `Content-Type: application/x-protobuf`

        - JSON Protobuf: `Content-Type: application/json`

        - Supports gzip compression via `Content-Encoding: gzip` header


        **Specification Compliance:**

        - Conforms to [OTLP/HTTP Trace
        Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)

        - Implements `ExportTraceServiceRequest` message format


        **Documentation:**

        - Integration guide:
        https://langfuse.com/integrations/native/opentelemetry

        - Data model: https://langfuse.com/docs/observability/data-model
      operationId: opentelemetry_exportTraces
      tags:
        - Opentelemetry
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OtelTraceResponse'
              examples:
                BasicTraceExport:
                  value: {}
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                resourceSpans:
                  type: array
                  items:
                    $ref: '#/components/schemas/OtelResourceSpan'
                  description: >-
                    Array of resource spans containing trace data as defined in
                    the OTLP specification
              required:
                - resourceSpans
            examples:
              BasicTraceExport:
                value:
                  resourceSpans:
                    - resource:
                        attributes:
                          - key: service.name
                            value:
                              stringValue: my-service
                          - key: service.version
                            value:
                              stringValue: 1.0.0
                      scopeSpans:
                        - scope:
                            name: langfuse-sdk
                            version: 2.60.3
                          spans:
                            - traceId: 0123456789abcdef0123456789abcdef
                              spanId: 0123456789abcdef
                              name: my-operation
                              kind: 1
                              startTimeUnixNano: '1747872000000000000'
                              endTimeUnixNano: '1747872001000000000'
                              attributes:
                                - key: langfuse.observation.type
                                  value:
                                    stringValue: generation
                              status: {}
  /api/public/organizations/memberships:
    get:
      description: >-
        Get all memberships for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationMemberships
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    put:
      description: >-
        Create or update a membership for the organization associated with the
        API key (requires organization-scoped API key)
      operationId: organizations_updateOrganizationMembership
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipRequest'
    delete:
      description: >-
        Delete a membership from the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_deleteOrganizationMembership
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembershipRequest'
  /api/public/projects/{projectId}/memberships:
    get:
      description: >-
        Get all memberships for a specific project (requires organization-scoped
        API key)
      operationId: organizations_getProjectMemberships
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    put:
      description: >-
        Create or update a membership for a specific project (requires
        organization-scoped API key). The user must already be a member of the
        organization.
      operationId: organizations_updateProjectMembership
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MembershipRequest'
    delete:
      description: >-
        Delete a membership from a specific project (requires
        organization-scoped API key). The user must be a member of the
        organization.
      operationId: organizations_deleteProjectMembership
      tags:
        - Organizations
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembershipRequest'
  /api/public/organizations/projects:
    get:
      description: >-
        Get all projects for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationProjects
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationProjectsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/organizations/apiKeys:
    get:
      description: >-
        Get all API keys for the organization associated with the API key
        (requires organization-scoped API key)
      operationId: organizations_getOrganizationApiKeys
      tags:
        - Organizations
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationApiKeysResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/projects:
    get:
      description: >-
        Get Project associated with API key (requires project-scoped API key).
        You can use GET /api/public/organizations/projects to get all projects
        with an organization-scoped key.
      operationId: projects_get
      tags:
        - Projects
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Projects'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: Create a new project (requires organization-scoped API key)
      operationId: projects_create
      tags:
        - Projects
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                  nullable: true
                  description: Optional metadata for the project
                retention:
                  type: integer
                  description: >-
                    Number of days to retain data. Must be 0 or at least 3 days.
                    Requires data-retention entitlement for non-zero values.
                    Optional.
              required:
                - name
                - retention
  /api/public/projects/{projectId}:
    put:
      description: Update a project by ID (requires organization-scoped API key).
      operationId: projects_update
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                metadata:
                  type: object
                  additionalProperties: true
                  nullable: true
                  description: Optional metadata for the project
                retention:
                  type: integer
                  nullable: true
                  description: |-
                    Number of days to retain data.
                    Must be 0 or at least 3 days.
                    Requires data-retention entitlement for non-zero values.
                    Optional. Will retain existing retention setting if omitted.
              required:
                - name
    delete:
      description: >-
        Delete a project by ID (requires organization-scoped API key). Project
        deletion is processed asynchronously.
      operationId: projects_delete
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '202':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/projects/{projectId}/apiKeys:
    get:
      description: Get all API keys for a project (requires organization-scoped API key)
      operationId: projects_getApiKeys
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyList'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: >-
        Create a new API key for a project (requires organization-scoped API key)
      operationId: projects_createApiKey
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                note:
                  type: string
                  nullable: true
                  description: Optional note for the API key
                publicKey:
                  type: string
                  nullable: true
                  description: >-
                    Optional predefined public key. Must start with 'pk-lf-'. If
                    provided, secretKey must also be provided.
                secretKey:
                  type: string
                  nullable: true
                  description: >-
                    Optional predefined secret key. Must start with 'sk-lf-'. If
                    provided, publicKey must also be provided.
  /api/public/projects/{projectId}/apiKeys/{apiKeyId}:
    delete:
      description: Delete an API key for a project (requires organization-scoped API key)
      operationId: projects_deleteApiKey
      tags:
        - Projects
      parameters:
        - name: projectId
          in: path
          required: true
          schema:
            type: string
        - name: apiKeyId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyDeletionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/v2/prompts/{name}/versions/{version}:
    patch:
      description: Update labels for a specific prompt version
      operationId: promptVersion_update
      tags:
        - PromptVersion
      parameters:
        - name: name
          in: path
          description: >-
            The name of the prompt. If the prompt is in a folder (e.g.,
            "folder/subfolder/prompt-name"), 

            the folder path must be URL encoded.
          required: true
          schema:
            type: string
        - name: version
          in: path
          description: Version of the prompt to update
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newLabels:
                  type: array
                  items:
                    type: string
                  description: >-
                    New labels for the prompt version. Labels are unique across
                    versions. The "latest" label is reserved and managed by
                    Langfuse.
              required:
                - newLabels
  /api/public/v2/prompts/{promptName}:
    get:
      description: Get a prompt
      operationId: prompts_get
      tags:
        - Prompts
      parameters:
        - name: promptName
          in: path
          description: >-
            The name of the prompt. If the prompt is in a folder (e.g.,
            "folder/subfolder/prompt-name"), 

            the folder path must be URL encoded.
          required: true
          schema:
            type: string
        - name: prompt-version
          in: query
          description: Version of the prompt to be retrieved.
          required: false
          schema:
            type: integer
            nullable: true
        - name: label
          in: query
          description: >-
            Label of the prompt to be retrieved. Defaults to "production" if no
            label or version is set.
          required: false
          schema:
            type: string
            nullable: true
        - name: resolve
          in: query
          description: >-
            Resolve prompt dependencies before returning the prompt. Defaults to
            `true`. Set to `false` to return the raw stored prompt with
            dependency tags intact. This bypasses prompt caching and is intended
            for debugging or one-off jobs, not production runtime fetches.
          required: false
          schema:
            type: boolean
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: >-
        Delete prompt versions. If neither version nor label is specified, all
        versions of the prompt are deleted.
      operationId: prompts_delete
      tags:
        - Prompts
      parameters:
        - name: promptName
          in: path
          description: The name of the prompt
          required: true
          schema:
            type: string
        - name: label
          in: query
          description: >-
            Optional label to filter deletion. If specified, deletes all prompt
            versions that have this label.
          required: false
          schema:
            type: string
            nullable: true
        - name: version
          in: query
          description: >-
            Optional version to filter deletion. If specified, deletes only this
            specific version of the prompt.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/v2/prompts:
    get:
      description: Get a list of prompt names with versions and labels
      operationId: prompts_list
      tags:
        - Prompts
      parameters:
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: label
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: tag
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: page
          in: query
          description: page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: limit of items per page
          required: false
          schema:
            type: integer
            nullable: true
        - name: fromUpdatedAt
          in: query
          description: >-
            Optional filter to only include prompt versions created/updated on
            or after a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toUpdatedAt
          in: query
          description: >-
            Optional filter to only include prompt versions created/updated
            before a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptMetaListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: >-
        Create a new version for the prompt with the given `name`


        Example:
          langfuse api prompts create --type text --name my-prompt --prompt 'Hello {{name}}'
      operationId: prompts_create
      tags:
        - Prompts
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePromptRequest'
  /api/public/scim/ServiceProviderConfig:
    get:
      description: >-
        Get SCIM Service Provider Configuration (requires organization-scoped
        API key)
      operationId: scim_getServiceProviderConfig
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceProviderConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/scim/ResourceTypes:
    get:
      description: Get SCIM Resource Types (requires organization-scoped API key)
      operationId: scim_getResourceTypes
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceTypesResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/scim/Schemas:
    get:
      description: Get SCIM Schemas (requires organization-scoped API key)
      operationId: scim_getSchemas
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SchemasResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/scim/Users:
    get:
      description: List users in the organization (requires organization-scoped API key)
      operationId: scim_listUsers
      tags:
        - Scim
      parameters:
        - name: filter
          in: query
          description: Filter expression (e.g. userName eq "value")
          required: false
          schema:
            type: string
            nullable: true
        - name: startIndex
          in: query
          description: 1-based index of the first result to return (default 1)
          required: false
          schema:
            type: integer
            nullable: true
        - name: count
          in: query
          description: Maximum number of results to return (default 100)
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUsersListResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    post:
      description: >-
        Create a new user in the organization (requires organization-scoped API
        key)
      operationId: scim_createUser
      tags:
        - Scim
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                userName:
                  type: string
                  description: User's email address (required)
                name:
                  $ref: '#/components/schemas/ScimName'
                  description: User's name information
                emails:
                  type: array
                  items:
                    $ref: '#/components/schemas/ScimEmail'
                  nullable: true
                  description: User's email addresses
                active:
                  type: boolean
                  nullable: true
                  description: Whether the user is active
                password:
                  type: string
                  nullable: true
                  description: Initial password for the user
              required:
                - userName
                - name
  /api/public/scim/Users/{userId}:
    get:
      description: Get a specific user by ID (requires organization-scoped API key)
      operationId: scim_getUser
      tags:
        - Scim
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: >-
        Remove a user from the organization (requires organization-scoped API
        key). Note that this only removes the user from the organization but
        does not delete the user entity itself.
      operationId: scim_deleteUser
      tags:
        - Scim
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptyResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/score-configs:
    post:
      description: >-
        Create a score configuration (config). Score configs are used to define
        the structure of scores
      operationId: scoreConfigs_create
      tags:
        - ScoreConfigs
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScoreConfigRequest'
    get:
      description: Get all score configs
      operationId: scoreConfigs_get
      tags:
        - ScoreConfigs
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfigs'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/score-configs/{configId}:
    get:
      description: Get a score config
      operationId: scoreConfigs_get-by-id
      tags:
        - ScoreConfigs
      parameters:
        - name: configId
          in: path
          description: The unique langfuse identifier of a score config
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    patch:
      description: Update a score config
      operationId: scoreConfigs_update
      tags:
        - ScoreConfigs
      parameters:
        - name: configId
          in: path
          description: The unique langfuse identifier of a score config
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreConfig'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScoreConfigRequest'
  /api/public/v2/scores:
    get:
      description: Get a list of scores (supports both trace and session scores)
      operationId: scores_get-many
      tags:
        - Scores
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit.
          required: false
          schema:
            type: integer
            nullable: true
        - name: userId
          in: query
          description: Retrieve only scores with this userId associated to the trace.
          required: false
          schema:
            type: string
            nullable: true
        - name: name
          in: query
          description: Retrieve only scores with this name.
          required: false
          schema:
            type: string
            nullable: true
        - name: fromTimestamp
          in: query
          description: >-
            Optional filter to only include scores created on or after a certain
            datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: >-
            Optional filter to only include scores created before a certain
            datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for scores where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: source
          in: query
          description: Retrieve only scores from a specific source.
          required: false
          schema:
            $ref: '#/components/schemas/ScoreSource'
            nullable: true
        - name: operator
          in: query
          description: Retrieve only scores with <operator> value.
          required: false
          schema:
            type: string
            nullable: true
        - name: value
          in: query
          description: Retrieve only scores with <operator> value.
          required: false
          schema:
            type: number
            format: double
            nullable: true
        - name: scoreIds
          in: query
          description: Comma-separated list of score IDs to limit the results to.
          required: false
          schema:
            type: string
            nullable: true
        - name: configId
          in: query
          description: Retrieve only scores with a specific configId.
          required: false
          schema:
            type: string
            nullable: true
        - name: sessionId
          in: query
          description: Retrieve only scores with a specific sessionId.
          required: false
          schema:
            type: string
            nullable: true
        - name: datasetRunId
          in: query
          description: Retrieve only scores with a specific datasetRunId.
          required: false
          schema:
            type: string
            nullable: true
        - name: traceId
          in: query
          description: Retrieve only scores with a specific traceId.
          required: false
          schema:
            type: string
            nullable: true
        - name: observationId
          in: query
          description: Comma-separated list of observation IDs to filter scores by.
          required: false
          schema:
            type: string
            nullable: true
        - name: queueId
          in: query
          description: Retrieve only scores with a specific annotation queueId.
          required: false
          schema:
            type: string
            nullable: true
        - name: dataType
          in: query
          description: Retrieve only scores with a specific dataType.
          required: false
          schema:
            $ref: '#/components/schemas/ScoreDataType'
            nullable: true
        - name: traceTags
          in: query
          description: >-
            Only scores linked to traces that include all of these tags will be
            returned.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: fields
          in: query
          description: >-
            Comma-separated list of field groups to include in the response.
            Available field groups: 'score' (core score fields), 'trace' (trace
            properties: userId, tags, environment, sessionId). If not specified,
            both 'score' and 'trace' are returned by default. Example: 'score'
            to exclude trace data, 'score,trace' to include both. Note: When
            filtering by trace properties (using userId or traceTags
            parameters), the 'trace' field group must be included, otherwise a
            400 error will be returned.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: >-
            A JSON stringified array of filter objects. Each object requires
            type, column, operator, and value. Supports filtering by score
            metadata using the stringObject type. Example:
            [{"type":"stringObject","column":"metadata","key":"user_id","operator":"=","value":"abc123"}].
            Supported types: stringObject (metadata key-value filtering),
            string, number, datetime, stringOptions, arrayOptions. Supported
            operators for stringObject: =, contains, does not contain, starts
            with, ends with.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetScoresResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/v2/scores/{scoreId}:
    get:
      description: Get a score (supports both trace and session scores)
      operationId: scores_get-by-id
      tags:
        - Scores
      parameters:
        - name: scoreId
          in: path
          description: The unique langfuse identifier of a score
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Score'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/sessions:
    get:
      description: Get sessions
      operationId: sessions_list
      tags:
        - Sessions
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit.
          required: false
          schema:
            type: integer
            nullable: true
        - name: fromTimestamp
          in: query
          description: >-
            Optional filter to only include sessions created on or after a
            certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: >-
            Optional filter to only include sessions created before a certain
            datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for sessions where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSessions'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/sessions/{sessionId}:
    get:
      description: >-
        Get a session. Please note that `traces` on this endpoint are not
        paginated, if you plan to fetch large sessions, consider `GET
        /api/public/traces?sessionId=<sessionId>`
      operationId: sessions_get
      tags:
        - Sessions
      parameters:
        - name: sessionId
          in: path
          description: The unique id of a session
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionWithTraces'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/traces/{traceId}:
    get:
      description: Get a specific trace
      operationId: trace_get
      tags:
        - Trace
      parameters:
        - name: traceId
          in: path
          description: The unique langfuse identifier of a trace
          required: true
          schema:
            type: string
        - name: fields
          in: query
          description: >-
            Comma-separated list of fields to include in the response. Available
            field groups: 'core' (always included), 'io' (input, output,
            metadata), 'scores', 'observations', 'metrics'. If not specified,
            all fields are returned. Example: 'core,scores,metrics'. Note:
            Excluded 'observations' or 'scores' fields return empty arrays;
            excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceWithFullDetails'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: Delete a specific trace
      operationId: trace_delete
      tags:
        - Trace
      parameters:
        - name: traceId
          in: path
          description: The unique langfuse identifier of the trace to delete
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTraceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
  /api/public/traces:
    get:
      description: Get list of traces
      operationId: trace_list
      tags:
        - Trace
      parameters:
        - name: page
          in: query
          description: Page number, starts at 1
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: >-
            Limit of items per page. If you encounter api issues due to too
            large page sizes, try to reduce the limit.
          required: false
          schema:
            type: integer
            nullable: true
        - name: userId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: name
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: sessionId
          in: query
          required: false
          schema:
            type: string
            nullable: true
        - name: fromTimestamp
          in: query
          description: >-
            Optional filter to only include traces with a trace.timestamp on or
            after a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: toTimestamp
          in: query
          description: >-
            Optional filter to only include traces with a trace.timestamp before
            a certain datetime (ISO 8601)
          required: false
          schema:
            type: string
            format: date-time
            nullable: true
        - name: orderBy
          in: query
          description: >-
            Format of the string [field].[asc/desc]. Fields: id, timestamp,
            name, userId, release, version, public, bookmarked, sessionId.
            Example: timestamp.asc
          required: false
          schema:
            type: string
            nullable: true
        - name: tags
          in: query
          description: Only traces that include all of these tags will be returned.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: version
          in: query
          description: Optional filter to only include traces with a certain version.
          required: false
          schema:
            type: string
            nullable: true
        - name: release
          in: query
          description: Optional filter to only include traces with a certain release.
          required: false
          schema:
            type: string
            nullable: true
        - name: environment
          in: query
          description: >-
            Optional filter for traces where the environment is one of the
            provided values.
          required: false
          schema:
            type: array
            items:
              type: string
              nullable: true
        - name: fields
          in: query
          description: >-
            Comma-separated list of fields to include in the response. Available
            field groups: 'core' (always included), 'io' (input, output,
            metadata), 'scores', 'observations', 'metrics'. If not specified,
            all fields are returned. Example: 'core,scores,metrics'. Note:
            Excluded 'observations' or 'scores' fields return empty arrays;
            excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
          required: false
          schema:
            type: string
            nullable: true
        - name: filter
          in: query
          description: >-
            JSON string containing an array of filter conditions. When provided,
            this takes precedence over query parameter filters (userId, name,
            sessionId, tags, version, release, environment, fromTimestamp,
            toTimestamp).


            ## Filter Structure

            Each filter condition has the following structure:

            ```json

            [
              {
                "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
                "column": string,         // Required. Column to filter on (see available columns below)
                "operator": string,       // Required. Operator based on type:
                                          // - datetime: ">", "<", ">=", "<="
                                          // - string: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - stringOptions: "any of", "none of"
                                          // - categoryOptions: "any of", "none of"
                                          // - arrayOptions: "any of", "none of", "all of"
                                          // - number: "=", ">", "<", ">=", "<="
                                          // - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
                                          // - numberObject: "=", ">", "<", ">=", "<="
                                          // - boolean: "=", "<>"
                                          // - null: "is null", "is not null"
                "value": any,             // Required (except for null type). Value to compare against. Type depends on filter type
                "key": string             // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
              }
            ]

            ```


            ## Available Columns


            ### Core Trace Fields

            - `id` (string) - Trace ID

            - `name` (string) - Trace name

            - `timestamp` (datetime) - Trace timestamp

            - `userId` (string) - User ID

            - `sessionId` (string) - Session ID

            - `environment` (string) - Environment tag

            - `version` (string) - Version tag

            - `release` (string) - Release tag

            - `tags` (arrayOptions) - Array of tags

            - `bookmarked` (boolean) - Bookmark status


            ### Structured Data

            - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
            key-value pairs. Use `key` parameter to filter on specific metadata
            keys.


            ### Aggregated Metrics (from observations)

            These metrics are aggregated from all observations within the trace:

            - `latency` (number) - Latency in seconds (time from first
            observation start to last observation end)

            - `inputTokens` (number) - Total input tokens across all
            observations

            - `outputTokens` (number) - Total output tokens across all
            observations

            - `totalTokens` (number) - Total tokens (alias: `tokens`)

            - `inputCost` (number) - Total input cost in USD

            - `outputCost` (number) - Total output cost in USD

            - `totalCost` (number) - Total cost in USD


            ### Observation Level Aggregations

            These fields aggregate observation levels within the trace:

            - `level` (string) - Highest severity level (ERROR > WARNING >
            DEFAULT > DEBUG)

            - `warningCount` (number) - Count of WARNING level observations

            - `errorCount` (number) - Count of ERROR level observations

            - `defaultCount` (number) - Count of DEFAULT level observations

            - `debugCount` (number) - Count of DEBUG level observations


            ### Scores (requires join with scores table)

            - `scores_avg` (number) - Average of numeric scores (alias:
            `scores`)

            - `score_categories` (categoryOptions) - Categorical score values


            ## Filter Examples

            ```json

            [
              {
                "type": "datetime",
                "column": "timestamp",
                "operator": ">=",
                "value": "2024-01-01T00:00:00Z"
              },
              {
                "type": "string",
                "column": "userId",
                "operator": "=",
                "value": "user-123"
              },
              {
                "type": "number",
                "column": "totalCost",
                "operator": ">=",
                "value": 0.01
              },
              {
                "type": "arrayOptions",
                "column": "tags",
                "operator": "all of",
                "value": ["production", "critical"]
              },
              {
                "type": "stringObject",
                "column": "metadata",
                "key": "customer_tier",
                "operator": "=",
                "value": "enterprise"
              }
            ]

            ```


            ## Performance Notes

            - Filtering on `userId`, `sessionId`, or `metadata` may enable skip
            indexes for better query performance

            - Score filters require a join with the scores table and may impact
            query performance
          required: false
          schema:
            type: string
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Traces'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
    delete:
      description: Delete multiple traces
      operationId: trace_deleteMultiple
      tags:
        - Trace
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteTraceResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                traceIds:
                  type: array
                  items:
                    type: string
                  description: List of trace IDs to delete
              required:
                - traceIds
  /api/public/unstable/evaluation-rules:
    post:
      description: >-
        Create an evaluation rule.


        An evaluation rule defines **what** incoming data should be evaluated
        and **how prompt variables should be populated** from that data.


        Use this resource after choosing an evaluator from the evaluator
        endpoints.


        Key rules:

        - `name` must be unique within the project for public evaluation rules

        - `target` must be `observation` or `experiment`

        - `evaluator.name` + `evaluator.scope` must identify an existing
        evaluator family returned by the evaluator endpoints

        - Langfuse resolves that family to its latest version before saving the
        evaluation rule

        - for `target=experiment`, use dataset `id` values from `GET
        /api/public/v2/datasets` when filtering by `datasetId`

        - every evaluator prompt variable must be mapped exactly once

        - `expected_output` mappings are only valid for `target=experiment`

        - if `enabled=true`, Langfuse validates that the referenced evaluator
        can currently run

        - at most 50 evaluation rules can be effectively active in one project
        at the same time


        If an evaluation rule with the same `name` already exists in the
        project, the API returns `409`.

        In that case, update the existing resource with `PATCH
        /api/public/unstable/evaluation-rules/{evaluationRuleId}` instead of
        creating a second one.


        If enabling this resource would exceed the 50-active limit, the API also
        returns `409`.

        In that case, disable or pause another active evaluation rule before
        enabling a new one.


        Current scope:

        - evaluation rules are live-ingestion rules only

        - they do not trigger historical backfills


        Recovery guidance:

        - `400 invalid_filter_value`: fix the filter `column` or `value` using
        `details.column`, `details.invalidValues`, and `details.allowedValues`

        - `400 invalid_filter_value` with `details.column=datasetId`: call `GET
        /api/public/v2/datasets`, then retry with dataset `id` values from that
        response

        - `400 missing_variable_mapping`: fetch the evaluator again and make
        sure every variable in `variables` appears exactly once in `mapping`

        - `400 duplicate_variable_mapping`: remove repeated mappings for the
        same variable

        - `400 invalid_variable_mapping`: switch to a valid `source` for the
        selected `target`, or fix the variable name

        - `400 invalid_json_path`: remove or correct the `jsonPath`

        - `422 evaluator_preflight_failed`: the selected evaluator cannot run
        with the resolved model configuration. Fix the evaluator/default model
        setup, then retry the create request.
      operationId: unstable_evaluationRules_create
      tags:
        - UnstableEvaluationRules
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluationRule'
              examples:
                CreateObservationEvaluationRule:
                  value:
                    id: erule_123
                    name: answer-correctness-live
                    evaluator:
                      id: evaltmpl_123
                      name: answer-correctness
                      scope: project
                    target: observation
                    enabled: true
                    status: active
                    sampling: 1
                    filter:
                      - type: stringOptions
                        column: type
                        operator: any of
                        value:
                          - GENERATION
                    mapping:
                      - variable: input
                        source: input
                      - variable: output
                        source: output
                    createdAt: '2026-03-30T09:20:00.000Z'
                    updatedAt: '2026-03-30T09:20:00.000Z'
                CreateExperimentEvaluationRule:
                  value:
                    id: erule_456
                    name: experiment-expected-output-match
                    evaluator:
                      id: evaltmpl_456
                      name: expected-output-match
                      scope: project
                    target: experiment
                    enabled: true
                    status: active
                    sampling: 0.5
                    filter:
                      - type: stringOptions
                        column: datasetId
                        operator: any of
                        value:
                          - 550e8400-e29b-41d4-a716-446655440000
                    mapping:
                      - variable: output
                        source: output
                      - variable: expected_output
                        source: expected_output
                    createdAt: '2026-03-30T09:30:00.000Z'
                    updatedAt: '2026-03-30T09:30:00.000Z'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableCreateEvaluationRuleRequest'
            examples:
              CreateObservationEvaluationRule:
                value:
                  name: answer-correctness-live
                  evaluator:
                    name: answer-correctness
                    scope: project
                  target: observation
                  enabled: true
                  sampling: 1
                  filter:
                    - type: stringOptions
                      column: type
                      operator: any of
                      value:
                        - GENERATION
                  mapping:
                    - variable: input
                      source: input
                    - variable: output
                      source: output
              CreateExperimentEvaluationRule:
                value:
                  name: experiment-expected-output-match
                  evaluator:
                    name: expected-output-match
                    scope: project
                  target: experiment
                  enabled: true
                  sampling: 0.5
                  filter:
                    - type: stringOptions
                      column: datasetId
                      operator: any of
                      value:
                        - 550e8400-e29b-41d4-a716-446655440000
                  mapping:
                    - variable: output
                      source: output
                    - variable: expected_output
                      source: expected_output
    get:
      description: >-
        List evaluation rules in the authenticated project.


        Each item describes one live evaluation rule and its effective runtime
        status.
      operationId: unstable_evaluationRules_list
      tags:
        - UnstableEvaluationRules
      parameters:
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluationRules'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
  /api/public/unstable/evaluation-rules/{evaluationRuleId}:
    get:
      description: >-
        Get one evaluation rule by its identifier.


        Use this endpoint to inspect the current evaluator, target, mapping,
        filters, and effective runtime status.
      operationId: unstable_evaluationRules_get
      tags:
        - UnstableEvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: >-
            Evaluation rule identifier returned by the evaluation rule endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
    patch:
      description: >-
        Update an evaluation rule.


        Typical uses:

        - enable or disable live execution

        - switch to another evaluator

        - adjust sampling

        - change filters

        - update variable mappings


        Important behavior:

        - provide only the fields you want to change

        - if you provide `evaluator`, Langfuse resolves that evaluator family to
        its latest version before saving

        - changing `target`, `filter`, or `mapping` must still produce a valid
        target-specific configuration

        - if you change `target`, also send a compatible `filter` and `mapping`
        in the same request unless the existing ones are still valid for the new
        target

        - if the resulting config is enabled, Langfuse re-validates that the
        selected evaluator can run

        - if the update would move a non-active evaluation rule into the active
        state and the project already has 50 active evaluation rules, the API
        returns `409`


        Recovery guidance:

        - if the update fails with `missing_variable_mapping` or
        `invalid_variable_mapping` after changing `evaluator` or `target`,
        resend the request with a complete new `mapping`

        - if the update fails with `invalid_filter_value` after changing
        `target`, resend the request with a target-compatible `filter`
      operationId: unstable_evaluationRules_update
      tags:
        - UnstableEvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: Evaluation rule identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluationRule'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableUpdateEvaluationRuleRequest'
    delete:
      description: >-
        Delete an evaluation rule.


        This removes the live-ingestion rule only. It does not delete the
        referenced evaluator.
      operationId: unstable_evaluationRules_delete
      tags:
        - UnstableEvaluationRules
      parameters:
        - name: evaluationRuleId
          in: path
          description: Evaluation rule identifier.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableDeleteEvaluationRuleResponse'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
  /api/public/unstable/evaluators:
    post:
      description: >-
        Create an evaluator in the authenticated project.


        Use evaluators to define **how** Langfuse should score data: the prompt,
        the expected structured output, and the optional model configuration.


        Naming behavior:

        - If this is a new evaluator name in your project, Langfuse creates
        version `1`.

        - If the name already exists in your project, Langfuse creates the next
        version and returns it.

        - When a new project version is created, existing evaluation rules in
        that project automatically move to the newest version for that evaluator
        name.


        Recommended workflow:

        1. Create the evaluator.

        2. Read the returned `variables` array.

        3. Read the returned `outputDefinition.dataType` so the client knows
        whether future scores will be numeric, boolean, or categorical.

        4. Create one or more evaluation rules that reference the returned
        evaluator family using `name` and `scope`.


        Recovery guidance:

        - `422` with `code=evaluator_preflight_failed`: the evaluator cannot run
        with the resolved model configuration. Add a valid explicit
        `modelConfig`, or configure the project's default evaluation model, then
        retry the same request.

        - `400` with `code=invalid_body`: the request shape is malformed. Use
        the structured `details.issues` array to fix the specific fields and
        retry.

        - `400` with `code=invalid_body` on `outputDefinition`: send `dataType`,
        `reasoning.description`, and `score.description`. Do not send `version`;
        it is not part of the public request shape.


        Unstable API note:

        - This surface may evolve while the underlying evaluation data model is
        being redesigned.
      operationId: unstable_evaluators_create
      tags:
        - UnstableEvaluators
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluator'
              examples:
                CreateEvaluatorVersion:
                  value:
                    id: evaltmpl_123
                    name: answer-correctness
                    version: 2
                    scope: project
                    type: llm_as_judge
                    prompt: |
                      You are grading an answer.

                      Input:
                      {{input}}

                      Output:
                      {{output}}

                      Return a score between 0 and 1.
                    variables:
                      - input
                      - output
                    outputDefinition:
                      dataType: NUMERIC
                      reasoning:
                        description: Explain why the score was assigned.
                      score:
                        description: Correctness score between 0 and 1.
                    modelConfig:
                      provider: openai
                      model: gpt-4.1-mini
                    evaluationRuleCount: 0
                    createdAt: '2026-03-30T09:00:00.000Z'
                    updatedAt: '2026-03-30T09:00:00.000Z'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '409':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '422':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/unstableCreateEvaluatorRequest'
            examples:
              CreateEvaluatorVersion:
                value:
                  name: answer-correctness
                  prompt: |
                    You are grading an answer.

                    Input:
                    {{input}}

                    Output:
                    {{output}}

                    Return a score between 0 and 1.
                  outputDefinition:
                    dataType: NUMERIC
                    reasoning:
                      description: Explain why the score was assigned.
                    score:
                      description: Correctness score between 0 and 1.
                  modelConfig:
                    provider: openai
                    model: gpt-4.1-mini
    get:
      description: >-
        List the evaluators available to the authenticated project.


        Important behavior:

        - This endpoint returns the latest version of each available evaluator.

        - Results can include evaluators from your project and Langfuse-managed
        evaluators.

        - If the same evaluator name exists in both places, both are returned as
        separate items with different `scope` values.
      operationId: unstable_evaluators_list
      tags:
        - UnstableEvaluators
      parameters:
        - name: page
          in: query
          description: 1-based page number. Defaults to `1`.
          required: false
          schema:
            type: integer
            nullable: true
        - name: limit
          in: query
          description: Maximum number of items per page. Defaults to `50`.
          required: false
          schema:
            type: integer
            nullable: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluators'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
  /api/public/unstable/evaluators/{evaluatorId}:
    get:
      description: >-
        Get one evaluator by `id`.


        Use this endpoint when you want the prompt, output definition, model
        configuration, and derived variables for the evaluator you plan to use
        in an evaluation rule.
      operationId: unstable_evaluators_get
      tags:
        - UnstableEvaluators
      parameters:
        - name: evaluatorId
          in: path
          description: Evaluator identifier returned by the evaluator endpoints.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstableEvaluator'
        '400':
          description: ''
          content:
            application/json:
              schema: {}
        '401':
          description: ''
          content:
            application/json:
              schema: {}
        '403':
          description: ''
          content:
            application/json:
              schema: {}
        '404':
          description: ''
          content:
            application/json:
              schema: {}
        '405':
          description: ''
          content:
            application/json:
              schema: {}
        '429':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unstablePublicApiError'
      security:
        - BasicAuth: []
components:
  schemas:
    AnnotationQueueStatus:
      title: AnnotationQueueStatus
      type: string
      enum:
        - PENDING
        - COMPLETED
    AnnotationQueueObjectType:
      title: AnnotationQueueObjectType
      type: string
      enum:
        - TRACE
        - OBSERVATION
        - SESSION
    AnnotationQueue:
      title: AnnotationQueue
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        scoreConfigIds:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - scoreConfigIds
        - createdAt
        - updatedAt
    AnnotationQueueItem:
      title: AnnotationQueueItem
      type: object
      properties:
        id:
          type: string
        queueId:
          type: string
        objectId:
          type: string
        objectType:
          $ref: '#/components/schemas/AnnotationQueueObjectType'
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
        completedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - queueId
        - objectId
        - objectType
        - status
        - createdAt
        - updatedAt
    PaginatedAnnotationQueues:
      title: PaginatedAnnotationQueues
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueue'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PaginatedAnnotationQueueItems:
      title: PaginatedAnnotationQueueItems
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/AnnotationQueueItem'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateAnnotationQueueRequest:
      title: CreateAnnotationQueueRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        scoreConfigIds:
          type: array
          items:
            type: string
      required:
        - name
        - scoreConfigIds
    CreateAnnotationQueueItemRequest:
      title: CreateAnnotationQueueItemRequest
      type: object
      properties:
        objectId:
          type: string
        objectType:
          $ref: '#/components/schemas/AnnotationQueueObjectType'
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
          nullable: true
          description: Defaults to PENDING for new queue items
      required:
        - objectId
        - objectType
    UpdateAnnotationQueueItemRequest:
      title: UpdateAnnotationQueueItemRequest
      type: object
      properties:
        status:
          $ref: '#/components/schemas/AnnotationQueueStatus'
          nullable: true
    DeleteAnnotationQueueItemResponse:
      title: DeleteAnnotationQueueItemResponse
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
        - message
    AnnotationQueueAssignmentRequest:
      title: AnnotationQueueAssignmentRequest
      type: object
      properties:
        userId:
          type: string
      required:
        - userId
    DeleteAnnotationQueueAssignmentResponse:
      title: DeleteAnnotationQueueAssignmentResponse
      type: object
      properties:
        success:
          type: boolean
      required:
        - success
    CreateAnnotationQueueAssignmentResponse:
      title: CreateAnnotationQueueAssignmentResponse
      type: object
      properties:
        userId:
          type: string
        queueId:
          type: string
        projectId:
          type: string
      required:
        - userId
        - queueId
        - projectId
    BlobStorageIntegrationType:
      title: BlobStorageIntegrationType
      type: string
      enum:
        - S3
        - S3_COMPATIBLE
        - AZURE_BLOB_STORAGE
    BlobStorageIntegrationFileType:
      title: BlobStorageIntegrationFileType
      type: string
      enum:
        - JSON
        - CSV
        - JSONL
    BlobStorageExportMode:
      title: BlobStorageExportMode
      type: string
      enum:
        - FULL_HISTORY
        - FROM_TODAY
        - FROM_CUSTOM_DATE
    BlobStorageExportFrequency:
      title: BlobStorageExportFrequency
      type: string
      enum:
        - hourly
        - daily
        - weekly
    CreateBlobStorageIntegrationRequest:
      title: CreateBlobStorageIntegrationRequest
      type: object
      properties:
        projectId:
          type: string
          description: ID of the project in which to configure the blob storage integration
        type:
          $ref: '#/components/schemas/BlobStorageIntegrationType'
        bucketName:
          type: string
          description: >-
            Name of the storage bucket. For AZURE_BLOB_STORAGE, must be a valid
            Azure container name (3-63 chars, lowercase letters, numbers, and
            hyphens only, must start and end with a letter or number, no
            consecutive hyphens).
        endpoint:
          type: string
          nullable: true
          description: Custom endpoint URL (required for S3_COMPATIBLE type)
        region:
          type: string
          description: Storage region
        accessKeyId:
          type: string
          nullable: true
          description: Access key ID for authentication
        secretAccessKey:
          type: string
          nullable: true
          description: Secret access key for authentication (will be encrypted when stored)
        prefix:
          type: string
          nullable: true
          description: >-
            Path prefix for exported files (must end with forward slash if
            provided)
        exportFrequency:
          $ref: '#/components/schemas/BlobStorageExportFrequency'
        enabled:
          type: boolean
          description: Whether the integration is active
        forcePathStyle:
          type: boolean
          description: Use path-style URLs for S3 requests
        fileType:
          $ref: '#/components/schemas/BlobStorageIntegrationFileType'
        exportMode:
          $ref: '#/components/schemas/BlobStorageExportMode'
        exportStartDate:
          type: string
          format: date-time
          nullable: true
          description: >-
            Custom start date for exports (required when exportMode is
            FROM_CUSTOM_DATE)
        compressed:
          type: boolean
          nullable: true
          description: >-
            Enable gzip compression for exported files (.csv.gz, .json.gz,
            .jsonl.gz). Defaults to true.
      required:
        - projectId
        - type
        - bucketName
        - region
        - exportFrequency
        - enabled
        - forcePathStyle
        - fileType
        - exportMode
    BlobStorageIntegrationResponse:
      title: BlobStorageIntegrationResponse
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        type:
          $ref: '#/components/schemas/BlobStorageIntegrationType'
        bucketName:
          type: string
        endpoint:
          type: string
          nullable: true
        region:
          type: string
        accessKeyId:
          type: string
          nullable: true
        prefix:
          type: string
        exportFrequency:
          $ref: '#/components/schemas/BlobStorageExportFrequency'
        enabled:
          type: boolean
        forcePathStyle:
          type: boolean
        fileType:
          $ref: '#/components/schemas/BlobStorageIntegrationFileType'
        exportMode:
          $ref: '#/components/schemas/BlobStorageExportMode'
        exportStartDate:
          type: string
          format: date-time
          nullable: true
        compressed:
          type: boolean
        nextSyncAt:
          type: string
          format: date-time
          nullable: true
        lastSyncAt:
          type: string
          format: date-time
          nullable: true
        lastError:
          type: string
          nullable: true
        lastErrorAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - projectId
        - type
        - bucketName
        - region
        - prefix
        - exportFrequency
        - enabled
        - forcePathStyle
        - fileType
        - exportMode
        - compressed
        - createdAt
        - updatedAt
    BlobStorageIntegrationsResponse:
      title: BlobStorageIntegrationsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BlobStorageIntegrationResponse'
      required:
        - data
    BlobStorageSyncStatus:
      title: BlobStorageSyncStatus
      type: string
      enum:
        - idle
        - queued
        - up_to_date
        - disabled
        - error
      description: >-
        Sync status of the blob storage integration:

        - `disabled` — integration is not enabled

        - `error` — last export failed (see `lastError` for details)

        - `idle` — enabled but has never exported yet

        - `queued` — next export is overdue (`nextSyncAt` is in the past) and
        waiting to be picked up by the worker

        - `up_to_date` — all available data has been exported; next export is
        scheduled for the future


        **ETL usage**: poll this endpoint and check for `up_to_date` status.
        Compare `lastSyncAt` against your

        ETL bookmark to determine if new data is available. Note that exports
        run with a 30-minute lag buffer,

        so `lastSyncAt` will always be at least 30 minutes behind real-time.
    BlobStorageIntegrationStatusResponse:
      title: BlobStorageIntegrationStatusResponse
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        syncStatus:
          $ref: '#/components/schemas/BlobStorageSyncStatus'
        enabled:
          type: boolean
        lastSyncAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            End of the last successfully exported time window. Compare against
            your ETL bookmark to determine if new data is available. Null if the
            integration has never synced.
        nextSyncAt:
          type: string
          format: date-time
          nullable: true
          description: When the next export is scheduled. Null if no sync has occurred yet.
        lastError:
          type: string
          nullable: true
          description: >-
            Raw error message from the storage provider (S3/Azure/GCS) if the
            last export failed. Cleared on successful export.
        lastErrorAt:
          type: string
          format: date-time
          nullable: true
          description: When the last error occurred. Cleared on successful export.
      required:
        - id
        - projectId
        - syncStatus
        - enabled
    BlobStorageIntegrationDeletionResponse:
      title: BlobStorageIntegrationDeletionResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    CreateCommentRequest:
      title: CreateCommentRequest
      type: object
      properties:
        projectId:
          type: string
          description: The id of the project to attach the comment to.
        objectType:
          type: string
          description: >-
            The type of the object to attach the comment to (trace, observation,
            session, prompt).
        objectId:
          type: string
          description: >-
            The id of the object to attach the comment to. If this does not
            reference a valid existing object, an error will be thrown.
        content:
          type: string
          description: >-
            The content of the comment. May include markdown. Currently limited
            to 5000 characters.
        authorUserId:
          type: string
          nullable: true
          description: The id of the user who created the comment.
      required:
        - projectId
        - objectType
        - objectId
        - content
    CreateCommentResponse:
      title: CreateCommentResponse
      type: object
      properties:
        id:
          type: string
          description: The id of the created object in Langfuse
      required:
        - id
    GetCommentsResponse:
      title: GetCommentsResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Comment'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    Trace:
      title: Trace
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of a trace
        timestamp:
          type: string
          format: date-time
          description: The timestamp when the trace was created
        name:
          type: string
          nullable: true
          description: The name of the trace
        input:
          nullable: true
          description: The input data of the trace. Can be any JSON.
        output:
          nullable: true
          description: The output data of the trace. Can be any JSON.
        sessionId:
          type: string
          nullable: true
          description: The session identifier associated with the trace
        release:
          type: string
          nullable: true
          description: The release version of the application when the trace was created
        version:
          type: string
          nullable: true
          description: The version of the trace
        userId:
          type: string
          nullable: true
          description: The user identifier associated with the trace
        metadata:
          nullable: true
          description: The metadata associated with the trace. Can be any JSON.
        tags:
          type: array
          items:
            type: string
          description: The tags associated with the trace.
        public:
          type: boolean
          description: Public traces are accessible via url without login
        environment:
          type: string
          description: >-
            The environment from which this trace originated. Can be any
            lowercase alphanumeric string with hyphens and underscores that does
            not start with 'langfuse'.
      required:
        - id
        - timestamp
        - tags
        - public
        - environment
    TraceWithDetails:
      title: TraceWithDetails
      type: object
      properties:
        htmlPath:
          type: string
          description: Path of trace in Langfuse UI
        latency:
          type: number
          format: double
          nullable: true
          description: Latency of trace in seconds
        totalCost:
          type: number
          format: double
          nullable: true
          description: Cost of trace in USD
        observations:
          type: array
          items:
            type: string
          nullable: true
          description: List of observation ids
        scores:
          type: array
          items:
            type: string
          nullable: true
          description: List of score ids
      required:
        - htmlPath
      allOf:
        - $ref: '#/components/schemas/Trace'
    TraceWithFullDetails:
      title: TraceWithFullDetails
      type: object
      properties:
        htmlPath:
          type: string
          description: Path of trace in Langfuse UI
        latency:
          type: number
          format: double
          nullable: true
          description: Latency of trace in seconds
        totalCost:
          type: number
          format: double
          nullable: true
          description: Cost of trace in USD
        observations:
          type: array
          items:
            $ref: '#/components/schemas/ObservationsView'
          description: List of observations
        scores:
          type: array
          items:
            $ref: '#/components/schemas/ScoreV1'
          description: List of scores
      required:
        - htmlPath
        - observations
        - scores
      allOf:
        - $ref: '#/components/schemas/Trace'
    Session:
      title: Session
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        projectId:
          type: string
        environment:
          type: string
          description: The environment from which this session originated.
      required:
        - id
        - createdAt
        - projectId
        - environment
    SessionWithTraces:
      title: SessionWithTraces
      type: object
      properties:
        traces:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
      required:
        - traces
      allOf:
        - $ref: '#/components/schemas/Session'
    Observation:
      title: Observation
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the observation
        traceId:
          type: string
          nullable: true
          description: The trace ID associated with the observation
        type:
          type: string
          description: The type of the observation
        name:
          type: string
          nullable: true
          description: The name of the observation
        startTime:
          type: string
          format: date-time
          description: The start time of the observation
        endTime:
          type: string
          format: date-time
          nullable: true
          description: The end time of the observation.
        completionStartTime:
          type: string
          format: date-time
          nullable: true
          description: The completion start time of the observation
        model:
          type: string
          nullable: true
          description: The model used for the observation
        modelParameters:
          description: The parameters of the model used for the observation
        input:
          description: The input data of the observation
        version:
          type: string
          nullable: true
          description: The version of the observation
        metadata:
          description: Additional metadata of the observation
        output:
          description: The output data of the observation
        usage:
          $ref: '#/components/schemas/Usage'
          description: >-
            (Deprecated. Use usageDetails and costDetails instead.) The usage
            data of the observation
        level:
          $ref: '#/components/schemas/ObservationLevel'
          description: The level of the observation
        statusMessage:
          type: string
          nullable: true
          description: The status message of the observation
        parentObservationId:
          type: string
          nullable: true
          description: The parent observation ID
        promptId:
          type: string
          nullable: true
          description: The prompt ID associated with the observation
        usageDetails:
          type: object
          additionalProperties:
            type: integer
          description: >-
            The usage details of the observation. Key is the name of the usage
            metric, value is the number of units consumed. The total key is the
            sum of all (non-total) usage metrics or the total value ingested.
        costDetails:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            The cost details of the observation. Key is the name of the cost
            metric, value is the cost in USD. The total key is the sum of all
            (non-total) cost metrics or the total value ingested.
        environment:
          type: string
          description: >-
            The environment from which this observation originated. Can be any
            lowercase alphanumeric string with hyphens and underscores that does
            not start with 'langfuse'.
      required:
        - id
        - type
        - startTime
        - modelParameters
        - input
        - metadata
        - output
        - usage
        - level
        - usageDetails
        - costDetails
        - environment
    ObservationsView:
      title: ObservationsView
      type: object
      properties:
        promptName:
          type: string
          nullable: true
          description: The name of the prompt associated with the observation
        promptVersion:
          type: integer
          nullable: true
          description: The version of the prompt associated with the observation
        modelId:
          type: string
          nullable: true
          description: The unique identifier of the model
        inputPrice:
          type: number
          format: double
          nullable: true
          description: The price of the input in USD
        outputPrice:
          type: number
          format: double
          nullable: true
          description: The price of the output in USD.
        totalPrice:
          type: number
          format: double
          nullable: true
          description: The total price in USD.
        calculatedInputCost:
          type: number
          format: double
          nullable: true
          description: >-
            (Deprecated. Use usageDetails and costDetails instead.) The
            calculated cost of the input in USD
        calculatedOutputCost:
          type: number
          format: double
          nullable: true
          description: >-
            (Deprecated. Use usageDetails and costDetails instead.) The
            calculated cost of the output in USD
        calculatedTotalCost:
          type: number
          format: double
          nullable: true
          description: >-
            (Deprecated. Use usageDetails and costDetails instead.) The
            calculated total cost in USD
        latency:
          type: number
          format: double
          nullable: true
          description: The latency in seconds.
        timeToFirstToken:
          type: number
          format: double
          nullable: true
          description: The time to the first token in seconds
      allOf:
        - $ref: '#/components/schemas/Observation'
    ObservationV2:
      title: ObservationV2
      type: object
      description: >-
        An observation from the v2 API with field-group-based selection.

        Core fields are always present. Other fields are included only when
        their field group is requested.
      properties:
        id:
          type: string
          description: The unique identifier of the observation
        traceId:
          type: string
          nullable: true
          description: The trace ID associated with the observation
        startTime:
          type: string
          format: date-time
          description: The start time of the observation
        endTime:
          type: string
          format: date-time
          nullable: true
          description: The end time of the observation
        projectId:
          type: string
          description: The project ID this observation belongs to
        parentObservationId:
          type: string
          nullable: true
          description: The parent observation ID
        type:
          type: string
          description: The type of the observation (e.g. GENERATION, SPAN, EVENT)
        name:
          type: string
          nullable: true
          description: The name of the observation
        level:
          $ref: '#/components/schemas/ObservationLevel'
          nullable: true
          description: The level of the observation
        statusMessage:
          type: string
          nullable: true
          description: The status message of the observation
        version:
          type: string
          nullable: true
          description: The version of the observation
        environment:
          type: string
          nullable: true
          description: The environment from which this observation originated
        bookmarked:
          type: boolean
          nullable: true
          description: Whether the observation is bookmarked
        public:
          type: boolean
          nullable: true
          description: Whether the observation is public
        userId:
          type: string
          nullable: true
          description: The user ID associated with the observation
        sessionId:
          type: string
          nullable: true
          description: The session ID associated with the observation
        completionStartTime:
          type: string
          format: date-time
          nullable: true
          description: The completion start time of the observation
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: The creation timestamp of the observation
        updatedAt:
          type: string
          format: date-time
          nullable: true
          description: The last update timestamp of the observation
        input:
          nullable: true
          description: The input data of the observation
        output:
          nullable: true
          description: The output data of the observation
        metadata:
          nullable: true
          description: Additional metadata of the observation
        providedModelName:
          type: string
          nullable: true
          description: The model name as provided by the user
        internalModelId:
          type: string
          nullable: true
          description: The internal model ID matched by Langfuse
        modelParameters:
          nullable: true
          description: The parameters of the model used for the observation
        usageDetails:
          type: object
          additionalProperties:
            type: integer
          nullable: true
          description: >-
            The usage details of the observation. Key is the usage metric name,
            value is the number of units consumed.
        costDetails:
          type: object
          additionalProperties:
            type: number
            format: double
          nullable: true
          description: >-
            The cost details of the observation. Key is the cost metric name,
            value is the cost in USD.
        totalCost:
          type: number
          format: double
          nullable: true
          description: The total cost of the observation in USD
        promptId:
          type: string
          nullable: true
          description: The prompt ID associated with the observation
        promptName:
          type: string
          nullable: true
          description: The prompt name associated with the observation
        promptVersion:
          type: integer
          nullable: true
          description: The prompt version associated with the observation
        latency:
          type: number
          format: double
          nullable: true
          description: The latency in seconds
        timeToFirstToken:
          type: number
          format: double
          nullable: true
          description: The time to first token in seconds
        modelId:
          type: string
          nullable: true
          description: The matched model ID
      required:
        - id
        - startTime
        - projectId
        - type
    Usage:
      title: Usage
      type: object
      description: >-
        (Deprecated. Use usageDetails and costDetails instead.) Standard
        interface for usage and cost
      properties:
        input:
          type: integer
          description: Number of input units (e.g. tokens)
        output:
          type: integer
          description: Number of output units (e.g. tokens)
        total:
          type: integer
          description: Defaults to input+output if not set
        unit:
          type: string
          nullable: true
          description: Unit of measurement
        inputCost:
          type: number
          format: double
          nullable: true
          description: USD input cost
        outputCost:
          type: number
          format: double
          nullable: true
          description: USD output cost
        totalCost:
          type: number
          format: double
          nullable: true
          description: USD total cost, defaults to input+output
      required:
        - input
        - output
        - total
    ScoreConfig:
      title: ScoreConfig
      type: object
      description: Configuration for a score
      properties:
        id:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        projectId:
          type: string
        dataType:
          $ref: '#/components/schemas/ScoreConfigDataType'
        isArchived:
          type: boolean
          description: Whether the score config is archived. Defaults to false
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Sets minimum value for numerical scores. If not set, the minimum
            value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Sets maximum value for numerical scores. If not set, the maximum
            value defaults to +∞
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: Configures custom categories for categorical scores
        description:
          type: string
          nullable: true
          description: Description of the score config
      required:
        - id
        - name
        - createdAt
        - updatedAt
        - projectId
        - dataType
        - isArchived
    ConfigCategory:
      title: ConfigCategory
      type: object
      properties:
        value:
          type: number
          format: double
        label:
          type: string
      required:
        - value
        - label
    BaseScoreV1:
      title: BaseScoreV1
      type: object
      properties:
        id:
          type: string
        traceId:
          type: string
        name:
          type: string
        source:
          $ref: '#/components/schemas/ScoreSource'
        observationId:
          type: string
          nullable: true
          description: The observation ID associated with the score
        timestamp:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        authorUserId:
          type: string
          nullable: true
          description: The user ID of the author
        comment:
          type: string
          nullable: true
          description: Comment on the score
        metadata:
          description: Metadata associated with the score
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. When set, config and score name
            must be equal and value must comply to optionally defined numerical
            range
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        environment:
          type: string
          description: >-
            The environment from which this score originated. Can be any
            lowercase alphanumeric string with hyphens and underscores that does
            not start with 'langfuse'.
      required:
        - id
        - traceId
        - name
        - source
        - timestamp
        - createdAt
        - updatedAt
        - metadata
        - environment
    NumericScoreV1:
      title: NumericScoreV1
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScoreV1'
    BooleanScoreV1:
      title: BooleanScoreV1
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            The numeric value of the score. Equals 1 for "True" and 0 for "False"
        stringValue:
          type: string
          description: >-
            The string representation of the score value. Is inferred from the
            numeric value and equals "True" or "False"
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScoreV1'
    CategoricalScoreV1:
      title: CategoricalScoreV1
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            Represents the numeric category mapping of the stringValue. If no
            config is linked, defaults to 0.
        stringValue:
          type: string
          description: >-
            The string representation of the score value. If no config is
            linked, can be any string. Otherwise, must map to a config category
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScoreV1'
    TextScoreV1:
      title: TextScoreV1
      type: object
      properties:
        stringValue:
          type: string
          description: The text content of the score (1-500 characters)
      required:
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScoreV1'
    ScoreV1:
      title: ScoreV1
      type: object
      properties:
        dataType:
          type: string
          enum:
            - NUMERIC
            - CATEGORICAL
            - BOOLEAN
            - TEXT
        value:
          type: string
          description: The numeric value of the score
        stringValue:
          type: string
          description: The string representation of the score value. If no config is
            linked, can be any string. Otherwise, must map to a config category
      required:
        - dataType
    BaseScore:
      title: BaseScore
      type: object
      properties:
        id:
          type: string
        traceId:
          type: string
          nullable: true
          description: The trace ID associated with the score
        sessionId:
          type: string
          nullable: true
          description: The session ID associated with the score
        observationId:
          type: string
          nullable: true
          description: The observation ID associated with the score
        datasetRunId:
          type: string
          nullable: true
          description: The dataset run ID associated with the score
        name:
          type: string
        source:
          $ref: '#/components/schemas/ScoreSource'
        timestamp:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        authorUserId:
          type: string
          nullable: true
          description: The user ID of the author
        comment:
          type: string
          nullable: true
          description: Comment on the score
        metadata:
          description: Metadata associated with the score
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. When set, config and score name
            must be equal and value must comply to optionally defined numerical
            range
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        environment:
          type: string
          description: >-
            The environment from which this score originated. Can be any
            lowercase alphanumeric string with hyphens and underscores that does
            not start with 'langfuse'.
      required:
        - id
        - name
        - source
        - timestamp
        - createdAt
        - updatedAt
        - metadata
        - environment
    NumericScore:
      title: NumericScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score
      required:
        - value
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    BooleanScore:
      title: BooleanScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            The numeric value of the score. Equals 1 for "True" and 0 for "False"
        stringValue:
          type: string
          description: >-
            The string representation of the score value. Is inferred from the
            numeric value and equals "True" or "False"
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    CategoricalScore:
      title: CategoricalScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: >-
            Represents the numeric category mapping of the stringValue. If no
            config is linked, defaults to 0.
        stringValue:
          type: string
          description: >-
            The string representation of the score value. If no config is
            linked, can be any string. Otherwise, must map to a config category
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    CorrectionScore:
      title: CorrectionScore
      type: object
      properties:
        value:
          type: number
          format: double
          description: The numeric value of the score. Always 0 for correction scores.
        stringValue:
          type: string
          description: The string representation of the correction content
      required:
        - value
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    TextScore:
      title: TextScore
      type: object
      properties:
        stringValue:
          type: string
          description: The text content of the score (1-500 characters)
      required:
        - stringValue
      allOf:
        - $ref: '#/components/schemas/BaseScore'
    Score:
      title: Score
      type: object
      properties:
        dataType:
          type: string
          enum:
            - NUMERIC
            - CATEGORICAL
            - BOOLEAN
            - CORRECTION
            - TEXT
        value:
          type: string
          description: The numeric value of the score
        stringValue:
          type: string
          description: The string representation of the score value. If no config is
            linked, can be any string. Otherwise, must map to a config category
      required:
        - dataType
    CreateScoreValue:
      title: CreateScoreValue
      oneOf:
        - type: number
          format: double
        - type: string
      description: >-
        The value of the score. Must be passed as string for categorical and
        text scores, and numeric for boolean and numeric scores
    Comment:
      title: Comment
      type: object
      properties:
        id:
          type: string
        projectId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        objectType:
          $ref: '#/components/schemas/CommentObjectType'
        objectId:
          type: string
        content:
          type: string
        authorUserId:
          type: string
          nullable: true
          description: The user ID of the comment author
      required:
        - id
        - projectId
        - createdAt
        - updatedAt
        - objectType
        - objectId
        - content
    Dataset:
      title: Dataset
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
          description: Description of the dataset
        metadata:
          description: Metadata associated with the dataset
        inputSchema:
          nullable: true
          description: JSON Schema for validating dataset item inputs
        expectedOutputSchema:
          nullable: true
          description: JSON Schema for validating dataset item expected outputs
        projectId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - metadata
        - projectId
        - createdAt
        - updatedAt
    DatasetItem:
      title: DatasetItem
      type: object
      properties:
        id:
          type: string
        status:
          $ref: '#/components/schemas/DatasetStatus'
        input:
          description: Input data for the dataset item
        expectedOutput:
          description: Expected output for the dataset item
        metadata:
          description: Metadata associated with the dataset item
        sourceTraceId:
          type: string
          nullable: true
          description: The trace ID that sourced this dataset item
        sourceObservationId:
          type: string
          nullable: true
          description: The observation ID that sourced this dataset item
        datasetId:
          type: string
        datasetName:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - status
        - input
        - expectedOutput
        - metadata
        - datasetId
        - datasetName
        - createdAt
        - updatedAt
    DatasetRunItem:
      title: DatasetRunItem
      type: object
      properties:
        id:
          type: string
        datasetRunId:
          type: string
        datasetRunName:
          type: string
        datasetItemId:
          type: string
        traceId:
          type: string
        observationId:
          type: string
          nullable: true
          description: The observation ID associated with this run item
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - datasetRunId
        - datasetRunName
        - datasetItemId
        - traceId
        - createdAt
        - updatedAt
    DatasetRun:
      title: DatasetRun
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the dataset run
        name:
          type: string
          description: Name of the dataset run
        description:
          type: string
          nullable: true
          description: Description of the run
        metadata:
          description: Metadata of the dataset run
        datasetId:
          type: string
          description: Id of the associated dataset
        datasetName:
          type: string
          description: Name of the associated dataset
        createdAt:
          type: string
          format: date-time
          description: The date and time when the dataset run was created
        updatedAt:
          type: string
          format: date-time
          description: The date and time when the dataset run was last updated
      required:
        - id
        - name
        - metadata
        - datasetId
        - datasetName
        - createdAt
        - updatedAt
    DatasetRunWithItems:
      title: DatasetRunWithItems
      type: object
      properties:
        datasetRunItems:
          type: array
          items:
            $ref: '#/components/schemas/DatasetRunItem'
      required:
        - datasetRunItems
      allOf:
        - $ref: '#/components/schemas/DatasetRun'
    Model:
      title: Model
      type: object
      description: >-
        Model definition used for transforming usage into USD cost and/or
        tokenization.


        Models can have either simple flat pricing or tiered pricing:

        - Flat pricing: Single price per usage type (legacy, but still
        supported)

        - Tiered pricing: Multiple pricing tiers with conditional matching based
        on usage patterns


        The pricing tiers approach is recommended for models with usage-based
        pricing variations.

        When using tiered pricing, the flat price fields (inputPrice,
        outputPrice, prices) are populated

        from the default tier for backward compatibility.
      properties:
        id:
          type: string
        modelName:
          type: string
          description: >-
            Name of the model definition. If multiple with the same name exist,
            they are applied in the following order: (1) custom over built-in,
            (2) newest according to startTime where
            model.startTime<observation.startTime
        matchPattern:
          type: string
          description: >-
            Regex pattern which matches this model definition to
            generation.model. Useful in case of fine-tuned models. If you want
            to exact match, use `(?i)^modelname$`
        startDate:
          type: string
          format: date-time
          nullable: true
          description: Apply only to generations which are newer than this ISO date.
        unit:
          $ref: '#/components/schemas/ModelUsageUnit'
          nullable: true
          description: Unit used by this model.
        inputPrice:
          type: number
          format: double
          nullable: true
          description: Deprecated. See 'prices' instead. Price (USD) per input unit
        outputPrice:
          type: number
          format: double
          nullable: true
          description: Deprecated. See 'prices' instead. Price (USD) per output unit
        totalPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot
            be set if input or output price is set.
        tokenizerId:
          type: string
          nullable: true
          description: >-
            Optional. Tokenizer to be applied to observations which match to
            this model. See docs for more details.
        tokenizerConfig:
          description: >-
            Optional. Configuration for the selected tokenizer. Needs to be
            JSON. See docs for more details.
        isLangfuseManaged:
          type: boolean
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the model was created
        prices:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ModelPrice'
          description: >-
            Deprecated. Use 'pricingTiers' instead for models with usage-based
            pricing variations.


            This field shows prices by usage type from the default pricing tier.
            Maintained for backward compatibility.

            If the model uses tiered pricing, this field will be populated from
            the default tier's prices.
        pricingTiers:
          type: array
          items:
            $ref: '#/components/schemas/PricingTier'
          description: >-
            Array of pricing tiers with conditional pricing based on usage
            thresholds.


            Pricing tiers enable accurate cost tracking for models that charge
            different rates based on usage patterns

            (e.g., different rates for high-volume usage, large context windows,
            or cached tokens).


            Each model must have exactly one default tier (isDefault=true,
            priority=0) that serves as a fallback.

            Additional conditional tiers can be defined with specific matching
            criteria.


            If this array is empty, the model uses legacy flat pricing from the
            inputPrice/outputPrice/totalPrice fields.
      required:
        - id
        - modelName
        - matchPattern
        - tokenizerConfig
        - isLangfuseManaged
        - createdAt
        - prices
        - pricingTiers
    ModelPrice:
      title: ModelPrice
      type: object
      properties:
        price:
          type: number
          format: double
      required:
        - price
    PricingTierCondition:
      title: PricingTierCondition
      type: object
      description: >-
        Condition for matching a pricing tier based on usage details. Used to
        implement tiered pricing models where costs vary based on usage
        thresholds.


        How it works:

        1. The regex pattern matches against usage detail keys (e.g.,
        "input_tokens", "input_cached")

        2. Values of all matching keys are summed together

        3. The sum is compared against the threshold value using the specified
        operator

        4. All conditions in a tier must be met (AND logic) for the tier to
        match


        Common use cases:

        - Threshold-based pricing: Match when accumulated usage exceeds a
        certain amount

        - Usage-type-specific pricing: Different rates for cached vs non-cached
        tokens, or input vs output

        - Volume-based pricing: Different rates based on total request or token
        count
      properties:
        usageDetailPattern:
          type: string
          description: >-
            Regex pattern to match against usage detail keys. All matching keys'
            values are summed for threshold comparison.


            Examples:

            - "^input" matches "input", "input_tokens", "input_cached", etc.

            - "^(input|prompt)" matches both "input_tokens" and "prompt_tokens"

            - "_cache$" matches "input_cache", "output_cache", etc.


            The pattern is case-insensitive by default. If no keys match, the
            sum is treated as zero.
        operator:
          $ref: '#/components/schemas/PricingTierOperator'
          description: >-
            Comparison operator to apply between the summed value and the
            threshold.


            - gt: greater than (sum > threshold)

            - gte: greater than or equal (sum >= threshold)

            - lt: less than (sum < threshold)

            - lte: less than or equal (sum <= threshold)

            - eq: equal (sum == threshold)

            - neq: not equal (sum != threshold)
        value:
          type: number
          format: double
          description: >-
            Threshold value for comparison. For token-based pricing, this is
            typically the token count threshold (e.g., 200000 for a 200K token
            threshold).
        caseSensitive:
          type: boolean
          description: >-
            Whether the regex pattern matching is case-sensitive. Default is
            false (case-insensitive matching).
      required:
        - usageDetailPattern
        - operator
        - value
        - caseSensitive
    PricingTier:
      title: PricingTier
      type: object
      description: >-
        Pricing tier definition with conditional pricing based on usage
        thresholds.


        Pricing tiers enable accurate cost tracking for LLM providers that
        charge different rates based on usage patterns.

        For example, some providers charge higher rates when context size
        exceeds certain thresholds.


        How tier matching works:

        1. Tiers are evaluated in ascending priority order (priority 1 before
        priority 2, etc.)

        2. The first tier where ALL conditions match is selected

        3. If no conditional tiers match, the default tier is used as a fallback

        4. The default tier has priority 0 and no conditions


        Why priorities matter:

        - Lower priority numbers are evaluated first, allowing you to define
        specific cases before general ones

        - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
        "medium usage" (>100K tokens), Priority 0 for default

        - Without proper ordering, a less specific condition might match before
        a more specific one


        Every model must have exactly one default tier to ensure cost
        calculation always succeeds.
      properties:
        id:
          type: string
          description: Unique identifier for the pricing tier
        name:
          type: string
          description: >-
            Name of the pricing tier for display and identification purposes.


            Examples: "Standard", "High Volume Tier", "Large Context", "Extended
            Context Tier"
        isDefault:
          type: boolean
          description: >-
            Whether this is the default tier. Every model must have exactly one
            default tier with priority 0 and no conditions.


            The default tier serves as a fallback when no conditional tiers
            match, ensuring cost calculation always succeeds.

            It typically represents the base pricing for standard usage
            patterns.
        priority:
          type: integer
          description: >-
            Priority for tier matching evaluation. Lower numbers = higher
            priority (evaluated first).


            The default tier must always have priority 0. Conditional tiers
            should have priority 1, 2, 3, etc.


            Example ordering:

            - Priority 0: Default tier (no conditions, always matches as
            fallback)

            - Priority 1: High usage tier (e.g., >200K tokens)

            - Priority 2: Medium usage tier (e.g., >100K tokens)


            This ensures more specific conditions are checked before general
            ones.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierCondition'
          description: >-
            Array of conditions that must ALL be met for this tier to match (AND
            logic).


            The default tier must have an empty conditions array. Conditional
            tiers should have one or more conditions

            that define when this tier's pricing applies.


            Multiple conditions enable complex matching scenarios (e.g., "high
            input tokens AND low output tokens").
        prices:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Prices (USD) by usage type for this tier.


            Common usage types: "input", "output", "total", "request", "image"

            Prices are specified in USD per unit (e.g., per token, per request,
            per second).


            Example: {"input": 0.000003, "output": 0.000015} means $3 per
            million input tokens and $15 per million output tokens.
      required:
        - id
        - name
        - isDefault
        - priority
        - conditions
        - prices
    PricingTierInput:
      title: PricingTierInput
      type: object
      description: >-
        Input schema for creating a pricing tier. The tier ID will be
        automatically generated server-side.


        When creating a model with pricing tiers:

        - Exactly one tier must have isDefault=true (the fallback tier)

        - The default tier must have priority=0 and conditions=[]

        - All tier names and priorities must be unique within the model

        - Each tier must define at least one price


        See PricingTier for detailed information about how tiers work and why
        they're useful.
      properties:
        name:
          type: string
          description: >-
            Name of the pricing tier for display and identification purposes.


            Must be unique within the model. Common patterns: "Standard", "High
            Volume Tier", "Extended Context"
        isDefault:
          type: boolean
          description: >-
            Whether this is the default tier. Exactly one tier per model must be
            marked as default.


            Requirements for default tier:

            - Must have isDefault=true

            - Must have priority=0

            - Must have empty conditions array (conditions=[])


            The default tier acts as a fallback when no conditional tiers match.
        priority:
          type: integer
          description: >-
            Priority for tier matching evaluation. Lower numbers = higher
            priority (evaluated first).


            Must be unique within the model. The default tier must have
            priority=0.

            Conditional tiers should use priority 1, 2, 3, etc. based on their
            specificity.
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierCondition'
          description: >-
            Array of conditions that must ALL be met for this tier to match (AND
            logic).


            The default tier must have an empty array (conditions=[]).

            Conditional tiers should define one or more conditions that specify
            when this tier's pricing applies.


            Each condition specifies a regex pattern, operator, and threshold
            value for matching against usage details.
        prices:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Prices (USD) by usage type for this tier. At least one price must be
            defined.


            Common usage types: "input", "output", "total", "request", "image"

            Prices are in USD per unit (e.g., per token).


            Example: {"input": 0.000003, "output": 0.000015} represents $3 per
            million input tokens and $15 per million output tokens.
      required:
        - name
        - isDefault
        - priority
        - conditions
        - prices
    PricingTierOperator:
      title: PricingTierOperator
      type: string
      enum:
        - gt
        - gte
        - lt
        - lte
        - eq
        - neq
      description: Comparison operators for pricing tier conditions
    ModelUsageUnit:
      title: ModelUsageUnit
      type: string
      enum:
        - CHARACTERS
        - TOKENS
        - MILLISECONDS
        - SECONDS
        - IMAGES
        - REQUESTS
      description: Unit of usage in Langfuse
    ObservationLevel:
      title: ObservationLevel
      type: string
      enum:
        - DEBUG
        - DEFAULT
        - WARNING
        - ERROR
    MapValue:
      title: MapValue
      oneOf:
        - type: string
          nullable: true
        - type: integer
          nullable: true
        - type: integer
          format: float
          nullable: true
        - type: boolean
          nullable: true
        - type: array
          items:
            type: string
          nullable: true
    CommentObjectType:
      title: CommentObjectType
      type: string
      enum:
        - TRACE
        - OBSERVATION
        - SESSION
        - PROMPT
    DatasetStatus:
      title: DatasetStatus
      type: string
      enum:
        - ACTIVE
        - ARCHIVED
    ScoreSource:
      title: ScoreSource
      type: string
      enum:
        - ANNOTATION
        - API
        - EVAL
    ScoreConfigDataType:
      title: ScoreConfigDataType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
        - TEXT
    ScoreDataType:
      title: ScoreDataType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
        - CORRECTION
        - TEXT
    DeleteDatasetItemResponse:
      title: DeleteDatasetItemResponse
      type: object
      properties:
        message:
          type: string
          description: Success message after deletion
      required:
        - message
    CreateDatasetItemRequest:
      title: CreateDatasetItemRequest
      type: object
      properties:
        datasetName:
          type: string
        input:
          nullable: true
        expectedOutput:
          nullable: true
        metadata:
          nullable: true
        sourceTraceId:
          type: string
          nullable: true
        sourceObservationId:
          type: string
          nullable: true
        id:
          type: string
          nullable: true
          description: >-
            Dataset items are upserted on their id. Id needs to be unique
            (project-level) and cannot be reused across datasets.
        status:
          $ref: '#/components/schemas/DatasetStatus'
          nullable: true
          description: Defaults to ACTIVE for newly created items
      required:
        - datasetName
    PaginatedDatasetItems:
      title: PaginatedDatasetItems
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DatasetItem'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateDatasetRunItemRequest:
      title: CreateDatasetRunItemRequest
      type: object
      properties:
        runName:
          type: string
        runDescription:
          type: string
          nullable: true
          description: Description of the run. If run exists, description will be updated.
        metadata:
          nullable: true
          description: Metadata of the dataset run, updates run if run already exists
        datasetItemId:
          type: string
        observationId:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
          description: >-
            traceId should always be provided. For compatibility with older SDK
            versions it can also be inferred from the provided observationId.
        datasetVersion:
          type: string
          format: date-time
          nullable: true
          description: >-
            ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
            "2026-01-21T14:35:42Z").

            Specifies the dataset version to use for this experiment run. 

            If provided, the experiment will use dataset items as they existed
            at or before this timestamp.

            If not provided, uses the latest version of dataset items.
        createdAt:
          type: string
          format: date-time
          nullable: true
          description: >-
            Optional timestamp to set the createdAt field of the dataset run
            item. If not provided or null, defaults to current timestamp.
      required:
        - runName
        - datasetItemId
    PaginatedDatasetRunItems:
      title: PaginatedDatasetRunItems
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DatasetRunItem'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PaginatedDatasets:
      title: PaginatedDatasets
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Dataset'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateDatasetRequest:
      title: CreateDatasetRequest
      type: object
      properties:
        name:
          type: string
        description:
          type: string
          nullable: true
        metadata:
          nullable: true
        inputSchema:
          nullable: true
          description: >-
            JSON Schema for validating dataset item inputs. When set, all new
            and existing dataset items will be validated against this schema.
        expectedOutputSchema:
          nullable: true
          description: >-
            JSON Schema for validating dataset item expected outputs. When set,
            all new and existing dataset items will be validated against this
            schema.
      required:
        - name
    PaginatedDatasetRuns:
      title: PaginatedDatasetRuns
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DatasetRun'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    DeleteDatasetRunResponse:
      title: DeleteDatasetRunResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    HealthResponse:
      title: HealthResponse
      type: object
      properties:
        version:
          type: string
          description: Langfuse server version
          example: 1.25.0
        status:
          type: string
          example: OK
      required:
        - version
        - status
    IngestionEvent:
      title: IngestionEvent
      type: object
      properties:
        type:
          type: string
          enum:
            - trace-create
            - score-create
            - span-create
            - span-update
            - generation-create
            - generation-update
            - event-create
            - sdk-log
            - observation-create
            - observation-update
        body:
          type: string
      required:
        - type
        - body
    ObservationType:
      title: ObservationType
      type: string
      enum:
        - SPAN
        - GENERATION
        - EVENT
        - AGENT
        - TOOL
        - CHAIN
        - RETRIEVER
        - EVALUATOR
        - EMBEDDING
        - GUARDRAIL
    IngestionUsage:
      title: IngestionUsage
      oneOf:
        - $ref: '#/components/schemas/Usage'
        - $ref: '#/components/schemas/OpenAIUsage'
    OpenAIUsage:
      title: OpenAIUsage
      type: object
      description: Usage interface of OpenAI for improved compatibility.
      properties:
        promptTokens:
          type: integer
          nullable: true
        completionTokens:
          type: integer
          nullable: true
        totalTokens:
          type: integer
          nullable: true
    OptionalObservationBody:
      title: OptionalObservationBody
      type: object
      properties:
        traceId:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        startTime:
          type: string
          format: date-time
          nullable: true
        metadata:
          nullable: true
        input:
          nullable: true
        output:
          nullable: true
        level:
          $ref: '#/components/schemas/ObservationLevel'
          nullable: true
        statusMessage:
          type: string
          nullable: true
        parentObservationId:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        environment:
          type: string
          nullable: true
    CreateEventBody:
      title: CreateEventBody
      type: object
      properties:
        id:
          type: string
          nullable: true
      allOf:
        - $ref: '#/components/schemas/OptionalObservationBody'
    UpdateEventBody:
      title: UpdateEventBody
      type: object
      properties:
        id:
          type: string
      required:
        - id
      allOf:
        - $ref: '#/components/schemas/OptionalObservationBody'
    CreateSpanBody:
      title: CreateSpanBody
      type: object
      properties:
        endTime:
          type: string
          format: date-time
          nullable: true
      allOf:
        - $ref: '#/components/schemas/CreateEventBody'
    UpdateSpanBody:
      title: UpdateSpanBody
      type: object
      properties:
        endTime:
          type: string
          format: date-time
          nullable: true
      allOf:
        - $ref: '#/components/schemas/UpdateEventBody'
    CreateGenerationBody:
      title: CreateGenerationBody
      type: object
      properties:
        completionStartTime:
          type: string
          format: date-time
          nullable: true
        model:
          type: string
          nullable: true
        modelParameters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
          nullable: true
        usage:
          $ref: '#/components/schemas/IngestionUsage'
          nullable: true
        usageDetails:
          $ref: '#/components/schemas/UsageDetails'
          nullable: true
        costDetails:
          type: object
          additionalProperties:
            type: number
            format: double
          nullable: true
        promptName:
          type: string
          nullable: true
        promptVersion:
          type: integer
          nullable: true
      allOf:
        - $ref: '#/components/schemas/CreateSpanBody'
    UpdateGenerationBody:
      title: UpdateGenerationBody
      type: object
      properties:
        completionStartTime:
          type: string
          format: date-time
          nullable: true
        model:
          type: string
          nullable: true
        modelParameters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
          nullable: true
        usage:
          $ref: '#/components/schemas/IngestionUsage'
          nullable: true
        promptName:
          type: string
          nullable: true
        usageDetails:
          $ref: '#/components/schemas/UsageDetails'
          nullable: true
        costDetails:
          type: object
          additionalProperties:
            type: number
            format: double
          nullable: true
        promptVersion:
          type: integer
          nullable: true
      allOf:
        - $ref: '#/components/schemas/UpdateSpanBody'
    ObservationBody:
      title: ObservationBody
      type: object
      properties:
        id:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        type:
          $ref: '#/components/schemas/ObservationType'
        name:
          type: string
          nullable: true
        startTime:
          type: string
          format: date-time
          nullable: true
        endTime:
          type: string
          format: date-time
          nullable: true
        completionStartTime:
          type: string
          format: date-time
          nullable: true
        model:
          type: string
          nullable: true
        modelParameters:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MapValue'
          nullable: true
        input:
          nullable: true
        version:
          type: string
          nullable: true
        metadata:
          nullable: true
        output:
          nullable: true
        usage:
          $ref: '#/components/schemas/Usage'
          nullable: true
        level:
          $ref: '#/components/schemas/ObservationLevel'
          nullable: true
        statusMessage:
          type: string
          nullable: true
        parentObservationId:
          type: string
          nullable: true
        environment:
          type: string
          nullable: true
      required:
        - type
    TraceBody:
      title: TraceBody
      type: object
      properties:
        id:
          type: string
          nullable: true
        timestamp:
          type: string
          format: date-time
          nullable: true
        name:
          type: string
          nullable: true
        userId:
          type: string
          nullable: true
        input:
          nullable: true
        output:
          nullable: true
        sessionId:
          type: string
          nullable: true
        release:
          type: string
          nullable: true
        version:
          type: string
          nullable: true
        metadata:
          nullable: true
        tags:
          type: array
          items:
            type: string
          nullable: true
        environment:
          type: string
          nullable: true
        public:
          type: boolean
          nullable: true
          description: Make trace publicly accessible via url
    SDKLogBody:
      title: SDKLogBody
      type: object
      properties:
        log: {}
      required:
        - log
    ScoreBody:
      title: ScoreBody
      type: object
      properties:
        id:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
        observationId:
          type: string
          nullable: true
        datasetRunId:
          type: string
          nullable: true
        name:
          type: string
          description: >-
            The name of the score. Always overrides "output" for correction
            scores.
          example: novelty
        environment:
          type: string
          nullable: true
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        value:
          $ref: '#/components/schemas/CreateScoreValue'
          description: >-
            The value of the score. Must be passed as string for categorical and
            text scores, and numeric for boolean and numeric scores. Boolean
            score values must equal either 1 or 0 (true or false). Text score
            values must be between 1 and 500 characters.
        comment:
          type: string
          nullable: true
        metadata:
          nullable: true
        dataType:
          $ref: '#/components/schemas/ScoreDataType'
          nullable: true
          description: >-
            When set, must match the score value's type. If not set, will be
            inferred from the score value or config
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. When set, the score name must
            equal the config name and scores must comply with the config's range
            and data type. For categorical scores, the value must map to a
            config category. Numeric scores might be constrained by the score
            config's max and min values
      required:
        - name
        - value
    BaseEvent:
      title: BaseEvent
      type: object
      properties:
        id:
          type: string
          description: UUID v4 that identifies the event
        timestamp:
          type: string
          description: >-
            Datetime (ISO 8601) of event creation in client. Should be as close
            to actual event creation in client as possible, this timestamp will
            be used for ordering of events in future release. Resolution:
            milliseconds (required), microseconds (optimal).
        metadata:
          nullable: true
          description: Optional. Metadata field used by the Langfuse SDKs for debugging.
      required:
        - id
        - timestamp
    TraceEvent:
      title: TraceEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/TraceBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    CreateObservationEvent:
      title: CreateObservationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ObservationBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    UpdateObservationEvent:
      title: UpdateObservationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ObservationBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    ScoreEvent:
      title: ScoreEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/ScoreBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    SDKLogEvent:
      title: SDKLogEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/SDKLogBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    CreateGenerationEvent:
      title: CreateGenerationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateGenerationBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    UpdateGenerationEvent:
      title: UpdateGenerationEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/UpdateGenerationBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    CreateSpanEvent:
      title: CreateSpanEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateSpanBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    UpdateSpanEvent:
      title: UpdateSpanEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/UpdateSpanBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    CreateEventEvent:
      title: CreateEventEvent
      type: object
      properties:
        body:
          $ref: '#/components/schemas/CreateEventBody'
      required:
        - body
      allOf:
        - $ref: '#/components/schemas/BaseEvent'
    IngestionSuccess:
      title: IngestionSuccess
      type: object
      properties:
        id:
          type: string
        status:
          type: integer
      required:
        - id
        - status
    IngestionError:
      title: IngestionError
      type: object
      properties:
        id:
          type: string
        status:
          type: integer
        message:
          type: string
          nullable: true
        error:
          nullable: true
      required:
        - id
        - status
    IngestionResponse:
      title: IngestionResponse
      type: object
      properties:
        successes:
          type: array
          items:
            $ref: '#/components/schemas/IngestionSuccess'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/IngestionError'
      required:
        - successes
        - errors
    OpenAICompletionUsageSchema:
      title: OpenAICompletionUsageSchema
      type: object
      description: OpenAI Usage schema from (Chat-)Completion APIs
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
        prompt_tokens_details:
          type: object
          additionalProperties:
            type: integer
            nullable: true
          nullable: true
        completion_tokens_details:
          type: object
          additionalProperties:
            type: integer
            nullable: true
          nullable: true
      required:
        - prompt_tokens
        - completion_tokens
        - total_tokens
    OpenAIResponseUsageSchema:
      title: OpenAIResponseUsageSchema
      type: object
      description: OpenAI Usage schema from Response API
      properties:
        input_tokens:
          type: integer
        output_tokens:
          type: integer
        total_tokens:
          type: integer
        input_tokens_details:
          type: object
          additionalProperties:
            type: integer
            nullable: true
          nullable: true
        output_tokens_details:
          type: object
          additionalProperties:
            type: integer
            nullable: true
          nullable: true
      required:
        - input_tokens
        - output_tokens
        - total_tokens
    UsageDetails:
      title: UsageDetails
      oneOf:
        - type: object
          additionalProperties:
            type: integer
        - $ref: '#/components/schemas/OpenAICompletionUsageSchema'
        - $ref: '#/components/schemas/OpenAIResponseUsageSchema'
    legacyMetricsResponse:
      title: legacyMetricsResponse
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The metrics data. Each item in the list contains the metric values
            and dimensions requested in the query.

            Format varies based on the query parameters.

            Histograms will return an array with [lower, upper, height] tuples.
      required:
        - data
    legacyObservations:
      title: legacyObservations
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Observation'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    legacyObservationsViews:
      title: legacyObservationsViews
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ObservationsView'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    legacyCreateScoreRequest:
      title: legacyCreateScoreRequest
      type: object
      properties:
        id:
          type: string
          nullable: true
        traceId:
          type: string
          nullable: true
        sessionId:
          type: string
          nullable: true
        observationId:
          type: string
          nullable: true
        datasetRunId:
          type: string
          nullable: true
        name:
          type: string
          example: novelty
        value:
          $ref: '#/components/schemas/CreateScoreValue'
          description: >-
            The value of the score. Must be passed as string for categorical and
            text scores, and numeric for boolean and numeric scores. Boolean
            score values must equal either 1 or 0 (true or false). Text score
            values must be between 1 and 500 characters.
        comment:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        environment:
          type: string
          nullable: true
          description: >-
            The environment of the score. Can be any lowercase alphanumeric
            string with hyphens and underscores that does not start with
            'langfuse'.
        queueId:
          type: string
          nullable: true
          description: >-
            The annotation queue referenced by the score. Indicates if score was
            initially created while processing annotation queue.
        dataType:
          $ref: '#/components/schemas/ScoreDataType'
          nullable: true
          description: >-
            The data type of the score. When passing a configId this field is
            inferred. Otherwise, this field must be passed or will default to
            numeric.
        configId:
          type: string
          nullable: true
          description: >-
            Reference a score config on a score. The unique langfuse identifier
            of a score config. When passing this field, the dataType and
            stringValue fields are automatically populated.
        source:
          $ref: '#/components/schemas/legacyCreateScoreSource'
          nullable: true
          description: >-
            The source of the score. Defaults to API. Set to ANNOTATION to
            prefill scores (e.g. from an LLM) for a human reviewer to verify in
            an annotation queue. When source is ANNOTATION, a configId is
            required unless dataType is CORRECTION. EVAL is reserved for
            internal evaluator outputs and is not accepted on this endpoint.
      required:
        - name
        - value
    legacyCreateScoreSource:
      title: legacyCreateScoreSource
      type: string
      enum:
        - API
        - ANNOTATION
      description: |-
        Source values accepted when creating a score via the public REST API.
        EVAL is reserved for internal evaluator outputs and is intentionally not
        exposed here — use commons.ScoreSource when reading scores.
    legacyCreateScoreResponse:
      title: legacyCreateScoreResponse
      type: object
      properties:
        id:
          type: string
          description: The id of the created object in Langfuse
      required:
        - id
    LlmConnection:
      title: LlmConnection
      type: object
      description: LLM API connection configuration (secrets excluded)
      properties:
        id:
          type: string
        provider:
          type: string
          description: >-
            Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
            project, used for upserting.
        adapter:
          type: string
          description: The adapter used to interface with the LLM
        displaySecretKey:
          type: string
          description: Masked version of the secret key for display purposes
        baseURL:
          type: string
          nullable: true
          description: Custom base URL for the LLM API
        customModels:
          type: array
          items:
            type: string
          description: List of custom model names available for this connection
        withDefaultModels:
          type: boolean
          description: Whether to include default models for this adapter
        extraHeaderKeys:
          type: array
          items:
            type: string
          description: >-
            Keys of extra headers sent with requests (values excluded for
            security)
        config:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Adapter-specific configuration. Required for Bedrock
            (`{"region":"us-east-1"}`), optional for VertexAI
            (`{"location":"us-central1"}`), not used by other adapters.
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - provider
        - adapter
        - displaySecretKey
        - customModels
        - withDefaultModels
        - extraHeaderKeys
        - createdAt
        - updatedAt
    PaginatedLlmConnections:
      title: PaginatedLlmConnections
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/LlmConnection'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    UpsertLlmConnectionRequest:
      title: UpsertLlmConnectionRequest
      type: object
      description: Request to create or update an LLM connection (upsert)
      properties:
        provider:
          type: string
          description: >-
            Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
            project, used for upserting.
        adapter:
          $ref: '#/components/schemas/LlmAdapter'
          description: The adapter used to interface with the LLM
        secretKey:
          type: string
          description: Secret key for the LLM API.
        baseURL:
          type: string
          nullable: true
          description: Custom base URL for the LLM API
        customModels:
          type: array
          items:
            type: string
          nullable: true
          description: List of custom model names
        withDefaultModels:
          type: boolean
          nullable: true
          description: Whether to include default models. Default is true.
        extraHeaders:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Extra headers to send with requests
        config:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Adapter-specific configuration. Validation rules: - **Bedrock**:
            Required. Must be `{"region": "<aws-region>"}` (e.g.,
            `{"region":"us-east-1"}`) - **VertexAI**: Optional. If provided,
            must be `{"location": "<gcp-location>"}` (e.g.,
            `{"location":"us-central1"}`) - **Other adapters**: Not supported.
            Omit this field or set to null.
      required:
        - provider
        - adapter
        - secretKey
    DeleteLlmConnectionResponse:
      title: DeleteLlmConnectionResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    LlmAdapter:
      title: LlmAdapter
      type: string
      enum:
        - anthropic
        - openai
        - azure
        - bedrock
        - google-vertex-ai
        - google-ai-studio
    GetMediaResponse:
      title: GetMediaResponse
      type: object
      properties:
        mediaId:
          type: string
          description: The unique langfuse identifier of a media record
        contentType:
          type: string
          description: The MIME type of the media record
        contentLength:
          type: integer
          description: The size of the media record in bytes
        uploadedAt:
          type: string
          format: date-time
          description: The date and time when the media record was uploaded
        url:
          type: string
          description: The download URL of the media record
        urlExpiry:
          type: string
          description: The expiry date and time of the media record download URL
      required:
        - mediaId
        - contentType
        - contentLength
        - uploadedAt
        - url
        - urlExpiry
    PatchMediaBody:
      title: PatchMediaBody
      type: object
      properties:
        uploadedAt:
          type: string
          format: date-time
          description: The date and time when the media record was uploaded
        uploadHttpStatus:
          type: integer
          description: The HTTP status code of the upload
        uploadHttpError:
          type: string
          nullable: true
          description: The HTTP error message of the upload
        uploadTimeMs:
          type: integer
          nullable: true
          description: The time in milliseconds it took to upload the media record
      required:
        - uploadedAt
        - uploadHttpStatus
    GetMediaUploadUrlRequest:
      title: GetMediaUploadUrlRequest
      type: object
      properties:
        traceId:
          type: string
          description: The trace ID associated with the media record
        observationId:
          type: string
          nullable: true
          description: >-
            The observation ID associated with the media record. If the media
            record is associated directly with a trace, this will be null.
        contentType:
          $ref: '#/components/schemas/MediaContentType'
        contentLength:
          type: integer
          description: The size of the media record in bytes
        sha256Hash:
          type: string
          description: The SHA-256 hash of the media record
        field:
          type: string
          description: >-
            The trace / observation field the media record is associated with.
            This can be one of `input`, `output`, `metadata`
      required:
        - traceId
        - contentType
        - contentLength
        - sha256Hash
        - field
    GetMediaUploadUrlResponse:
      title: GetMediaUploadUrlResponse
      type: object
      properties:
        uploadUrl:
          type: string
          nullable: true
          description: >-
            The presigned upload URL. If the asset is already uploaded, this
            will be null
        mediaId:
          type: string
          description: The unique langfuse identifier of a media record
      required:
        - mediaId
    MediaContentType:
      title: MediaContentType
      type: string
      enum:
        - image/png
        - image/jpeg
        - image/jpg
        - image/webp
        - image/gif
        - image/svg+xml
        - image/tiff
        - image/bmp
        - image/avif
        - image/heic
        - audio/mpeg
        - audio/mp3
        - audio/wav
        - audio/ogg
        - audio/oga
        - audio/aac
        - audio/mp4
        - audio/flac
        - audio/opus
        - audio/webm
        - video/mp4
        - video/webm
        - video/ogg
        - video/mpeg
        - video/quicktime
        - video/x-msvideo
        - video/x-matroska
        - text/plain
        - text/html
        - text/css
        - text/csv
        - text/markdown
        - text/x-python
        - application/javascript
        - text/x-typescript
        - application/x-yaml
        - application/pdf
        - application/msword
        - application/vnd.ms-excel
        - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
        - application/zip
        - application/json
        - application/xml
        - application/octet-stream
        - >-
          application/vnd.openxmlformats-officedocument.wordprocessingml.document
        - >-
          application/vnd.openxmlformats-officedocument.presentationml.presentation
        - application/rtf
        - application/x-ndjson
        - application/vnd.apache.parquet
        - application/gzip
        - application/x-tar
        - application/x-7z-compressed
      description: The MIME type of the media record
    MetricsV2Response:
      title: MetricsV2Response
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            The metrics data. Each item in the list contains the metric values
            and dimensions requested in the query.

            Format varies based on the query parameters.

            Histograms will return an array with [lower, upper, height] tuples.
      required:
        - data
    PaginatedModels:
      title: PaginatedModels
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Model'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateModelRequest:
      title: CreateModelRequest
      type: object
      properties:
        modelName:
          type: string
          description: >-
            Name of the model definition. If multiple with the same name exist,
            they are applied in the following order: (1) custom over built-in,
            (2) newest according to startTime where
            model.startTime<observation.startTime
        matchPattern:
          type: string
          description: >-
            Regex pattern which matches this model definition to
            generation.model. Useful in case of fine-tuned models. If you want
            to exact match, use `(?i)^modelname$`
        startDate:
          type: string
          format: date-time
          nullable: true
          description: Apply only to generations which are newer than this ISO date.
        unit:
          $ref: '#/components/schemas/ModelUsageUnit'
          nullable: true
          description: Unit used by this model.
        inputPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit.
            Creates a default tier if pricingTiers not provided.
        outputPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit.
            Creates a default tier if pricingTiers not provided.
        totalPrice:
          type: number
          format: double
          nullable: true
          description: >-
            Deprecated. Use 'pricingTiers' instead. Price (USD) per total units.
            Cannot be set if input or output price is set. Creates a default
            tier if pricingTiers not provided.
        pricingTiers:
          type: array
          items:
            $ref: '#/components/schemas/PricingTierInput'
          nullable: true
          description: >-
            Optional. Array of pricing tiers for this model.


            Use pricing tiers for all models - both those with threshold-based
            pricing variations and those with simple flat pricing:


            - For models with standard flat pricing: Create a single default
            tier with your prices
              (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices)

            - For models with threshold-based pricing: Create a default tier
            plus additional conditional tiers
              (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds)

            Requirements:

            - Cannot be provided with flat prices
            (inputPrice/outputPrice/totalPrice) - use one approach or the other

            - Must include exactly one default tier with isDefault=true,
            priority=0, and conditions=[]

            - All tier names and priorities must be unique within the model

            - Each tier must define at least one price


            If omitted, you must provide flat prices instead
            (inputPrice/outputPrice/totalPrice),

            which will automatically create a single default tier named
            "Standard".
        tokenizerId:
          type: string
          nullable: true
          description: >-
            Optional. Tokenizer to be applied to observations which match to
            this model. See docs for more details.
        tokenizerConfig:
          nullable: true
          description: >-
            Optional. Configuration for the selected tokenizer. Needs to be
            JSON. See docs for more details.
      required:
        - modelName
        - matchPattern
    ObservationsV2Response:
      title: ObservationsV2Response
      type: object
      description: >-
        Response containing observations with field-group-based filtering and
        cursor-based pagination.


        The `data` array contains observation objects with only the requested
        field groups included.

        Use the `cursor` in `meta` to retrieve the next page of results.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ObservationV2'
          description: >-
            Array of observation objects. Fields included depend on the `fields`
            parameter in the request.
        meta:
          $ref: '#/components/schemas/ObservationsV2Meta'
      required:
        - data
        - meta
    ObservationsV2Meta:
      title: ObservationsV2Meta
      type: object
      description: Metadata for cursor-based pagination
      properties:
        cursor:
          type: string
          nullable: true
          description: >-
            Base64-encoded cursor to use for retrieving the next page. If not
            present, there are no more results.
    OtelResourceSpan:
      title: OtelResourceSpan
      type: object
      description: >-
        Represents a collection of spans from a single resource as per OTLP
        specification
      properties:
        resource:
          $ref: '#/components/schemas/OtelResource'
          nullable: true
          description: Resource information
        scopeSpans:
          type: array
          items:
            $ref: '#/components/schemas/OtelScopeSpan'
          nullable: true
          description: Array of scope spans
    OtelResource:
      title: OtelResource
      type: object
      description: Resource attributes identifying the source of telemetry
      properties:
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: Resource attributes like service.name, service.version, etc.
    OtelScopeSpan:
      title: OtelScopeSpan
      type: object
      description: Collection of spans from a single instrumentation scope
      properties:
        scope:
          $ref: '#/components/schemas/OtelScope'
          nullable: true
          description: Instrumentation scope information
        spans:
          type: array
          items:
            $ref: '#/components/schemas/OtelSpan'
          nullable: true
          description: Array of spans
    OtelScope:
      title: OtelScope
      type: object
      description: Instrumentation scope information
      properties:
        name:
          type: string
          nullable: true
          description: Instrumentation scope name
        version:
          type: string
          nullable: true
          description: Instrumentation scope version
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: Additional scope attributes
    OtelSpan:
      title: OtelSpan
      type: object
      description: Individual span representing a unit of work or operation
      properties:
        traceId:
          nullable: true
          description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary)
        spanId:
          nullable: true
          description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary)
        parentSpanId:
          nullable: true
          description: Parent span ID if this is a child span
        name:
          type: string
          nullable: true
          description: Span name describing the operation
        kind:
          type: integer
          nullable: true
          description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER)
        startTimeUnixNano:
          nullable: true
          description: Start time in nanoseconds since Unix epoch
        endTimeUnixNano:
          nullable: true
          description: End time in nanoseconds since Unix epoch
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/OtelAttribute'
          nullable: true
          description: >-
            Span attributes including Langfuse-specific attributes
            (langfuse.observation.*)
        status:
          nullable: true
          description: Span status object
    OtelAttribute:
      title: OtelAttribute
      type: object
      description: Key-value attribute pair for resources, scopes, or spans
      properties:
        key:
          type: string
          nullable: true
          description: Attribute key (e.g., "service.name", "langfuse.observation.type")
        value:
          $ref: '#/components/schemas/OtelAttributeValue'
          nullable: true
          description: Attribute value
    OtelAttributeValue:
      title: OtelAttributeValue
      type: object
      description: Attribute value wrapper supporting different value types
      properties:
        stringValue:
          type: string
          nullable: true
          description: String value
        intValue:
          type: integer
          nullable: true
          description: Integer value
        doubleValue:
          type: number
          format: double
          nullable: true
          description: Double value
        boolValue:
          type: boolean
          nullable: true
          description: Boolean value
    OtelTraceResponse:
      title: OtelTraceResponse
      type: object
      description: Response from trace export request. Empty object indicates success.
      properties: {}
    MembershipRole:
      title: MembershipRole
      type: string
      enum:
        - OWNER
        - ADMIN
        - MEMBER
        - VIEWER
    MembershipRequest:
      title: MembershipRequest
      type: object
      properties:
        userId:
          type: string
        role:
          $ref: '#/components/schemas/MembershipRole'
      required:
        - userId
        - role
    DeleteMembershipRequest:
      title: DeleteMembershipRequest
      type: object
      properties:
        userId:
          type: string
      required:
        - userId
    MembershipResponse:
      title: MembershipResponse
      type: object
      properties:
        userId:
          type: string
        role:
          $ref: '#/components/schemas/MembershipRole'
        email:
          type: string
        name:
          type: string
      required:
        - userId
        - role
        - email
        - name
    MembershipDeletionResponse:
      title: MembershipDeletionResponse
      type: object
      properties:
        message:
          type: string
        userId:
          type: string
      required:
        - message
        - userId
    MembershipsResponse:
      title: MembershipsResponse
      type: object
      properties:
        memberships:
          type: array
          items:
            $ref: '#/components/schemas/MembershipResponse'
      required:
        - memberships
    OrganizationProject:
      title: OrganizationProject
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        metadata:
          type: object
          additionalProperties: true
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
        - id
        - name
        - createdAt
        - updatedAt
    OrganizationProjectsResponse:
      title: OrganizationProjectsResponse
      type: object
      properties:
        projects:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationProject'
      required:
        - projects
    OrganizationApiKey:
      title: OrganizationApiKey
      type: object
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          nullable: true
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        note:
          type: string
          nullable: true
        publicKey:
          type: string
        displaySecretKey:
          type: string
      required:
        - id
        - createdAt
        - publicKey
        - displaySecretKey
    OrganizationApiKeysResponse:
      title: OrganizationApiKeysResponse
      type: object
      properties:
        apiKeys:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationApiKey'
      required:
        - apiKeys
    Projects:
      title: Projects
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Project'
      required:
        - data
    Organization:
      title: Organization
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the organization
        name:
          type: string
          description: The name of the organization
      required:
        - id
        - name
    Project:
      title: Project
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        organization:
          $ref: '#/components/schemas/Organization'
          description: The organization this project belongs to
        metadata:
          type: object
          additionalProperties: true
          description: Metadata for the project
        retentionDays:
          type: integer
          nullable: true
          description: >-
            Number of days to retain data. Null or 0 means no retention. Omitted
            if no retention is configured.
      required:
        - id
        - name
        - organization
        - metadata
    ProjectDeletionResponse:
      title: ProjectDeletionResponse
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
      required:
        - success
        - message
    ApiKeyList:
      title: ApiKeyList
      type: object
      description: List of API keys for a project
      properties:
        apiKeys:
          type: array
          items:
            $ref: '#/components/schemas/ApiKeySummary'
      required:
        - apiKeys
    ApiKeySummary:
      title: ApiKeySummary
      type: object
      description: Summary of an API key
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
          nullable: true
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        note:
          type: string
          nullable: true
        publicKey:
          type: string
        displaySecretKey:
          type: string
      required:
        - id
        - createdAt
        - publicKey
        - displaySecretKey
    ApiKeyResponse:
      title: ApiKeyResponse
      type: object
      description: Response for API key creation
      properties:
        id:
          type: string
        createdAt:
          type: string
          format: date-time
        publicKey:
          type: string
        secretKey:
          type: string
        displaySecretKey:
          type: string
        note:
          type: string
          nullable: true
      required:
        - id
        - createdAt
        - publicKey
        - secretKey
        - displaySecretKey
    ApiKeyDeletionResponse:
      title: ApiKeyDeletionResponse
      type: object
      description: Response for API key deletion
      properties:
        success:
          type: boolean
      required:
        - success
    PromptMetaListResponse:
      title: PromptMetaListResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PromptMeta'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PromptMeta:
      title: PromptMeta
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/PromptType'
          description: Indicates whether the prompt is a text or chat prompt.
        versions:
          type: array
          items:
            type: integer
        labels:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
        lastUpdatedAt:
          type: string
          format: date-time
        lastConfig:
          description: >-
            Config object of the most recent prompt version that matches the
            filters (if any are provided)
      required:
        - name
        - type
        - versions
        - labels
        - tags
        - lastUpdatedAt
        - lastConfig
    CreatePromptRequest:
      title: CreatePromptRequest
      oneOf:
        - $ref: '#/components/schemas/CreateChatPromptRequest'
        - $ref: '#/components/schemas/CreateTextPromptRequest'
    CreateChatPromptRequest:
      title: CreateChatPromptRequest
      type: object
      properties:
        name:
          type: string
        prompt:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageWithPlaceholders'
        config:
          nullable: true
        type:
          $ref: '#/components/schemas/CreateChatPromptType'
        labels:
          type: array
          items:
            type: string
          nullable: true
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: List of tags to apply to all versions of this prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
      required:
        - name
        - prompt
        - type
    CreateTextPromptRequest:
      title: CreateTextPromptRequest
      type: object
      properties:
        name:
          type: string
        prompt:
          type: string
        config:
          nullable: true
        type:
          $ref: '#/components/schemas/CreateTextPromptType'
          nullable: true
        labels:
          type: array
          items:
            type: string
          nullable: true
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: List of tags to apply to all versions of this prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
      required:
        - name
        - prompt
    Prompt:
      title: Prompt
      type: object
      properties:
        type:
          type: string
          enum:
            - chat
            - text
        prompt:
          type: string
      required:
        - type
        - prompt
    PromptType:
      title: PromptType
      type: string
      enum:
        - chat
        - text
    BasePrompt:
      title: BasePrompt
      type: object
      properties:
        name:
          type: string
        version:
          type: integer
        config: {}
        labels:
          type: array
          items:
            type: string
          description: List of deployment labels of this prompt version.
        tags:
          type: array
          items:
            type: string
          description: >-
            List of tags. Used to filter via UI and API. The same across
            versions of a prompt.
        commitMessage:
          type: string
          nullable: true
          description: Commit message for this prompt version.
        resolutionGraph:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            The dependency resolution graph for the current prompt. Null if the
            prompt has no dependencies or if `resolve=false` was used.
      required:
        - name
        - version
        - config
        - labels
        - tags
    ChatMessageWithPlaceholders:
      title: ChatMessageWithPlaceholders
      oneOf:
        - $ref: '#/components/schemas/ChatMessage'
        - $ref: '#/components/schemas/PlaceholderMessage'
    ChatMessage:
      title: ChatMessage
      type: object
      properties:
        role:
          type: string
        content:
          type: string
        type:
          $ref: '#/components/schemas/ChatMessageType'
          nullable: true
      required:
        - role
        - content
    ChatMessageType:
      title: ChatMessageType
      type: string
      enum:
        - chatmessage
    PlaceholderMessage:
      title: PlaceholderMessage
      type: object
      properties:
        name:
          type: string
        type:
          $ref: '#/components/schemas/PlaceholderMessageType'
          nullable: true
      required:
        - name
    PlaceholderMessageType:
      title: PlaceholderMessageType
      type: string
      enum:
        - placeholder
    TextPrompt:
      title: TextPrompt
      type: object
      properties:
        prompt:
          type: string
      required:
        - prompt
      allOf:
        - $ref: '#/components/schemas/BasePrompt'
    ChatPrompt:
      title: ChatPrompt
      type: object
      properties:
        prompt:
          type: array
          items:
            $ref: '#/components/schemas/ChatMessageWithPlaceholders'
      required:
        - prompt
      allOf:
        - $ref: '#/components/schemas/BasePrompt'
    CreateChatPromptType:
      title: CreateChatPromptType
      type: string
      enum:
        - chat
    CreateTextPromptType:
      title: CreateTextPromptType
      type: string
      enum:
        - text
    ServiceProviderConfig:
      title: ServiceProviderConfig
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        documentationUri:
          type: string
        patch:
          $ref: '#/components/schemas/ScimFeatureSupport'
        bulk:
          $ref: '#/components/schemas/BulkConfig'
        filter:
          $ref: '#/components/schemas/FilterConfig'
        changePassword:
          $ref: '#/components/schemas/ScimFeatureSupport'
        sort:
          $ref: '#/components/schemas/ScimFeatureSupport'
        etag:
          $ref: '#/components/schemas/ScimFeatureSupport'
        authenticationSchemes:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticationScheme'
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - schemas
        - documentationUri
        - patch
        - bulk
        - filter
        - changePassword
        - sort
        - etag
        - authenticationSchemes
        - meta
    ScimFeatureSupport:
      title: ScimFeatureSupport
      type: object
      properties:
        supported:
          type: boolean
      required:
        - supported
    BulkConfig:
      title: BulkConfig
      type: object
      properties:
        supported:
          type: boolean
        maxOperations:
          type: integer
        maxPayloadSize:
          type: integer
      required:
        - supported
        - maxOperations
        - maxPayloadSize
    FilterConfig:
      title: FilterConfig
      type: object
      properties:
        supported:
          type: boolean
        maxResults:
          type: integer
      required:
        - supported
        - maxResults
    ResourceMeta:
      title: ResourceMeta
      type: object
      properties:
        resourceType:
          type: string
        location:
          type: string
      required:
        - resourceType
        - location
    AuthenticationScheme:
      title: AuthenticationScheme
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        specUri:
          type: string
        type:
          type: string
        primary:
          type: boolean
      required:
        - name
        - description
        - specUri
        - type
        - primary
    ResourceTypesResponse:
      title: ResourceTypesResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ResourceType'
      required:
        - schemas
        - totalResults
        - Resources
    ResourceType:
      title: ResourceType
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          nullable: true
        id:
          type: string
        name:
          type: string
        endpoint:
          type: string
        description:
          type: string
        schema:
          type: string
        schemaExtensions:
          type: array
          items:
            $ref: '#/components/schemas/SchemaExtension'
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - id
        - name
        - endpoint
        - description
        - schema
        - schemaExtensions
        - meta
    SchemaExtension:
      title: SchemaExtension
      type: object
      properties:
        schema:
          type: string
        required:
          type: boolean
      required:
        - schema
        - required
    SchemasResponse:
      title: SchemasResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/SchemaResource'
      required:
        - schemas
        - totalResults
        - Resources
    SchemaResource:
      title: SchemaResource
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        attributes:
          type: array
          items: {}
        meta:
          $ref: '#/components/schemas/ResourceMeta'
      required:
        - id
        - name
        - description
        - attributes
        - meta
    ScimUsersListResponse:
      title: ScimUsersListResponse
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        totalResults:
          type: integer
        startIndex:
          type: integer
        itemsPerPage:
          type: integer
        Resources:
          type: array
          items:
            $ref: '#/components/schemas/ScimUser'
      required:
        - schemas
        - totalResults
        - startIndex
        - itemsPerPage
        - Resources
    ScimUser:
      title: ScimUser
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
        userName:
          type: string
        name:
          $ref: '#/components/schemas/ScimName'
        emails:
          type: array
          items:
            $ref: '#/components/schemas/ScimEmail'
        meta:
          $ref: '#/components/schemas/UserMeta'
      required:
        - schemas
        - id
        - userName
        - name
        - emails
        - meta
    UserMeta:
      title: UserMeta
      type: object
      properties:
        resourceType:
          type: string
        created:
          type: string
          nullable: true
        lastModified:
          type: string
          nullable: true
      required:
        - resourceType
    ScimName:
      title: ScimName
      type: object
      properties:
        formatted:
          type: string
          nullable: true
    ScimEmail:
      title: ScimEmail
      type: object
      properties:
        primary:
          type: boolean
        value:
          type: string
        type:
          type: string
      required:
        - primary
        - value
        - type
    EmptyResponse:
      title: EmptyResponse
      type: object
      description: Empty response for 204 No Content responses
      properties: {}
    ScoreConfigs:
      title: ScoreConfigs
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ScoreConfig'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    CreateScoreConfigRequest:
      title: CreateScoreConfigRequest
      type: object
      properties:
        name:
          type: string
          description: >-
            Name of the score config. Max 35 characters. Only letters, numbers,
            underscores, spaces, periods, parentheses, and hyphens are allowed.
        dataType:
          $ref: '#/components/schemas/ScoreConfigDataType'
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: >-
            Configure custom categories for categorical scores. Pass a list of
            objects with `label` and `value` properties. Categories are
            autogenerated for boolean configs and cannot be passed
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a minimum value for numerical scores. If not set, the
            minimum value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a maximum value for numerical scores. If not set, the
            maximum value defaults to +∞
        description:
          type: string
          nullable: true
          description: >-
            Description is shown across the Langfuse UI and can be used to e.g.
            explain the config categories in detail, why a numeric range was
            set, or provide additional context on config name or usage
      required:
        - name
        - dataType
    UpdateScoreConfigRequest:
      title: UpdateScoreConfigRequest
      type: object
      properties:
        isArchived:
          type: boolean
          nullable: true
          description: The status of the score config showing if it is archived or not
        name:
          type: string
          nullable: true
          description: >-
            Name of the score config. Max 35 characters. Only letters, numbers,
            underscores, spaces, periods, parentheses, and hyphens are allowed.
        categories:
          type: array
          items:
            $ref: '#/components/schemas/ConfigCategory'
          nullable: true
          description: >-
            Configure custom categories for categorical scores. Pass a list of
            objects with `label` and `value` properties. Categories are
            autogenerated for boolean configs and cannot be passed
        minValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a minimum value for numerical scores. If not set, the
            minimum value defaults to -∞
        maxValue:
          type: number
          format: double
          nullable: true
          description: >-
            Configure a maximum value for numerical scores. If not set, the
            maximum value defaults to +∞
        description:
          type: string
          nullable: true
          description: >-
            Description is shown across the Langfuse UI and can be used to e.g.
            explain the config categories in detail, why a numeric range was
            set, or provide additional context on config name or usage
    GetScoresResponseTraceData:
      title: GetScoresResponseTraceData
      type: object
      properties:
        userId:
          type: string
          nullable: true
          description: The user ID associated with the trace referenced by score
        tags:
          type: array
          items:
            type: string
          nullable: true
          description: A list of tags associated with the trace referenced by score
        environment:
          type: string
          nullable: true
          description: The environment of the trace referenced by score
        sessionId:
          type: string
          nullable: true
          description: The session ID associated with the trace referenced by score
    GetScoresResponseDataNumeric:
      title: GetScoresResponseDataNumeric
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
          nullable: true
      allOf:
        - $ref: '#/components/schemas/NumericScore'
    GetScoresResponseDataCategorical:
      title: GetScoresResponseDataCategorical
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
          nullable: true
      allOf:
        - $ref: '#/components/schemas/CategoricalScore'
    GetScoresResponseDataBoolean:
      title: GetScoresResponseDataBoolean
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
          nullable: true
      allOf:
        - $ref: '#/components/schemas/BooleanScore'
    GetScoresResponseDataCorrection:
      title: GetScoresResponseDataCorrection
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
          nullable: true
      allOf:
        - $ref: '#/components/schemas/CorrectionScore'
    GetScoresResponseDataText:
      title: GetScoresResponseDataText
      type: object
      properties:
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
          nullable: true
      allOf:
        - $ref: '#/components/schemas/TextScore'
    GetScoresResponseData:
      title: GetScoresResponseData
      type: object
      properties:
        dataType:
          type: string
          enum:
            - NUMERIC
            - CATEGORICAL
            - BOOLEAN
            - CORRECTION
            - TEXT
        trace:
          $ref: '#/components/schemas/GetScoresResponseTraceData'
      required:
        - dataType
    GetScoresResponse:
      title: GetScoresResponse
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/GetScoresResponseData'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    PaginatedSessions:
      title: PaginatedSessions
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Session'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    Traces:
      title: Traces
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TraceWithDetails'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    DeleteTraceResponse:
      title: DeleteTraceResponse
      type: object
      properties:
        message:
          type: string
      required:
        - message
    Sort:
      title: Sort
      type: object
      properties:
        id:
          type: string
      required:
        - id
    unstableEvaluatorType:
      title: unstableEvaluatorType
      type: string
      enum:
        - llm_as_judge
      description: >-
        The evaluator engine type.


        The unstable public API currently supports only LLM-as-a-judge
        evaluators.
    unstableEvaluatorScope:
      title: unstableEvaluatorScope
      type: string
      enum:
        - project
        - managed
      description: |-
        Where an evaluator comes from.

        - `project`: created in your project
        - `managed`: provided by Langfuse
    unstableEvaluationRuleTarget:
      title: unstableEvaluationRuleTarget
      type: string
      enum:
        - observation
        - experiment
      description: >-
        The ingestion object type that should trigger evaluation runs.


        Choose the target first, because it changes both the valid filter
        columns and the valid variable-mapping sources:

        - `observation` evaluates live-ingested observations such as
        generations, spans, and events.
          It supports mapping from `input`, `output`, and `metadata`.
        - `experiment` evaluates live experiment executions and can additionally
        map `expected_output`.
          It currently supports filtering by `datasetId`.
          Discover valid dataset IDs with `GET /api/public/v2/datasets`, then use the returned dataset `id` values in your filter.
    unstableEvaluationRuleStatus:
      title: unstableEvaluationRuleStatus
      type: string
      enum:
        - active
        - inactive
        - paused
      description: >-
        Effective runtime status of the evaluation rule.


        - `active`: enabled and currently runnable.

        - `inactive`: disabled by configuration.

        - `paused`: enabled, but Langfuse has blocked execution until the
        underlying issue is resolved.
    unstableEvaluationRuleMappingSource:
      title: unstableEvaluationRuleMappingSource
      type: string
      enum:
        - input
        - output
        - metadata
        - expected_output
      description: >-
        Source field used to populate a prompt variable.


        Use these values when mapping evaluator prompt variables to live data.


        Target-specific rules:

        - `target=observation` supports `input`, `output`, and `metadata`

        - `target=experiment` supports `input`, `output`, `metadata`, and
        `expected_output`


        Source semantics:

        - `input`: the observation or experiment input payload

        - `output`: the observation or experiment output payload

        - `metadata`: the metadata object for the target. Combine with
        `jsonPath` when you need one nested field instead of the whole object.

        - `expected_output`: the experiment item's expected output. Only valid
        for `target=experiment`.
    unstableEvaluatorModelConfig:
      title: unstableEvaluatorModelConfig
      type: object
      description: >-
        Optional explicit model configuration for an evaluator.


        If omitted, Langfuse uses the project's default evaluation model.

        If provided, the model must be available to the project when the
        evaluator or evaluation rule is enabled.


        To discover valid configured `provider` values for a project, call `GET
        /api/public/llm-connections` and read the `provider` field from the
        returned connections.

        Use a `provider` value that matches one of the connections already
        configured in the same project.


        Recovery guidance:

        - If evaluator creation returns `422` with
        `code=evaluator_preflight_failed`, either provide a valid explicit
        `modelConfig` here or configure the project's default evaluation model,
        then retry the same request.
      properties:
        provider:
          type: string
          description: >-
            Provider identifier to use for this evaluator, for example `openai`
            or `anthropic`.


            To discover valid values for the current project, call `GET
            /api/public/llm-connections` and use one of the returned `provider`
            values.
          example: openai
        model:
          type: string
          description: >-
            Model identifier exposed by the provider, for example `gpt-4.1-mini`.
          example: gpt-4.1-mini
      required:
        - provider
        - model
    unstableEvaluatorOutputDataType:
      title: unstableEvaluatorOutputDataType
      type: string
      enum:
        - NUMERIC
        - BOOLEAN
        - CATEGORICAL
      description: >-
        Structured score type returned by an evaluator.


        This controls the type of score value Langfuse stores for evaluation
        results:

        - `NUMERIC`: a numeric score such as `0.82`

        - `BOOLEAN`: a boolean score such as `true`

        - `CATEGORICAL`: one or more category labels from a fixed list
    unstableEvaluatorOutputFieldDefinition:
      title: unstableEvaluatorOutputFieldDefinition
      type: object
      properties:
        description:
          type: string
          description: >-
            Human-readable instructions for what the evaluator should return in
            this field.
      required:
        - description
    unstableEvaluatorOutputDefinition:
      title: unstableEvaluatorOutputDefinition
      type: object
      properties:
        dataType:
          type: string
          enum:
            - NUMERIC
            - BOOLEAN
            - CATEGORICAL
        reasoning:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
        score:
          type: string
      required:
        - dataType
        - reasoning
        - score
    unstablePublicNumericEvaluatorOutputDefinition:
      title: unstablePublicNumericEvaluatorOutputDefinition
      type: object
      properties:
        dataType:
          $ref: '#/components/schemas/unstableEvaluatorOutputDataType'
          description: Always `NUMERIC`.
        reasoning:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
        score:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
      required:
        - dataType
        - reasoning
        - score
    unstablePublicBooleanEvaluatorOutputDefinition:
      title: unstablePublicBooleanEvaluatorOutputDefinition
      type: object
      properties:
        dataType:
          $ref: '#/components/schemas/unstableEvaluatorOutputDataType'
          description: Always `BOOLEAN`.
        reasoning:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
        score:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
      required:
        - dataType
        - reasoning
        - score
    unstablePublicCategoricalEvaluatorOutputScoreDefinition:
      title: unstablePublicCategoricalEvaluatorOutputScoreDefinition
      type: object
      properties:
        description:
          type: string
        categories:
          type: array
          items:
            type: string
        shouldAllowMultipleMatches:
          type: boolean
      required:
        - description
        - categories
        - shouldAllowMultipleMatches
    unstablePublicCategoricalEvaluatorOutputDefinition:
      title: unstablePublicCategoricalEvaluatorOutputDefinition
      type: object
      properties:
        dataType:
          $ref: '#/components/schemas/unstableEvaluatorOutputDataType'
          description: Always `CATEGORICAL`.
        reasoning:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
        score:
          $ref: >-
            #/components/schemas/unstablePublicCategoricalEvaluatorOutputScoreDefinition
      required:
        - dataType
        - reasoning
        - score
    unstablePublicEvaluatorOutputDefinition:
      title: unstablePublicEvaluatorOutputDefinition
      type: object
      properties:
        dataType:
          type: string
          enum:
            - NUMERIC
            - BOOLEAN
            - CATEGORICAL
        reasoning:
          $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition'
        score:
          type: string
      required:
        - dataType
        - reasoning
        - score
    unstableEvaluationRuleStringFilterOperator:
      title: unstableEvaluationRuleStringFilterOperator
      type: string
      enum:
        - '='
        - contains
        - does not contain
        - starts with
        - ends with
    unstableEvaluationRuleNumberFilterOperator:
      title: unstableEvaluationRuleNumberFilterOperator
      type: string
      enum:
        - '='
        - '>'
        - <
        - '>='
        - <=
    unstableEvaluationRuleOptionsFilterOperator:
      title: unstableEvaluationRuleOptionsFilterOperator
      type: string
      enum:
        - any of
        - none of
    unstableEvaluationRuleArrayOptionsFilterOperator:
      title: unstableEvaluationRuleArrayOptionsFilterOperator
      type: string
      enum:
        - any of
        - none of
        - all of
    unstableEvaluationRuleBooleanFilterOperator:
      title: unstableEvaluationRuleBooleanFilterOperator
      type: string
      enum:
        - '='
        - <>
    unstableEvaluationRuleNullFilterOperator:
      title: unstableEvaluationRuleNullFilterOperator
      type: string
      enum:
        - is null
        - is not null
    unstableDateTimeEvaluationRuleFilter:
      title: unstableDateTimeEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator'
          description: Comparison operator for datetime values.
        value:
          type: string
          format: date-time
          description: Datetime value to compare against.
      required:
        - column
        - operator
        - value
    unstableStringEvaluationRuleFilter:
      title: unstableStringEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator'
        value:
          type: string
      required:
        - column
        - operator
        - value
    unstableNumberEvaluationRuleFilter:
      title: unstableNumberEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator'
        value:
          type: number
          format: double
      required:
        - column
        - operator
        - value
    unstableStringOptionsEvaluationRuleFilter:
      title: unstableStringOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator'
        value:
          type: array
          items:
            type: string
          description: One or more allowed string values.
      required:
        - column
        - operator
        - value
    unstableArrayOptionsEvaluationRuleFilter:
      title: unstableArrayOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: >-
            #/components/schemas/unstableEvaluationRuleArrayOptionsFilterOperator
        value:
          type: array
          items:
            type: string
          description: One or more array elements to match.
      required:
        - column
        - operator
        - value
    unstableStringObjectEvaluationRuleFilter:
      title: unstableStringObjectEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: >-
            Object-valued column to filter on. In the unstable public API this
            is currently `metadata`.
        key:
          type: string
          description: Top-level key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator'
        value:
          type: string
      required:
        - column
        - key
        - operator
        - value
    unstableNumberObjectEvaluationRuleFilter:
      title: unstableNumberObjectEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Object-valued column to filter on.
        key:
          type: string
          description: Key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator'
        value:
          type: number
          format: double
      required:
        - column
        - key
        - operator
        - value
    unstableCategoryOptionsEvaluationRuleFilter:
      title: unstableCategoryOptionsEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Object-valued column to filter on.
        key:
          type: string
          description: Key inside the object-valued column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator'
        value:
          type: array
          items:
            type: string
      required:
        - column
        - key
        - operator
        - value
    unstableBooleanEvaluationRuleFilter:
      title: unstableBooleanEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: Column to filter on.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleBooleanFilterOperator'
        value:
          type: boolean
      required:
        - column
        - operator
        - value
    unstableNullEvaluationRuleFilter:
      title: unstableNullEvaluationRuleFilter
      type: object
      properties:
        column:
          type: string
          description: >-
            Column to filter on. In the unstable public API this is currently
            `parentObservationId`.
        operator:
          $ref: '#/components/schemas/unstableEvaluationRuleNullFilterOperator'
        value:
          type: string
          nullable: true
          description: >-
            Ignored placeholder value. Clients may omit it or send an empty
            string.
      required:
        - column
        - operator
    unstableEvaluationRuleMapping:
      title: unstableEvaluationRuleMapping
      type: object
      description: >-
        Maps one evaluator prompt variable to one source field from the target
        object.


        How to build a valid mapping list:

        1. Create the evaluator or fetch it with `GET /evaluators/{id}`.

        2. Read the evaluator `variables` array.

        3. Add exactly one mapping object for each variable in that array.

        4. Use the variable name exactly as returned, without braces such as
        `{{` or `}}`.

        5. Choose a `source` that is valid for the selected `target`.


        `jsonPath` is optional. Use it only when the selected source is a JSON
        object and you want to extract one nested field before inserting it into
        the evaluator prompt.


        Recovery guidance:

        - `invalid_variable_mapping`: the variable name is unknown for this
        evaluator, or the selected `source` is not valid for the chosen `target`

        - `missing_variable_mapping`: one or more evaluator variables are not
        mapped yet

        - `duplicate_variable_mapping`: the same evaluator variable appears more
        than once

        - `invalid_json_path`: the JSONPath expression is malformed. Remove it
        or correct it.
      properties:
        variable:
          type: string
          description: >-
            Prompt variable name without braces.


            Example: for the prompt `Judge {{input}} against {{output}}`, use
            `input` and `output`.
          example: input
        source:
          $ref: '#/components/schemas/unstableEvaluationRuleMappingSource'
          description: >-
            Source field that should populate the prompt variable.


            Quick reference:

            - `target=observation`: `input`, `output`, `metadata`

            - `target=experiment`: `input`, `output`, `metadata`,
            `expected_output`
        jsonPath:
          type: string
          nullable: true
          description: >-
            Optional JSONPath selector applied to the selected source before it
            is passed to the evaluator prompt.


            Requirements:

            - Must start with `$`

            - Must be a syntactically valid JSONPath expression

            - Most useful with `source=metadata`
      required:
        - variable
        - source
    unstableEvaluationRuleFilter:
      title: unstableEvaluationRuleFilter
      type: object
      properties:
        type:
          type: string
          enum:
            - datetime
            - string
            - number
            - stringOptions
            - categoryOptions
            - arrayOptions
            - stringObject
            - numberObject
            - boolean
            - 'null'
        column:
          type: string
          description: Column to filter on.
        operator:
          type: string
          description: Comparison operator for datetime values.
        value:
          type: string
          description: Datetime value to compare against.
        key:
          type: string
          description: Key inside the object-valued column to filter on.
      required:
        - type
        - column
        - operator
    unstablePublicApiErrorCode:
      title: unstablePublicApiErrorCode
      type: string
      enum:
        - authentication_failed
        - access_denied
        - invalid_request
        - invalid_query
        - invalid_body
        - invalid_filter_value
        - invalid_json_path
        - invalid_variable_mapping
        - missing_variable_mapping
        - duplicate_variable_mapping
        - resource_not_found
        - name_conflict
        - evaluator_preflight_failed
        - conflict
        - unprocessable_content
        - rate_limited
        - method_not_allowed
        - internal_error
      description: >-
        Machine-readable error code returned by the unstable evaluators API.


        SDKs, CLIs, and agents should branch on `code` rather than parsing the
        human-readable `message`.

        The HTTP status still indicates the broad error class, while `code`
        gives the specific failure reason.
    unstablePublicApiValidationIssue:
      title: unstablePublicApiValidationIssue
      type: object
      description: >-
        One validation issue returned for malformed request bodies or query
        parameters.


        This mirrors the most important parts of a Zod issue: a machine-readable
        `code`,

        a human-readable `message`, and a structured `path`.
      properties:
        code:
          type: string
          description: >-
            Machine-readable validation issue code emitted by the server
            validator.
        message:
          type: string
          description: Human-readable explanation of the validation failure.
        path:
          type: array
          items: {}
          description: Path to the invalid field, for example `["mapping", 0, "jsonPath"]`.
      required:
        - code
        - message
        - path
    unstablePublicApiErrorDetails:
      title: unstablePublicApiErrorDetails
      type: object
      description: >-
        Optional structured context attached to an unstable-evals error.


        The populated fields depend on the error `code`:

        - request parsing failures populate `issues`

        - filter validation failures populate `field`, `column`,
        `invalidValues`, and `allowedValues`

        - variable mapping failures populate `field`, `variable`, or `variables`

        - JSONPath validation failures populate `field`, `variable`, and `value`

        - evaluator preflight failures populate `evaluatorName`, `provider`, and
        `model`

        - rate limiting populates `retryAfterSeconds`, `limit`, `remaining`, and
        `resetAt`
      properties:
        issues:
          type: array
          items:
            $ref: '#/components/schemas/unstablePublicApiValidationIssue'
          nullable: true
          description: Validation issues for malformed request bodies or query parameters.
        field:
          type: string
          nullable: true
          description: >-
            Path-like reference to the failing field, for example
            `mapping[1].jsonPath`.
        column:
          type: string
          nullable: true
          description: Filter column that failed validation.
        invalidValues:
          type: array
          items:
            type: string
          nullable: true
          description: Unsupported values supplied by the caller.
        allowedValues:
          type: array
          items:
            type: string
          nullable: true
          description: Allowed values for the failing filter column.
        variable:
          type: string
          nullable: true
          description: Evaluator variable involved in the failure.
        variables:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Multiple evaluator variables involved in the failure, for example
            missing mappings.
        value:
          type: string
          nullable: true
          description: Raw invalid value supplied by the caller.
        evaluatorName:
          type: string
          nullable: true
          description: Evaluator name used during preflight validation.
        provider:
          type: string
          nullable: true
          description: Provider resolved during evaluator preflight, if any.
        model:
          type: string
          nullable: true
          description: Model resolved during evaluator preflight, if any.
        retryAfterSeconds:
          type: integer
          nullable: true
          description: Suggested retry delay for rate-limited requests.
        limit:
          type: integer
          nullable: true
          description: >-
            Numeric limit associated with the failure, for example the active
            evaluation-rule cap or the current rate-limit window.
        remaining:
          type: integer
          nullable: true
          description: Remaining requests in the current rate-limit window.
        resetAt:
          type: string
          nullable: true
          description: ISO-8601 timestamp when the current rate-limit window resets.
    unstablePublicApiError:
      title: unstablePublicApiError
      type: object
      description: >-
        Standard error envelope for the unstable evaluators API.


        Response handling guidance:

        - Use the HTTP status code for the broad class of failure.

        - Use `code` for precise branching in SDKs, CLIs, or agents.

        - Inspect `details` for field-level validation context such as invalid
        filter values, malformed JSONPath expressions, or missing variable
        mappings.

        - Retry only after fixing the specific issue described by `code` and
        `details`.
      properties:
        message:
          type: string
          description: Human-readable description of the failure.
          example: 'Filter column "type" contains unsupported value(s): INVALID'
        code:
          $ref: '#/components/schemas/unstablePublicApiErrorCode'
          description: Stable machine-readable error code.
        details:
          $ref: '#/components/schemas/unstablePublicApiErrorDetails'
          nullable: true
          description: >-
            Optional structured error context. Inspect the populated fields
            based on `code`.
      required:
        - message
        - code
    unstableEvaluationRule:
      title: unstableEvaluationRule
      type: object
      description: >-
        Live evaluation rule for incoming data.


        An evaluation rule answers:

        - which evaluator should be used

        - which target objects should trigger scoring

        - how often scoring should run

        - which target fields should populate each evaluator variable

        - whether the deployment is active, inactive, or paused


        Important status semantics:

        - `enabled` is the desired on/off setting from the client

        - `status` is the effective runtime state after Langfuse applies
        validation and blocking rules

        - `enabled=true` with `status=paused` means the rule should run, but
        Langfuse has paused it until the underlying problem is fixed
      properties:
        id:
          type: string
          description: Stable evaluation rule identifier.
          example: erule_123
        name:
          type: string
          description: >-
            Human-readable deployment name. This is independent from the
            evaluator name.
          example: answer-correctness-live
        evaluator:
          $ref: '#/components/schemas/unstableEvaluationRuleEvaluator'
          description: >-
            Evaluator currently used by this rule.


            `name` and `scope` identify the evaluator family conceptually.

            `id` is the currently active evaluator version in that family.

            If you create a newer project version with the same evaluator name
            later, existing evaluation rules are moved to it automatically.
        target:
          $ref: '#/components/schemas/unstableEvaluationRuleTarget'
          description: Target object type that should trigger scoring.
        enabled:
          type: boolean
          description: Desired enabled state configured by the client.
          example: true
        status:
          $ref: '#/components/schemas/unstableEvaluationRuleStatus'
          description: >-
            Effective runtime status after Langfuse applies validation and
            blocking rules.
        pausedReason:
          type: string
          nullable: true
          description: Machine-readable reason when `status=paused`, otherwise `null`.
        pausedMessage:
          type: string
          nullable: true
          description: Human-readable explanation when `status=paused`, otherwise `null`.
        sampling:
          type: number
          format: double
          description: |-
            Fraction of matching target objects that should be evaluated.

            Must be greater than `0` and less than or equal to `1`.
            - `1` means evaluate every matching target.
            - `0.25` means evaluate approximately 25% of matching targets.
          example: 1
        filter:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleFilter'
          description: >-
            List of filter conditions used to decide whether a target should be
            evaluated.
        mapping:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleMapping'
          description: >-
            Variable mappings used to populate the evaluator prompt from the
            live target object.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the evaluation rule was created.
          example: '2026-03-30T09:20:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the evaluation rule was last updated.
          example: '2026-03-30T09:20:00.000Z'
      required:
        - id
        - name
        - evaluator
        - target
        - enabled
        - status
        - sampling
        - filter
        - mapping
        - createdAt
        - updatedAt
    unstableEvaluationRules:
      title: unstableEvaluationRules
      type: object
      description: Paginated list of evaluation rules.
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRule'
          description: Evaluation rules in the current page.
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
          description: Standard pagination metadata.
      required:
        - data
        - meta
    unstableCreateEvaluationRuleRequest:
      title: unstableCreateEvaluationRuleRequest
      type: object
      description: >-
        Request body for creating an evaluation rule.


        Checklist for agents and SDK clients:

        - reference an existing evaluator family by `evaluator.name` and
        `evaluator.scope`

        - choose `target=observation` or `target=experiment`

        - if `target=experiment` and you want a dataset filter, call `GET
        /api/public/v2/datasets` first and use dataset `id` values in
        `filter[].value`

        - fetch or inspect the evaluator first, then provide a complete variable
        mapping for every evaluator variable listed in `variables`

        - optionally narrow execution with `filter`

        - set `enabled=true` only when you want live execution immediately
      properties:
        name:
          type: string
          description: Human-readable deployment name.
          example: answer-correctness-live
        evaluator:
          $ref: '#/components/schemas/unstableEvaluationRuleEvaluatorReference'
          description: >-
            Evaluator family to use.


            Use `name` and `scope` from the evaluator endpoints.

            Langfuse resolves that family to its latest version before saving
            the rule.
        target:
          $ref: '#/components/schemas/unstableEvaluationRuleTarget'
          description: Target object type to evaluate.
        enabled:
          type: boolean
          description: Whether the deployment should be active immediately after creation.
          example: true
        sampling:
          type: number
          format: double
          nullable: true
          description: Optional sampling fraction. Defaults to `1`.
        filter:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleFilter'
          nullable: true
          description: >-
            Optional filter list.


            Omit or pass an empty list to evaluate all matching targets for the
            selected `target`.

            Each filter object must use a column that is valid for that
            `target`.

            For `target=experiment`, `column=datasetId` expects dataset `id`
            values from `GET /api/public/v2/datasets`, not dataset names.
        mapping:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleMapping'
          description: >-
            Required variable mappings.


            Every evaluator variable must appear exactly once.

            Build this list from the evaluator `variables` array returned by the
            evaluator endpoints.
      required:
        - name
        - evaluator
        - target
        - enabled
        - mapping
    unstableUpdateEvaluationRuleRequest:
      title: unstableUpdateEvaluationRuleRequest
      type: object
      description: >-
        Partial update body for an evaluation rule.


        Provide only the fields you want to change.

        An empty body is rejected.


        Practical guidance:

        - If you only want to rename the rule or change sampling, send just
        those fields.

        - If you change `evaluator`, send a fresh `mapping` unless you are
        certain the existing mapping still matches the evaluator variables.

        - If you change `target`, usually send both `filter` and `mapping` in
        the same request.

        - If you change an experiment `datasetId` filter, call `GET
        /api/public/v2/datasets` and use dataset `id` values from that response.
      properties:
        name:
          type: string
          nullable: true
          description: Updated deployment name.
        evaluator:
          $ref: '#/components/schemas/unstableEvaluationRuleEvaluatorReference'
          nullable: true
          description: >-
            Updated evaluator family.


            Langfuse resolves the provided evaluator family to its latest
            version before saving the rule.
        target:
          $ref: '#/components/schemas/unstableEvaluationRuleTarget'
          nullable: true
          description: Updated target object type.
        enabled:
          type: boolean
          nullable: true
          description: Updated desired enabled state.
        sampling:
          type: number
          format: double
          nullable: true
          description: Updated sampling fraction.
        filter:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleFilter'
          nullable: true
          description: >-
            Updated filter list.


            For `target=experiment`, `column=datasetId` expects dataset `id`
            values from `GET /api/public/v2/datasets`, not dataset names.
        mapping:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluationRuleMapping'
          nullable: true
          description: Updated variable mappings.
    unstableDeleteEvaluationRuleResponse:
      title: unstableDeleteEvaluationRuleResponse
      type: object
      description: Confirmation response returned after successful deletion.
      properties:
        message:
          type: string
          description: Always `Evaluation rule successfully deleted`.
      required:
        - message
    unstableEvaluationRuleEvaluatorReference:
      title: unstableEvaluationRuleEvaluatorReference
      type: object
      description: >-
        Evaluator family reference used when creating or updating an evaluation
        rule.


        `name` and `scope` are enough to identify the evaluator family in the
        authenticated project context.
      properties:
        name:
          type: string
          description: Evaluator family name.
        scope:
          $ref: '#/components/schemas/unstableEvaluatorScope'
          description: Whether the evaluator family is project-owned or Langfuse-managed.
      required:
        - name
        - scope
    unstableEvaluationRuleEvaluator:
      title: unstableEvaluationRuleEvaluator
      type: object
      description: |-
        Resolved evaluator currently used by the evaluation rule.

        `id` is the exact active evaluator version.
        `name` and `scope` identify the evaluator family conceptually.
      properties:
        id:
          type: string
          description: >-
            Identifier of the exact evaluator version currently used by the rule.
        name:
          type: string
          description: Evaluator family name.
        scope:
          $ref: '#/components/schemas/unstableEvaluatorScope'
          description: Whether the evaluator family is project-owned or Langfuse-managed.
      required:
        - id
        - name
        - scope
    unstableEvaluator:
      title: unstableEvaluator
      type: object
      description: >-
        One evaluator that can be used for scoring.


        An evaluator describes **how** to score data:

        - prompt

        - extracted prompt variables

        - output schema

        - optional explicit model configuration


        It does not define **which** live objects are evaluated. That is the job
        of `evaluation-rules`.


        For agent clients, the most important fields are:

        - `variables`: use these exact names when building the evaluation-rule
        `mapping` array

        - `outputDefinition`: tells you the expected score type and the
        evaluator's response instructions

        - `modelConfig`: tells you whether the evaluator uses the project
        default model (`null`) or an explicit provider/model


        Versioning behavior:

        - `GET /evaluators` returns the latest version of each available
        evaluator.

        - `GET /evaluators/{id}` can return an older version.

        - Evaluation rules always run against the latest version for the
        selected evaluator name within the same source (`project` or `managed`).
      properties:
        id:
          type: string
          description: Identifier of this evaluator.
          example: evaltmpl_123
        name:
          type: string
          description: Evaluator name.
          example: answer-correctness
        version:
          type: integer
          description: Version number of this evaluator.
          example: 2
        scope:
          $ref: '#/components/schemas/unstableEvaluatorScope'
          description: >-
            Where this evaluator comes from: your project or Langfuse-managed
            defaults.
        type:
          $ref: '#/components/schemas/unstableEvaluatorType'
          description: Evaluator engine type. Currently always `llm_as_judge`.
        prompt:
          type: string
          description: Prompt template used during evaluation.
          example: |
            You are grading an answer.

            Input:
            {{input}}

            Output:
            {{output}}

            Return a score between 0 and 1.
        variables:
          type: array
          items:
            type: string
          description: >-
            Variables extracted from the evaluator prompt.


            Every variable in this list must be mapped exactly once when
            creating an evaluation rule.
          example:
            - input
            - output
        outputDefinition:
          $ref: '#/components/schemas/unstablePublicEvaluatorOutputDefinition'
          description: >-
            Structured output schema returned by this evaluator.


            Responses always include `dataType` and omit the internal
            output-definition `version`.

            Use `dataType` to decide how future scores should be interpreted.
        modelConfig:
          $ref: '#/components/schemas/unstableEvaluatorModelConfig'
          nullable: true
          description: >-
            Explicit model configuration, or `null` when the project default
            evaluation model is used.
        evaluationRuleCount:
          type: integer
          description: >-
            Number of evaluation rules in the project that currently use this
            evaluator version.
          example: 0
        createdAt:
          type: string
          format: date-time
          description: Timestamp when this evaluator was created.
          example: '2026-03-30T09:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when this evaluator was last updated.
          example: '2026-03-30T09:00:00.000Z'
      required:
        - id
        - name
        - version
        - scope
        - type
        - prompt
        - variables
        - outputDefinition
        - evaluationRuleCount
        - createdAt
        - updatedAt
    unstableEvaluators:
      title: unstableEvaluators
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/unstableEvaluator'
        meta:
          $ref: '#/components/schemas/utilsMetaResponse'
      required:
        - data
        - meta
    unstableCreateEvaluatorRequest:
      title: unstableCreateEvaluatorRequest
      type: object
      description: >-
        Request body for creating an evaluator.


        If the same `name` already exists in your project, Langfuse creates the
        next version and returns it.

        Existing evaluation rules in the same project are then moved to that new
        latest version automatically.
      properties:
        name:
          type: string
          description: Evaluator name within the authenticated project.
          example: answer-correctness
        prompt:
          type: string
          description: Prompt template used by the evaluator.
          example: |
            You are grading an answer.

            Input:
            {{input}}

            Output:
            {{output}}

            Return a score between 0 and 1.
        outputDefinition:
          $ref: '#/components/schemas/unstableEvaluatorOutputDefinition'
          description: >-
            Structured output schema the evaluator must return.


            Always send `dataType`.

            Do not send `version`; it is an internal storage detail and not part
            of the public request contract.
        modelConfig:
          $ref: '#/components/schemas/unstableEvaluatorModelConfig'
          nullable: true
          description: >-
            Optional explicit model configuration. Omit or set to `null` to use
            the project default evaluation model.
      required:
        - name
        - prompt
        - outputDefinition
    utilsMetaResponse:
      title: utilsMetaResponse
      type: object
      properties:
        page:
          type: integer
          description: current page number
        limit:
          type: integer
          description: number of items per page
        totalItems:
          type: integer
          description: number of total items given the current filters/selection (if any)
        totalPages:
          type: integer
          description: number of total pages given the current limit
      required:
        - page
        - limit
        - totalItems
        - totalPages
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic