openapi: 3.0.1
info:
title: server
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: &ref_0
- 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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
/api/public/experiments:
get:
description: |-
List experiments with cursor-based pagination. Results are ordered by
latest experiment activity descending.
operationId: experiments_list
tags:
- Experiments
parameters:
- name: fields
in: query
description: |-
Comma-separated list of field groups to include. Available groups:
`core`, `metadata`, `scores`. If omitted, `core` is returned.
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: Number of experiments to return per page. Maximum 100, default 50.
required: false
schema:
type: integer
nullable: true
- name: scoreLimit
in: query
description: >-
Number of scores to return per experiment when `fields=scores` is
requested. Maximum 50, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Versioned base64url cursor from the previous response page.
required: false
schema:
type: string
nullable: true
- name: fromStartTime
in: query
description: Retrieve only experiments on or after this datetime.
required: true
schema:
type: string
format: date-time
- name: toStartTime
in: query
description: Retrieve only experiments before this datetime.
required: false
schema:
type: string
format: date-time
nullable: true
- name: id
in: query
description: Comma-separated list of experiment IDs.
required: false
schema:
type: string
nullable: true
- name: name
in: query
description: Comma-separated list of experiment names.
required: false
schema:
type: string
nullable: true
- name: datasetId
in: query
description: Comma-separated list of dataset IDs.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: |-
JSON string containing an array of structured filter conditions.
Supported columns are `id`, `name`, and `datasetId`.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExperimentsResponse'
'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: *ref_0
/api/public/experiment-items:
get:
description: |-
List experiment items with cursor-based pagination. Use this endpoint
to export experiment item inputs, outputs, expected outputs, metadata,
and optionally item/trace scores. Results are ordered by time
descending.
operationId: experiments_listItems
tags:
- Experiments
parameters:
- name: fields
in: query
description: |-
Comma-separated list of field groups to include. Available groups:
`core`, `dataset`, `io`, `metadata`, `itemMetadata`,
`experimentMetadata`, `scores`. If omitted, `core,dataset` is
returned.
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: >-
Number of experiment items to return per page. Maximum 100, default
50.
required: false
schema:
type: integer
nullable: true
- name: scoreLimit
in: query
description: >-
Number of scores to return per experiment item when `fields=scores`
is requested. Maximum 50, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Versioned base64url cursor from the previous response page.
required: false
schema:
type: string
nullable: true
- name: fromStartTime
in: query
description: Retrieve only experiment items started on or after this datetime.
required: true
schema:
type: string
format: date-time
- name: toStartTime
in: query
description: Retrieve only experiment items started before this datetime.
required: false
schema:
type: string
format: date-time
nullable: true
- name: experimentId
in: query
description: Comma-separated list of experiment IDs.
required: false
schema:
type: string
nullable: true
- name: experimentName
in: query
description: Comma-separated list of experiment names.
required: false
schema:
type: string
nullable: true
- name: experimentItemId
in: query
description: Comma-separated list of experiment item IDs.
required: false
schema:
type: string
nullable: true
- name: datasetId
in: query
description: Comma-separated list of dataset IDs.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: |-
JSON string containing an array of structured filter conditions.
Supported columns are `experimentId`, `experimentName`,
`experimentItemId`, and `datasetId`.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExperimentItemsResponse'
'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: *ref_0
/api/public/feedback:
post:
description: >-
Submit explicit user-approved feedback about Langfuse skills, MCP tools,
CLI, docs, or public API. Do not include secrets, credentials, customer
data, trace payloads, or unrelated use-case details.
operationId: feedback_submit
tags:
- Feedback
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitFeedbackResponse'
'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: ''
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitFeedbackRequest'
/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'
'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: *ref_0
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
/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-boolean", "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: *ref_0
/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/ObservationsViewSingle'
'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: *ref_0
/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: *ref_0
/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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
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`, `scores-boolean`, and
`scores-categorical` views only (traces view not supported)
- Direct access to tags and release fields on observations
- Semantic-root filtering and grouping through the v2-only
`isRootObservation` dimension
- 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
- `isRootObservation` - Boolean semantic-root status. `true` includes
physical roots and app roots whose SDK parent is external (so
`parentObservationId` may be non-null).
- `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-boolean
Query boolean score data. It has the same score and parent
trace/observation dimensions as scores-numeric, plus:
**Dimensions:**
- `booleanValue` - Boolean value for true/false grouping and filtering
**Measures:**
- `count` - Total number of boolean scores
- `value` - Numeric 0/1 score value; `avg` returns the true-rate
### 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-boolean / 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-boolean", "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
}
}
```
For example, to count semantic roots (including app roots with a
non-null external parent), use a boolean filter:
```json
{
"view": "observations",
"metrics": [{"measure": "count", "aggregation": "count"}],
"filters": [{"column": "isRootObservation", "operator": "=", "value": true, "type": "boolean"}],
"fromTimestamp": "2025-01-01T00:00:00.000Z",
"toTimestamp": "2025-02-01T00:00:00.000Z"
}
```
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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, isRootObservation
- `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, usagePricingTierName
- `prompt` - promptId, promptName, promptVersion
- `metrics` - latency, timeToFirstToken
- `trace_context` - tags, release, traceName
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, trace_context.
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: sessionId
in: query
description: Filter by session ID.
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
description: >-
Filter by the physical parent observation ID.
An empty value matches only observations without a physical parent.
Use `isRootObservation` to include observations marked as app roots
by the SDK, which may retain a non-null `parentObservationId`.
required: false
schema:
type: string
nullable: true
- name: isRootObservation
in: query
description: >-
Filter by whether an observation is a logical root.
Root observations include observations without a physical parent and
observations marked as app roots by the SDK.
An app-root observation may have `isRootObservation=true` and a
non-null `parentObservationId`.
required: false
schema:
type: boolean
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", "matches"
// - 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", "matches"
// - 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
- `isRootObservation` (boolean) - Whether the observation is a
logical root. Observations marked as app roots by the SDK may retain
a non-null parentObservationId.
### 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
- `input` (string) - Observation input. Supports accelerated indexed
literal search with the `matches` operator.
- `output` (string) - Observation output. Supports accelerated
indexed literal search with the `matches` operator.
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
The `matches` operator is only supported for `input`, `output`, and
stringObject `metadata` filters. It performs indexed literal search
with token-boundary pruning using the events table text indexes.
Case sensitivity differs by target: `input` and `output` matches are
case-insensitive, while metadata value matches are case-sensitive.
Unlike SQL `LIKE`, `%` and `_` are treated as literal characters.
Use `contains` for legacy substring semantics where the API allows
it. Any v2 `input` or `output` filter must be accompanied by at
least one `=` or `matches` filter on `input` or `output`; standalone
`contains`, `starts with`, `ends with`, and `does not contain`
filters on these columns are rejected.
## 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"
},
{
"type": "string",
"column": "output",
"operator": "matches",
"value": "needle"
},
{
"type": "boolean",
"column": "isRootObservation",
"operator": "=",
"value": true
}
]
```
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: *ref_0
/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'
'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: *ref_0
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
/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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: 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: *ref_0
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: *ref_0
/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: *ref_0
post:
description: Create a new version for the prompt with the given `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: *ref_0
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: *ref_0
/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: *ref_0
/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: *ref_0
/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: *ref_0
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: *ref_0
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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
/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: *ref_0
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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScoreConfigRequest'
/api/public/v3/scores:
get:
description: |-
Get a list of scores with a polymorphic `value` field (v3).
The `value` field type depends on `dataType`:
- `NUMERIC` → number
- `BOOLEAN` → boolean
- `CATEGORICAL`, `TEXT`, `CORRECTION` → string
The response always includes the core fields: id, projectId, name,
value, dataType, source, timestamp, environment, createdAt, updatedAt.
Additional field groups can be requested via the `fields` parameter:
- `details` — adds comment, configId, metadata
- `subject` — adds the subject object describing the entity the score
is attached to: kind (trace, observation, session, or experiment),
id, and traceId for observation-level scores
- `annotation` — adds authorUserId, queueId
Unknown group names return HTTP 400.
operationId: scoresV3_getManyV3
tags:
- ScoresV3
parameters:
- name: limit
in: query
description: >-
Number of items per page. Maximum 100, default 50. Requests with a
limit greater than 100 return HTTP 400.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: >-
URL-safe base64 (base64url) cursor for pagination. Use the cursor
from the previous response to get the next page. Absent on the final
page.
required: false
schema:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated field groups to include in addition to the
always-returned core fields. Allowed: details, subject, annotation —
see the endpoint description for the fields each group adds. Unknown
names return HTTP 400.
required: false
schema:
type: string
nullable: true
- name: id
in: query
description: >-
Comma-separated list of score IDs to filter by (OR within, AND
across filters).
required: false
schema:
type: string
nullable: true
- name: name
in: query
description: Comma-separated list of score names to filter by.
required: false
schema:
type: string
nullable: true
- name: source
in: query
description: >-
Comma-separated list of score sources to filter by (e.g. API,
ANNOTATION, EVAL). Case-insensitive — `api` and `API` are
equivalent.
required: false
schema:
type: string
nullable: true
- name: dataType
in: query
description: >-
Comma-separated list of data types to filter by (NUMERIC, BOOLEAN,
CATEGORICAL, TEXT, CORRECTION). Case-insensitive — `numeric` and
`NUMERIC` are equivalent. Must be a single value when used with
value, valueMin, or valueMax; otherwise the request returns HTTP
400. Must be NUMERIC when used with valueMin or valueMax.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: Comma-separated list of environments to filter by.
required: false
schema:
type: string
nullable: true
- name: configId
in: query
description: Comma-separated list of score config IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: queueId
in: query
description: Comma-separated list of annotation queue IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: authorUserId
in: query
description: Comma-separated list of author user IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: value
in: query
description: >-
Comma-separated list of exact values to filter by. Requires a single
dataType from NUMERIC, BOOLEAN, or CATEGORICAL; any other dataType,
multiple dataTypes, or omitting dataType returns HTTP 400. For
BOOLEAN, each value must be "true" or "false"; for NUMERIC, each
value must be a finite number. Otherwise the request returns HTTP
400.
required: false
schema:
type: string
nullable: true
- name: valueMin
in: query
description: >-
Inclusive lower bound on the numeric value. Requires
dataType=NUMERIC as a single value; otherwise the request returns
HTTP 400.
required: false
schema:
type: number
format: double
nullable: true
- name: valueMax
in: query
description: >-
Inclusive upper bound on the numeric value. Requires
dataType=NUMERIC as a single value; otherwise the request returns
HTTP 400.
required: false
schema:
type: number
format: double
nullable: true
- name: traceId
in: query
description: >-
Comma-separated list of trace IDs to filter by. Mutually exclusive
with sessionId, experimentId. May be combined with observationId to
scope the observation lookup to a specific trace.
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
description: >-
Comma-separated list of session IDs to filter by. Mutually exclusive
with traceId, observationId, experimentId.
required: false
schema:
type: string
nullable: true
- name: observationId
in: query
description: >-
Comma-separated list of observation IDs to filter by. Requires
traceId to be specified, because observation IDs are scoped to a
trace. Mutually exclusive with sessionId, experimentId. Returns HTTP
400 when used without traceId.
required: false
schema:
type: string
nullable: true
- name: experimentId
in: query
description: >-
Comma-separated list of dataset run IDs (experiment IDs) to filter
by. Mutually exclusive with traceId, sessionId, observationId.
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: Inclusive lower bound on the score timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: Exclusive upper bound on the score timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetScoresV3Response'
'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: *ref_0
/api/public/scores:
post:
description: >-
Create a score (supports trace, observation, session, and dataset run
scores)
operationId: scores_create
tags:
- Scores
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreResponse'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreRequest'
/api/public/v2/scores:
get:
description: |-
**Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
is no longer available on Langfuse v4 and later.
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. Maximum 100. Defaults to 50. Requests with
a limit greater than 100 return HTTP 400. 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: *ref_0
/api/public/v2/scores/{scoreId}:
get:
description: |-
**Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
instead. This endpoint is no longer available on Langfuse v4 and later.
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: *ref_0
/api/public/sessions:
get:
description: >-
Get sessions.
This legacy endpoint is not recommended for new data extraction
workflows.
Use the v2 observations endpoint with a bounded time range and group
rows by
`sessionId` instead:
`GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
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: *ref_0
/api/public/sessions/{sessionId}:
get:
description: >-
Get a session.
Please note that `traces` on this endpoint are not paginated. For large
sessions or new data extraction workflows, use the v2 observations
endpoint
with a URL-encoded `sessionId` filter and a bounded time range:
`GET /api/public/v2/observations?filter=<sessionId
filter>&fromStartTime=<from>&toStartTime=<to>`.
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: *ref_0
/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: *ref_0
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: *ref_0
/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", "booleanObject", "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: "=", ">", "<", ">=", "<="
// - booleanObject: "=", "<>"
// - 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, booleanObject, and categoryOptions types when filtering on nested fields like metadata or score names
}
]
```
## 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
- `score_booleans` (booleanObject) - Boolean score values. Use `key`
for the score name and a boolean `value`, e.g. `{"type":
"booleanObject", "column": "score_booleans", "key": "is_correct",
"operator": "=", "value": true}`. The `<>` operator also matches
traces without a score of that name.
## 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: *ref_0
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: *ref_0
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/dashboard-widgets:
get:
description: |-
List dashboard widgets in the project, ordered by most recently
updated first.
Responses may include legacy `traces` widgets created before this
API existed. New widgets cannot be created with `view: traces`.
operationId: unstable_dashboardWidgets_list
tags:
- UnstableDashboardWidgets
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/unstableDashboardWidgetList'
'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: *ref_0
post:
description: >-
Create a dashboard widget (a standalone chart definition you place on
any dashboard).
This endpoint creates the widget only; place it on a dashboard via
`POST /dashboards/{dashboardId}/placements`.
Supported views are `observations`, `scores-numeric`, `scores-boolean`,
and `scores-categorical`.
The legacy `traces` view is not supported by this unstable API.
Widgets are created as v2 internally.
`chartConfig` is optional and defaults to the plain config for
`chartType`; when `chartConfig.type` is given it must match
`chartType`.
Unstable API note:
- This surface may evolve while dashboard/widget APIs are being
finalized.
operationId: unstable_dashboardWidgets_create
tags:
- UnstableDashboardWidgets
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'
/api/public/unstable/dashboard-widgets/{widgetId}:
get:
description: |-
Get a dashboard widget by id.
The response may use `view: traces` for legacy widgets.
operationId: unstable_dashboardWidgets_get
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'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: *ref_0
patch:
description: |-
Update a dashboard widget.
All fields are optional; at least one field is required.
Changing `chartType` without sending `chartConfig` resets the config
to the new chart type's defaults. When `chartConfig.type` is given
it must match the widget's (possibly updated) `chartType`.
`view` cannot be changed to the legacy `traces` value. Existing
`traces` widgets may be updated on other fields.
operationId: unstable_dashboardWidgets_update
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest'
delete:
description: |-
Delete a dashboard widget.
The API returns `409` while the widget is still placed on a dashboard.
Remove those placements first.
operationId: unstable_dashboardWidgets_delete
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'
'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'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
/api/public/unstable/dashboards:
get:
description: |-
List dashboards in the project, ordered by most recently updated
first.
operationId: unstable_dashboards_list
tags:
- UnstableDashboards
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/unstableDashboardList'
'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: *ref_0
post:
description: Create a dashboard.
operationId: unstable_dashboards_create
tags:
- UnstableDashboards
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardRequest'
/api/public/unstable/dashboards/{dashboardId}:
get:
description: Get a dashboard by id.
operationId: unstable_dashboards_get
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'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: *ref_0
patch:
description: Update a dashboard's name, description, definition, or filters.
operationId: unstable_dashboards_update
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardRequest'
delete:
description: Delete a dashboard.
operationId: unstable_dashboards_delete
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardResponse'
'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: *ref_0
/api/public/unstable/dashboards/{dashboardId}/placements:
post:
description: |-
Add a placement to a dashboard grid (see `DashboardPlacement` for
grid semantics).
`id` and the position fields are optional: when omitted, the
placement gets a server-generated id and is appended below all
existing tiles as a 6x6 tile. Returns the created placement.
The referenced widget must exist in the same project or be a
Langfuse-managed widget. The API returns `409` if a placement with
the same `id` already exists on the dashboard.
operationId: unstable_dashboards_addPlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardPlacement'
'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'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardPlacementRequest'
/api/public/unstable/dashboards/{dashboardId}/placements/{placementId}:
patch:
description: |-
Move or resize a placement. All fields are optional; at least one is
required. Omitted fields keep their current value. The placement's
content (widget/preset reference) and id cannot change — delete and
re-add the placement to swap content. Returns the updated placement.
operationId: unstable_dashboards_updatePlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
- name: placementId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardPlacement'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'
delete:
description: >-
Remove a placement from a dashboard grid without deleting the referenced
widget.
operationId: unstable_dashboards_deletePlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
- name: placementId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse'
'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: *ref_0
/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`
- for `llm_as_judge` evaluators, every evaluator prompt variable must be
mapped exactly once
- for `code` evaluators, Langfuse uses the fixed code runtime mapping;
omit `mapping` in create and update requests
- for user-provided `llm_as_judge` mappings, `expected_output` and
`experiment_item_metadata` 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`: for `llm_as_judge` evaluators, 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`: for `llm_as_judge`, 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'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateEvaluationRuleRequest'
get:
description: >-
List evaluation rules in the authenticated project.
This includes legacy `trace` and `dataset` rules so they can be
inspected and migrated to v4 rules. Legacy rules are read-only through
this API; create, update, and delete continue to support only
`observation` and `experiment` rules.
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: *ref_0
/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, execution timing, and effective runtime status. Legacy `trace`
and `dataset` rules are returned for migration and are read-only through
this API.
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/unstableReadableEvaluationRule'
'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: *ref_0
patch:
description: >-
Update an evaluation rule.
Typical uses:
- enable or disable live execution
- switch to another evaluator
- adjust sampling
- change filters
- update LLM-as-judge 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 an LLM-as-judge `mapping` must still
produce a valid target-specific configuration
- if you change `target` for an LLM-as-judge rule, also send a
compatible `filter` and `mapping` in the same request unless the
existing ones are still valid for the new target
- for `code` evaluator rules, omit `mapping`; Langfuse stores the fixed
code runtime mapping automatically
- 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 an LLM-as-judge 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: *ref_0
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: *ref_0
/api/public/unstable/evaluators:
post:
description: >-
Create an evaluator in the authenticated project.
Use evaluators to define **how** Langfuse should score data.
LLM-as-a-judge evaluators define a prompt, expected structured output,
and optional model configuration.
Code evaluators define source code and a runtime language.
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`.
Code evaluator validation:
- At creation, Langfuse only validates the request shape
- The `sourceCode` itself is not executed here. It is first run
(preflight-tested against a sample observation) when you link the
evaluator to an evaluation rule, so runtime errors in the code surface
at evaluation-rule creation, not at evaluator creation.
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`: for
`type=llm_as_judge`, send `dataType`, `reasoning.description`, and
`score.description`. Do not send `version`; it is not part of the public
request shape.
- If `type` is omitted, Langfuse treats the request as
`type=llm_as_judge` for backwards compatibility. New clients should send
`type` explicitly.
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'
'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: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateEvaluatorRequest'
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: *ref_0
/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: *ref_0
delete:
description: >-
Delete an evaluator.
Important behavior:
- This deletes the evaluator including all of its stored versions;
`evaluatorId` may reference any version.
- The API returns `409` while evaluation rules still reference the
evaluator. Delete those evaluation rules first.
- Langfuse-managed evaluators (`scope=managed`) cannot be deleted; the
API returns `403`.
- Scores already produced by the evaluator are not deleted.
operationId: unstable_evaluators_delete
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/unstableDeleteEvaluatorResponse'
'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'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
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
- description
- 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
- PARQUET
description: >-
File format for exported data. `PARQUET` is a columnar binary format
encoded and compressed by the storage engine; gzip compression does not
apply to it. Note that the model-price columns (`input_price`,
`output_price`, `total_price`) are not included in Parquet observation
exports.
BlobStorageIntegrationFileTypeResponse:
title: BlobStorageIntegrationFileTypeResponse
type: string
enum:
- JSON
- CSV
- JSONL
- PARQUET
description: File type reported for an existing integration.
BlobStorageExportMode:
title: BlobStorageExportMode
type: string
enum:
- FULL_HISTORY
- FROM_TODAY
- FROM_CUSTOM_DATE
BlobStorageExportFrequency:
title: BlobStorageExportFrequency
type: string
enum:
- every_20_minutes
- hourly
- daily
- weekly
BlobStorageExportSource:
title: BlobStorageExportSource
type: string
enum:
- LEGACY_TRACES_OBSERVATIONS
- OBSERVATIONS_V2
- LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS
description: >-
What data the integration exports.
- `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables.
Observation columns are controlled by `exportFieldGroups`; field groups
without a counterpart in this data model (e.g. `trace_context`) are
omitted.
- `OBSERVATIONS_V2`: same data model as the
`/api/public/v2/observations` endpoint, plus scores. Columns are
controlled by `exportFieldGroups`.
- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation
columns of both portions are controlled by `exportFieldGroups`.
**Note:** `OBSERVATIONS_V2` and the enriched-observations portion of
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` rely on the enriched
observations table (Langfuse Fast Preview / v4), which is currently
available on Langfuse Cloud only. See https://langfuse.com/docs/v4.
BlobStorageExportFieldGroup:
title: BlobStorageExportFieldGroup
type: string
enum:
- core
- basic
- time
- io
- metadata
- model
- usage
- prompt
- metrics
- tools
- trace_context
description: >-
Field group selecting which observation columns are included in the
export. Applies to all export sources; groups without a counterpart in
the legacy data model (e.g. `trace_context`) are omitted from the legacy
observations export.
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). Must not be in the future (27 h tolerance for
timezone differences).
compressed:
type: boolean
nullable: true
description: >-
Enable gzip compression for exported files (.csv.gz, .json.gz,
.jsonl.gz). Defaults to true.
exportSource:
$ref: '#/components/schemas/BlobStorageExportSource'
nullable: true
description: >-
Data to export. When omitted on update, the existing value is
preserved. When omitted on create: integrations on Langfuse Cloud
default to `OBSERVATIONS_V2`; self-hosted deployments fall back to
`LEGACY_TRACES_OBSERVATIONS`. Required when `exportFieldGroups` is
provided.
**Cloud-only project deprecation gate (effective 2026-05-20):** For
projects created on or after 2026-05-20 on Langfuse Cloud,
`LEGACY_TRACES_OBSERVATIONS` and
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted
deployments are unaffected.
**Cloud-only integration deprecation gate (effective 2026-06-22):**
On Langfuse Cloud, legacy export sources are only accepted for blob
storage integrations created before 2026-06-22, regardless of
project age. Requests that would create a new integration with
`LEGACY_TRACES_OBSERVATIONS` or
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are
unaffected.
exportFieldGroups:
type: array
items:
$ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
Field groups to include in each exported observation row. Applies to
all export sources; must include `core` if provided. When omitted on
create, the column default (all groups) applies. When omitted on
update, the existing value is preserved.
`exportFieldGroups` requires `exportSource` to be provided in the
same request.
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/BlobStorageIntegrationFileTypeResponse'
exportMode:
$ref: '#/components/schemas/BlobStorageExportMode'
exportStartDate:
type: string
format: date-time
nullable: true
compressed:
type: boolean
exportSource:
$ref: '#/components/schemas/BlobStorageExportSource'
exportFieldGroups:
type: array
items:
$ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
Field groups included in each exported observation row. An empty
list is treated as all groups during export.
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
- endpoint
- region
- accessKeyId
- prefix
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
- exportStartDate
- compressed
- exportSource
- exportFieldGroups
- nextSyncAt
- lastSyncAt
- lastError
- lastErrorAt
- 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
- running
- 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)
- `running` — an export job is currently being processed
- `queued` — next export is overdue (`nextSyncAt` is in the past) and
waiting to be picked up by the worker
- `idle` — enabled but has never exported yet and no export is queued
- `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 20-minute lag buffer,
so `lastSyncAt` will always be at least 20 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
- lastSyncAt
- nextSyncAt
- lastError
- lastErrorAt
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. Must be a member of the
organization that owns the project, otherwise an error will be
thrown.
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
Deprecation:
title: Deprecation
type: object
description: >-
Migration signal returned by deprecated endpoints. Optional fields are
omitted when they have no value.
properties:
message:
type: string
description: >-
Human- and agent-readable summary of the deprecation and its
replacement.
replacement:
type: string
nullable: true
description: >-
The replacement endpoint, e.g. "GET /api/public/v2/observations".
Omitted when the endpoint is being removed without a direct
replacement.
docsUrl:
type: string
nullable: true
description: Link to the migration documentation (markdown), when available.
sunsetAt:
type: string
nullable: true
description: >-
ISO date after which the endpoint may stop working, when a removal
date is committed.
required:
- message
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
- name
- sessionId
- release
- version
- userId
- 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
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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
- traceId
- type
- name
- startTime
- endTime
- completionStartTime
- model
- modelParameters
- input
- version
- metadata
- output
- usage
- level
- statusMessage
- parentObservationId
- promptId
- 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
required:
- promptName
- promptVersion
- modelId
- inputPrice
- outputPrice
- totalPrice
- calculatedInputCost
- calculatedOutputCost
- calculatedTotalCost
- latency
- timeToFirstToken
allOf:
- $ref: '#/components/schemas/Observation'
ObservationsViewSingle:
title: ObservationsViewSingle
type: object
properties:
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
allOf:
- $ref: '#/components/schemas/ObservationsView'
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 physical parent observation ID, if present.
Observations marked as app roots by the SDK may retain a non-null
parent ID.
type:
type: string
description: The type of the observation (e.g. GENERATION, SPAN, EVENT)
isRootObservation:
type: boolean
nullable: true
description: >-
Whether this observation is a logical root.
This is true for observations without a physical parent and
observations marked as app roots by the SDK.
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
usagePricingTierName:
type: string
nullable: true
description: >-
The name of the pricing tier applied to this observation's usage
costs
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. Null when the `model` field group is not
requested.
inputPrice:
type: string
nullable: true
description: >-
The input token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
outputPrice:
type: string
nullable: true
description: >-
The output token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
totalPrice:
type: string
nullable: true
description: >-
The total token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
traceName:
type: string
nullable: true
description: The name of the parent trace
tags:
type: array
items:
type: string
nullable: true
description: Tags from the parent trace (denormalized onto the observation)
release:
type: string
nullable: true
description: The release version of the parent trace
required:
- id
- traceId
- startTime
- endTime
- projectId
- parentObservationId
- type
- modelId
- inputPrice
- outputPrice
- totalPrice
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
- unit
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
- authorUserId
- comment
- metadata
- configId
- queueId
- 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
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScoreV1'
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
- authorUserId
- comment
- metadata
- configId
- queueId
- 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
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/CorrectionScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScore'
required:
- dataType
properties:
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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
- description
- metadata
- inputSchema
- expectedOutputSchema
- 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
mediaReferences:
type: array
items:
$ref: '#/components/schemas/DatasetItemMediaReference'
description: >-
Resolved Langfuse media references found in input, expectedOutput,
and metadata.
required:
- id
- status
- input
- expectedOutput
- metadata
- sourceTraceId
- sourceObservationId
- datasetId
- datasetName
- createdAt
- updatedAt
- mediaReferences
DatasetItemMediaReference:
title: DatasetItemMediaReference
type: object
properties:
field:
$ref: '#/components/schemas/DatasetItemMediaReferenceField'
description: The dataset item field containing the reference
referenceString:
type: string
description: >-
The Langfuse media reference string, e.g.
`@@@langfuseMedia:type=image/png|id=...|source=bytes@@@`
jsonPath:
type: string
description: >-
JSONPath of the string holding the reference within the field, e.g.
`$['image']`
media:
$ref: '#/components/schemas/DatasetItemMediaReferenceMedia'
description: The resolved media record.
required:
- field
- referenceString
- jsonPath
- media
DatasetItemMediaReferenceField:
title: DatasetItemMediaReferenceField
type: string
enum:
- input
- expectedOutput
- metadata
DatasetItemMediaReferenceMedia:
title: DatasetItemMediaReferenceMedia
type: object
properties:
mediaId:
type: string
description: The unique langfuse identifier of the 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
url:
type: string
description: The signed download URL of the media record
urlExpiry:
type: string
description: The expiry date and time of the download URL
required:
- mediaId
- contentType
- contentLength
- url
- urlExpiry
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
- observationId
- 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
- description
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunWithItems:
title: DatasetRunWithItems
type: object
properties:
datasetRunItems:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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
- startDate
- inputPrice
- outputPrice
- totalPrice
- tokenizerId
- 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: number
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), cannot be reused across datasets, and must be at
most 255 characters.
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'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
DeleteDatasetRunResponse:
title: DeleteDatasetRunResponse
type: object
properties:
message:
type: string
required:
- message
ExperimentsResponse:
title: ExperimentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Experiment'
meta:
$ref: '#/components/schemas/ExperimentsResponseMeta'
required:
- data
- meta
ExperimentsResponseMeta:
title: ExperimentsResponseMeta
type: object
properties:
cursor:
type: string
nullable: true
description: >-
Versioned base64url cursor for retrieving the next page. Absent when
there are no more results.
Experiment:
title: Experiment
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
startTime:
type: string
format: date-time
description: |-
Start of the experiment, i.e. the earliest event within the
requested time range. Clipped to `fromStartTime` when the
experiment started before the requested range.
endTime:
type: string
format: date-time
description: |-
End of the experiment, i.e. the latest event end within the
requested time range.
itemCount:
type: integer
description: Number of experiment items within the requested time range.
datasetId:
type: string
nullable: true
description: Null when the experiment is not associated with a dataset.
metadata:
type: object
additionalProperties: true
nullable: true
description: Included only when `fields=metadata` is requested.
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
nullable: true
description: >-
Included only when `fields=scores` is requested. Contains scores
directly attached to the experiment.
required:
- id
- name
- description
- startTime
- endTime
- itemCount
- datasetId
ExperimentItemsResponse:
title: ExperimentItemsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ExperimentItem'
meta:
$ref: '#/components/schemas/ExperimentsResponseMeta'
required:
- data
- meta
ExperimentItem:
title: ExperimentItem
type: object
properties:
id:
type: string
traceId:
type: string
startTime:
type: string
format: date-time
endTime:
type: string
format: date-time
nullable: true
level:
$ref: '#/components/schemas/ObservationLevel'
environment:
type: string
experimentId:
type: string
experimentName:
type: string
experimentItemId:
type: string
experimentDatasetId:
type: string
nullable: true
description: Included when `fields=dataset` is requested.
experimentItemVersion:
type: string
format: date-time
nullable: true
description: Included when `fields=dataset` is requested.
input:
nullable: true
description: Included when `fields=io` is requested.
output:
nullable: true
description: Included when `fields=io` is requested.
expectedOutput:
nullable: true
description: Included when `fields=io` is requested.
metadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=metadata` is requested.
experimentItemMetadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=itemMetadata` is requested.
experimentMetadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=experimentMetadata` is requested.
experimentDescription:
type: string
nullable: true
description: Included when `fields=experimentMetadata` is requested.
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
nullable: true
description: >-
Included only when `fields=scores` is requested. Contains item and
trace scores only; experiment-level scores are returned by the
experiments endpoint.
required:
- id
- traceId
- startTime
- endTime
- level
- environment
- experimentId
- experimentName
- experimentItemId
FeedbackTargetType:
title: FeedbackTargetType
type: string
enum:
- skill
- mcp-tool
- cli
- docs
- public-api
- other
SubmitFeedbackRequest:
title: SubmitFeedbackRequest
type: object
properties:
targetType:
$ref: '#/components/schemas/FeedbackTargetType'
description: Category of the thing the feedback is about.
target:
type: string
description: >-
The specific instance within targetType: the skill name, MCP tool
name, CLI command, API endpoint path, or docs page path (e.g.
'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be
between 1 and 200 characters.
feedback:
type: string
description: >-
Concise feedback text approved by the user. Must be between 1 and
3000 characters.
goal:
type: string
nullable: true
description: >-
Optional user-approved goal or use case they were trying to achieve.
Must be between 1 and 1500 characters when provided. Do not include
secrets, customer data, trace payloads, or broad unrelated context.
referenceUrl:
type: string
nullable: true
description: >-
Optional HTTP(S) reference URL. Langfuse stores it as text for
triage and does not fetch it.
required:
- targetType
- target
- feedback
SubmitFeedbackResponse:
title: SubmitFeedbackResponse
type: object
properties:
id:
type: string
description: Correlation ID for the submitted feedback.
required:
- id
HealthResponse:
title: HealthResponse
type: object
properties:
version:
type: string
description: Langfuse server version
status:
type: string
required:
- version
- status
IngestionEvent:
title: IngestionEvent
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- trace-create
- $ref: '#/components/schemas/TraceEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- score-create
- $ref: '#/components/schemas/ScoreEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-create
- $ref: '#/components/schemas/CreateSpanEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-update
- $ref: '#/components/schemas/UpdateSpanEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-create
- $ref: '#/components/schemas/CreateGenerationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-update
- $ref: '#/components/schemas/UpdateGenerationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- event-create
- $ref: '#/components/schemas/CreateEventEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- sdk-log
- $ref: '#/components/schemas/SDKLogEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-create
- $ref: '#/components/schemas/CreateObservationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-update
- $ref: '#/components/schemas/UpdateObservationEvent'
required:
- type
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.
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.
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
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 OpenAI
(`{"useResponsesApi":true}`), 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"}`) - **OpenAI**: Optional. If provided, must
be `{"useResponsesApi": <boolean>}` to control whether Langfuse
routes calls through OpenAI's Responses API. - **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
description: >-
Request a presigned media upload URL. Provide exactly one context: a
trace (traceId, optionally observationId) or a dataset item (datasetId +
datasetItemId). field is required and must match the chosen context.
properties:
traceId:
type: string
nullable: true
description: >-
The trace the media is associated with. Null for dataset item media
uploads.
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.
datasetId:
type: string
nullable: true
description: >-
The dataset the media belongs to. Null for trace/observation media
uploads.
datasetItemId:
type: string
nullable: true
description: >-
The dataset item the media is associated with (need not exist yet).
Null for trace/observation media uploads.
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 item field the media is in: `input`/`output`/`metadata` (trace)
or `input`/`expectedOutput`/`metadata` (dataset item).
required:
- 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
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- chat
- $ref: '#/components/schemas/ChatPrompt'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- text
- $ref: '#/components/schemas/TextPrompt'
required:
- type
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
ScoreSubjectTraceV3:
title: ScoreSubjectTraceV3
type: object
properties:
id:
type: string
description: The trace ID.
required:
- id
ScoreSubjectObservationV3:
title: ScoreSubjectObservationV3
type: object
properties:
id:
type: string
description: The observation ID.
traceId:
type: string
nullable: true
description: The parent trace ID, if available.
required:
- id
ScoreSubjectSessionV3:
title: ScoreSubjectSessionV3
type: object
properties:
id:
type: string
description: The session ID.
required:
- id
ScoreSubjectExperimentV3:
title: ScoreSubjectExperimentV3
type: object
properties:
id:
type: string
description: The dataset run ID (experiment ID).
required:
- id
ScoreSubjectV3:
title: ScoreSubjectV3
oneOf:
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- trace
- $ref: '#/components/schemas/ScoreSubjectTraceV3'
required:
- kind
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- observation
- $ref: '#/components/schemas/ScoreSubjectObservationV3'
required:
- kind
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- session
- $ref: '#/components/schemas/ScoreSubjectSessionV3'
required:
- kind
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- experiment
- $ref: '#/components/schemas/ScoreSubjectExperimentV3'
required:
- kind
description: >-
A reference to the entity this score is attached to. Discriminated by
"kind" — one of trace, observation, session, or experiment.
BaseScoreV3:
title: BaseScoreV3
type: object
properties:
id:
type: string
projectId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
timestamp:
type: string
format: date-time
environment:
type: string
description: The environment from which this score originated.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
comment:
type: string
nullable: true
description: >-
Optional comment attached to the score. Present when "details" is
included in the fields parameter.
configId:
type: string
nullable: true
description: >-
The score config ID, if this score was created from a config.
Present when "details" is included in the fields parameter.
metadata:
type: object
additionalProperties: true
nullable: true
description: >-
Arbitrary metadata attached to the score. Present when "details" is
included in the fields parameter.
authorUserId:
type: string
nullable: true
description: >-
The user who created this score, if available. Present when
"annotation" is included in the fields parameter.
queueId:
type: string
nullable: true
description: >-
The annotation queue this score belongs to, if any. Present when
"annotation" is included in the fields parameter.
subject:
$ref: '#/components/schemas/ScoreSubjectV3'
nullable: true
description: >-
The entity this score is attached to (trace, observation, session,
or experiment). Present when "subject" is included in the fields
parameter.
required:
- id
- projectId
- name
- source
- timestamp
- environment
- createdAt
- updatedAt
NumericScoreV3:
title: NumericScoreV3
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
BooleanScoreV3:
title: BooleanScoreV3
type: object
properties:
value:
type: boolean
description: The boolean value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
CategoricalScoreV3:
title: CategoricalScoreV3
type: object
properties:
value:
type: string
description: The string category value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
TextScoreV3:
title: TextScoreV3
type: object
properties:
value:
type: string
description: The text content of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
CorrectionScoreV3:
title: CorrectionScoreV3
type: object
properties:
value:
type: string
description: The correction content of the score. Empty string if not set.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
ScoreV3:
title: ScoreV3
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV3'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV3'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV3'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScoreV3'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/CorrectionScoreV3'
required:
- dataType
GetScoresV3Meta:
title: GetScoresV3Meta
type: object
properties:
limit:
type: integer
cursor:
type: string
nullable: true
description: >-
URL-safe base64 (base64url) cursor for the next page. Absent when
there are no more results.
required:
- limit
GetScoresV3Response:
title: GetScoresV3Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
meta:
$ref: '#/components/schemas/GetScoresV3Meta'
required:
- data
- meta
CreateScoreRequest:
title: CreateScoreRequest
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
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/CreateScoreSource'
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
CreateScoreSource:
title: CreateScoreSource
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.
CreateScoreResponse:
title: CreateScoreResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
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
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/GetScoresResponseDataNumeric'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/GetScoresResponseDataCategorical'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/GetScoresResponseDataBoolean'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/GetScoresResponseDataCorrection'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/GetScoresResponseDataText'
required:
- dataType
GetScoresResponse:
title: GetScoresResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GetScoresResponseData'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
PaginatedSessions:
title: PaginatedSessions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Session'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
Traces:
title: Traces
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TraceWithDetails'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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
- code
description: |-
The evaluator engine type.
The unstable public API supports LLM-as-a-judge and code evaluators.
unstableCodeEvaluatorSourceCodeLanguage:
title: unstableCodeEvaluatorSourceCodeLanguage
type: string
enum:
- PYTHON
- TYPESCRIPT
description: Code evaluator runtime language.
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`, `metadata`, and `tool_calls`.
- `experiment` evaluates live experiment executions and can additionally
map `expected_output` and `experiment_item_metadata`.
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
- tool_calls
- expected_output
- experiment_item_metadata
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`, `metadata`, and
`tool_calls`
- `target=experiment` supports `input`, `output`, `metadata`,
`tool_calls`, `expected_output`, and `experiment_item_metadata`
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.
- `tool_calls`: the tool calls recorded on the observation, as an array
of `{id, name, arguments, type, index}` objects in the order the model
emitted them. Combine with `jsonPath` (for example `$[*].name`) to
select parts of each call.
- `expected_output`: the experiment item's expected output. Only valid
for `target=experiment`.
- `experiment_item_metadata`: the experiment item's metadata object.
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.
model:
type: string
description: >-
Model identifier exposed by the provider, for 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
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: >-
#/components/schemas/unstablePublicNumericEvaluatorOutputDefinition
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: >-
#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinition
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: >-
#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinition
required:
- dataType
description: >-
Structured output definition to send when creating an evaluator.
Agent guidance:
- `dataType` is required.
- Do not send `version`; that is an internal storage detail and is not
part of the public request contract.
- For `NUMERIC` and `BOOLEAN`, provide `reasoning.description` and
`score.description`.
- For `CATEGORICAL`, also provide `score.categories` and
`score.shouldAllowMultipleMatches`.
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
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: >-
#/components/schemas/unstablePublicNumericEvaluatorOutputDefinition
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: >-
#/components/schemas/unstablePublicBooleanEvaluatorOutputDefinition
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: >-
#/components/schemas/unstablePublicCategoricalEvaluatorOutputDefinition
required:
- dataType
description: >-
Evaluator output definition returned by the public API.
This response always includes `dataType` and never includes an internal
output-definition `version`.
Legacy stored evaluator definitions are normalized into this shape
before they are returned.
Use this response shape when deciding how to interpret future evaluation
scores:
- `NUMERIC`: expect numeric score values
- `BOOLEAN`: expect `true` / `false`
- `CATEGORICAL`: expect one or more values from `score.categories`
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 variable to one source field from the target object.
Manual mappings are used for `llm_as_judge` evaluators. `code`
evaluators use a fixed runtime mapping managed by Langfuse.
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 LLM-as-judge 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`.
source:
$ref: '#/components/schemas/unstableEvaluationRuleMappingSource'
description: >-
Source field that should populate the prompt variable.
Quick reference:
- `target=observation`: `input`, `output`, `metadata`, `tool_calls`
- `target=experiment`: `input`, `output`, `metadata`, `tool_calls`,
`expected_output`, `experiment_item_metadata`
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
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- datetime
- $ref: '#/components/schemas/unstableDateTimeEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- string
- $ref: '#/components/schemas/unstableStringEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- number
- $ref: '#/components/schemas/unstableNumberEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- stringOptions
- $ref: '#/components/schemas/unstableStringOptionsEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- categoryOptions
- $ref: '#/components/schemas/unstableCategoryOptionsEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- arrayOptions
- $ref: '#/components/schemas/unstableArrayOptionsEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- stringObject
- $ref: '#/components/schemas/unstableStringObjectEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- numberObject
- $ref: '#/components/schemas/unstableNumberObjectEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- boolean
- $ref: '#/components/schemas/unstableBooleanEvaluationRuleFilter'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- 'null'
- $ref: '#/components/schemas/unstableNullEvaluationRuleFilter'
required:
- type
description: >-
One filter condition used to decide whether a live-ingested target
should be evaluated.
An evaluation rule can include zero or more filter objects. All filters
must be satisfied for the target to run.
How to build a valid filter object:
- Pick the `target` first, because it changes the supported columns.
- Pick the filter `type`. That determines which fields are required.
- Use `key` only for object filters such as `metadata`.
- Use the correct `value` shape for the chosen filter `type`.
Operator quick reference by filter `type`:
- `string`: `"="`, `contains`, `does not contain`, `starts with`, `ends
with`
- `number`: `"="`, `">"`, `"<"`, `">="`, `"<="`
- `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
- `stringOptions`: `any of`, `none of`
- `arrayOptions`: `any of`, `none of`, `all of`
- `stringObject`: same operators as `string`
- `boolean`: `"="`, `"<>"`
- `null`: `is null`, `is not null`
Supported columns by target:
- `target=observation`
- `type`: `stringOptions`, operators `any of` / `none of`, values `GENERATION`, `SPAN`, `EVENT`
- `name`: `stringOptions`, operators `any of` / `none of`
- `environment`: `stringOptions`, operators `any of` / `none of`
- `level`: `stringOptions`, operators `any of` / `none of`, values `DEBUG`, `DEFAULT`, `WARNING`, `ERROR`
- `version`: `string`
- `traceName`: `stringOptions`, operators `any of` / `none of`
- `userId`: `string`
- `sessionId`: `string`
- `tags`: `arrayOptions`, operators `any of` / `none of` / `all of`
- `metadata`: `stringObject` with `key`
- `isRootObservation`: `boolean`, operators `=` / `<>`; true when the observation has no parent or is explicitly marked as an application root
- `parentObservationId`: `null`, operators `is null` / `is not null`
- `calledToolNames`: `arrayOptions`, operators `any of` / `none of` / `all of`
- `toolCalls`: `number`
- `target=experiment`
- `datasetId`: `stringOptions`, operators `any of` / `none of`
Use dataset `id` values from `GET /api/public/v2/datasets`, not dataset names.
Recovery guidance:
- `invalid_filter_value` with `details.column` but no `invalidValues`:
the selected `column` is not supported for the chosen `target`
- `invalid_filter_value` with `details.invalidValues`: the selected
values are not allowed for that column. Replace them with one of
`details.allowedValues` when provided.
- `invalid_filter_value` for `column=datasetId`: call `GET
/api/public/v2/datasets`, then retry with dataset `id` values from that
response.
unstableDashboardWidgetView:
title: unstableDashboardWidgetView
type: string
enum:
- observations
- scores-numeric
- scores-boolean
- scores-categorical
unstableDashboardWidgetViewWithLegacy:
title: unstableDashboardWidgetViewWithLegacy
type: string
enum:
- observations
- scores-numeric
- scores-boolean
- scores-categorical
- traces
description: |-
Widget data view. Responses may include the legacy `traces` value for
widgets created before this API existed.
unstableDashboardWidgetChartType:
title: unstableDashboardWidgetChartType
type: string
enum:
- LINE_TIME_SERIES
- AREA_TIME_SERIES
- BAR_TIME_SERIES
- HORIZONTAL_BAR
- VERTICAL_BAR
- PIE
- NUMBER
- HISTOGRAM
- PIVOT_TABLE
unstableDashboardWidgetMetricAggregation:
title: unstableDashboardWidgetMetricAggregation
type: string
enum:
- sum
- avg
- count
- max
- min
- p50
- p75
- p90
- p95
- p99
- histogram
- uniq
unstableDashboardWidgetDimension:
title: unstableDashboardWidgetDimension
type: object
properties:
field:
type: string
required:
- field
unstableDashboardWidgetMetric:
title: unstableDashboardWidgetMetric
type: object
properties:
measure:
type: string
agg:
$ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation'
required:
- measure
- agg
unstableDashboardWidgetFilter:
title: unstableDashboardWidgetFilter
type: object
description: >-
A filter in Langfuse filter-state shape. The `value` shape and the
allowed operators depend on `type`:
| `type` | `value` | operators |
|---|---|---|
| `string` | string | `=`, `contains`, `does not contain`, `starts
with`, `ends with` |
| `number` | number | `=`, `>`, `<`, `>=`, `<=` |
| `datetime` | ISO datetime string | `>`, `<`, `>=`, `<=` |
| `boolean` | boolean | `=`, `<>` |
| `null` | `""` | `is null`, `is not null` |
| `stringOptions` | list of strings | `any of`, `none of` |
| `arrayOptions` | list of strings | `any of`, `none of`, `all of` |
| `categoryOptions` | list of strings (requires `key`) | `any of`, `none
of` |
| `stringObject` | string (requires `key`, e.g. a metadata key) | same
as `string` |
| `numberObject` | number (requires `key`, e.g. a score name) | same as
`number` |
| `booleanObject` | boolean (requires `key`) | `=`, `<>` |
properties:
column:
type: string
operator:
type: string
type:
type: string
value:
nullable: true
key:
type: string
nullable: true
required:
- column
- operator
- type
unstableDashboardWidgetChartConfig:
title: unstableDashboardWidgetChartConfig
type: object
description: |-
Chart-specific widget configuration.
`type` must match the top-level `chartType`.
`row_limit` applies to total-value charts and pivot tables.
`bins` applies to histograms.
`defaultSort` applies to pivot tables.
properties:
type:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
row_limit:
type: integer
nullable: true
show_value_labels:
type: boolean
nullable: true
bins:
type: integer
nullable: true
defaultSort:
$ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
nullable: true
required:
- type
unstableDashboardWidgetDefaultSort:
title: unstableDashboardWidgetDefaultSort
type: object
properties:
column:
type: string
order:
$ref: '#/components/schemas/unstableDashboardWidgetSortOrder'
required:
- column
- order
unstableDashboardWidgetSortOrder:
title: unstableDashboardWidgetSortOrder
type: string
enum:
- ASC
- DESC
unstableDashboardWidgetChartConfigInput:
title: unstableDashboardWidgetChartConfigInput
type: object
description: |-
Input-side chart config. `type` is optional and defaults to the
widget's `chartType`; when given it must match.
properties:
type:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
nullable: true
row_limit:
type: integer
nullable: true
show_value_labels:
type: boolean
nullable: true
bins:
type: integer
nullable: true
defaultSort:
$ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
nullable: true
unstableCreateDashboardWidgetRequest:
title: unstableCreateDashboardWidgetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
description: Defaults to an empty string.
view:
$ref: '#/components/schemas/unstableDashboardWidgetView'
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
nullable: true
description: Defaults to the plain config for `chartType`.
required:
- name
- view
- dimensions
- metrics
- filters
- chartType
unstableUpdateDashboardWidgetRequest:
title: unstableUpdateDashboardWidgetRequest
type: object
properties:
name:
type: string
nullable: true
description:
type: string
nullable: true
view:
$ref: '#/components/schemas/unstableDashboardWidgetView'
nullable: true
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
nullable: true
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
nullable: true
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
nullable: true
unstableDashboardWidgetList:
title: unstableDashboardWidgetList
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidget'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableDeleteDashboardWidgetResponse:
title: unstableDeleteDashboardWidgetResponse
type: object
properties:
message:
type: string
required:
- message
unstableDashboardWidget:
title: unstableDashboardWidget
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
description:
type: string
view:
$ref: '#/components/schemas/unstableDashboardWidgetViewWithLegacy'
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfig'
required:
- id
- createdAt
- updatedAt
- name
- description
- view
- dimensions
- metrics
- filters
- chartType
- chartConfig
unstableDashboardPlacement:
title: unstableDashboardPlacement
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- widget
- $ref: '#/components/schemas/unstableWidgetPlacement'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- preset
- $ref: '#/components/schemas/unstablePresetPlacement'
required:
- type
description: |-
A tile on the dashboard's 12-column grid. `x`/`y` are the tile's
top-left cell (0-based; `y` grows downward), `width`/`height` its size
in cells. The UI default tile is 6x6 (half width). Overlapping tiles
are not rejected; prefer appending below existing tiles (or omit the
position on create to let the server do it).
unstableWidgetPlacement:
title: unstableWidgetPlacement
type: object
properties:
id:
type: string
widgetId:
type: string
x:
type: integer
'y':
type: integer
width:
type: integer
height:
type: integer
required:
- id
- widgetId
- x
- 'y'
- width
- height
unstablePresetPlacement:
title: unstablePresetPlacement
type: object
properties:
id:
type: string
presetId:
type: string
x:
type: integer
'y':
type: integer
width:
type: integer
height:
type: integer
required:
- id
- presetId
- x
- 'y'
- width
- height
unstableCreateDashboardPlacementRequest:
title: unstableCreateDashboardPlacementRequest
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- widget
- $ref: '#/components/schemas/unstableCreateWidgetPlacement'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- preset
- $ref: '#/components/schemas/unstableCreatePresetPlacement'
required:
- type
unstableCreateWidgetPlacement:
title: unstableCreateWidgetPlacement
type: object
properties:
id:
type: string
nullable: true
description: Server-generated when omitted.
widgetId:
type: string
x:
type: integer
nullable: true
description: Grid column (12-column grid). Defaults to `0`.
'y':
type: integer
nullable: true
description: Grid row. Defaults to the first row below all existing tiles.
width:
type: integer
nullable: true
description: Width in grid columns. Defaults to `6`.
height:
type: integer
nullable: true
description: Height in grid rows. Defaults to `6`.
required:
- widgetId
unstableCreatePresetPlacement:
title: unstableCreatePresetPlacement
type: object
properties:
id:
type: string
nullable: true
description: Server-generated when omitted.
presetId:
type: string
x:
type: integer
nullable: true
description: Grid column (12-column grid). Defaults to `0`.
'y':
type: integer
nullable: true
description: Grid row. Defaults to the first row below all existing tiles.
width:
type: integer
nullable: true
description: Width in grid columns. Defaults to `6`.
height:
type: integer
nullable: true
description: Height in grid rows. Defaults to `6`.
required:
- presetId
unstableUpdateDashboardPlacementRequest:
title: unstableUpdateDashboardPlacementRequest
type: object
properties:
x:
type: integer
nullable: true
description: Grid column (12-column grid).
'y':
type: integer
nullable: true
description: Grid row.
width:
type: integer
nullable: true
description: Width in grid columns.
height:
type: integer
nullable: true
description: Height in grid rows.
unstableDeleteDashboardPlacementResponse:
title: unstableDeleteDashboardPlacementResponse
type: object
properties:
message:
type: string
required:
- message
unstableDashboardDefinition:
title: unstableDashboardDefinition
type: object
properties:
widgets:
type: array
items:
$ref: '#/components/schemas/unstableDashboardPlacement'
required:
- widgets
unstableDashboard:
title: unstableDashboard
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
description:
type: string
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
description: Dashboard-level filters applied to all widgets on the dashboard.
required:
- id
- createdAt
- updatedAt
- name
- description
- definition
- filters
unstableDashboardList:
title: unstableDashboardList
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableDashboard'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableCreateDashboardRequest:
title: unstableCreateDashboardRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
required:
- name
unstableUpdateDashboardRequest:
title: unstableUpdateDashboardRequest
type: object
properties:
name:
type: string
nullable: true
description:
type: string
nullable: true
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
unstableDeleteDashboardResponse:
title: unstableDeleteDashboardResponse
type: object
properties:
message:
type: string
required:
- message
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.
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
unstableEvaluationRuleBase:
title: unstableEvaluationRuleBase
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.
name:
type: string
description: >-
Human-readable deployment name. This is independent from the
evaluator name.
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.
enabled:
type: boolean
description: Desired enabled state configured by the client.
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.
createdAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was last updated.
required:
- id
- name
- evaluator
- enabled
- status
- pausedReason
- pausedMessage
- sampling
- createdAt
- updatedAt
unstableEvaluationRule:
title: unstableEvaluationRule
type: object
properties:
target:
$ref: '#/components/schemas/unstableEvaluationRuleTarget'
description: Target object type that should trigger scoring.
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 evaluator runtime variables from
the live target object.
required:
- target
- filter
- mapping
allOf:
- $ref: '#/components/schemas/unstableEvaluationRuleBase'
unstableLegacyEvaluationRule:
title: unstableLegacyEvaluationRule
type: object
description: >-
Legacy trace- or dataset-level evaluation rule returned by list and get
for migration.
This resource is read-only through the unstable public API. Its mapping
preserves the trace, dataset item, or named observation that each
evaluator variable previously read from. Its filters use the persisted
legacy filter format so migration clients can read the configuration
without losing information.
properties:
target:
$ref: '#/components/schemas/unstableLegacyEvaluationRuleTarget'
delay:
type: integer
description: Delay in milliseconds before the legacy evaluation job runs.
timeScope:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleTimeScope'
description: >-
Whether the legacy rule evaluates newly ingested data, existing
data, or both.
filter:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleFilter'
description: Stored filters used by the legacy trace or dataset rule.
mapping:
type: array
items:
$ref: '#/components/schemas/unstableLegacyEvaluationRuleMapping'
description: >-
Stored variable mappings, including the trace, dataset item, or
named observation selected for each variable.
required:
- target
- delay
- timeScope
- filter
- mapping
allOf:
- $ref: '#/components/schemas/unstableEvaluationRuleBase'
unstableReadableEvaluationRule:
title: unstableReadableEvaluationRule
oneOf:
- $ref: '#/components/schemas/unstableEvaluationRule'
- $ref: '#/components/schemas/unstableLegacyEvaluationRule'
description: >-
Evaluation rule returned by list and get, including read-only legacy
trace and dataset rules.
unstableEvaluationRules:
title: unstableEvaluationRules
type: object
description: Paginated list of evaluation rules.
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableReadableEvaluationRule'
description: Evaluation rules in the current page.
meta:
$ref: '#/components/schemas/utilsMetaResponse'
description: Standard pagination metadata.
required:
- data
- meta
unstableCreateEvaluationRuleRequest:
title: unstableCreateEvaluationRuleRequest
oneOf:
- $ref: '#/components/schemas/unstableCreateLlmAsJudgeEvaluationRuleRequest'
- $ref: '#/components/schemas/unstableCreateCodeEvaluationRuleRequest'
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`
- for `llm_as_judge`, fetch or inspect the evaluator first and provide a
complete variable mapping for every evaluator variable
- for `code`, do not send variables or mappings; Langfuse stores the
fixed code runtime mapping automatically
- optionally narrow execution with `filter`
- set `enabled=true` only when you want live execution immediately
unstableCreateLlmAsJudgeEvaluationRuleRequest:
title: unstableCreateLlmAsJudgeEvaluationRuleRequest
type: object
properties:
name:
type: string
description: Human-readable deployment name.
evaluator:
$ref: >-
#/components/schemas/unstableLlmAsJudgeEvaluationRuleEvaluatorReference
description: >-
LLM-as-judge evaluator family to use.
Use `name`, `scope`, and `type` from the evaluator endpoints. If
`type` is omitted, Langfuse defaults it to `llm_as_judge` for
backwards compatibility.
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.
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: >-
LLM-as-judge 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
unstableCreateCodeEvaluationRuleRequest:
title: unstableCreateCodeEvaluationRuleRequest
type: object
properties:
name:
type: string
description: Human-readable deployment name.
evaluator:
$ref: '#/components/schemas/unstableCodeEvaluationRuleEvaluatorReference'
description: >-
Code evaluator family to use.
Use `name`, `scope`, and `type` 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.
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.
required:
- name
- evaluator
- target
- enabled
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 to an LLM-as-judge `evaluator`, send a fresh `mapping`
unless you are certain the existing mapping still matches the evaluator
variables.
- If you change `target` for an LLM-as-judge rule, usually send both
`filter` and `mapping` in the same request.
- For code evaluator rules, omit `mapping`; Langfuse stores the fixed
code runtime mapping automatically.
- 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.
A rule's evaluator type cannot be changed: provide `name` and
`scope` for an evaluator family of the rule's current type. To use a
different evaluator type, create a new 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 LLM-as-judge variable mappings.
Do not send this field for code evaluator rules. Langfuse stores the
fixed code runtime mapping automatically and returns it in the
response.
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 updating an evaluation rule.
`name` and `scope` identify the evaluator family in the authenticated
project context.
A rule's evaluator type cannot be changed, so this reference does not
accept a `type`; the family must match the rule's current evaluator
type.
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
unstableLlmAsJudgeEvaluationRuleEvaluatorReference:
title: unstableLlmAsJudgeEvaluationRuleEvaluatorReference
type: object
description: >-
LLM-as-judge evaluator family reference used when creating an evaluation
rule.
properties:
name:
type: string
description: Evaluator family name.
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: Whether the evaluator family is project-owned or Langfuse-managed.
type:
$ref: '#/components/schemas/unstableLlmAsJudgeEvaluatorType'
nullable: true
description: Evaluator engine type. Defaults to `llm_as_judge` when omitted.
required:
- name
- scope
unstableCodeEvaluationRuleEvaluatorReference:
title: unstableCodeEvaluationRuleEvaluatorReference
type: object
description: Code evaluator family reference used when creating an evaluation rule.
properties:
name:
type: string
description: Evaluator family name.
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: Whether the evaluator family is project-owned or Langfuse-managed.
type:
type: string
description: Must be `code`.
required:
- name
- scope
- type
unstableLlmAsJudgeEvaluatorType:
title: unstableLlmAsJudgeEvaluatorType
type: string
enum:
- llm_as_judge
unstableEvaluationRuleTimeScope:
title: unstableEvaluationRuleTimeScope
type: string
enum:
- NEW
- EXISTING
unstableLegacyEvaluationRuleTarget:
title: unstableLegacyEvaluationRuleTarget
type: string
enum:
- trace
- dataset
unstableLegacyEvaluationRuleMapping:
title: unstableLegacyEvaluationRuleMapping
type: object
description: >-
Maps one evaluator variable to a trace, dataset item, or field on a
named observation in a legacy rule.
properties:
variable:
type: string
description: Evaluator prompt variable populated by this mapping.
langfuseObject:
$ref: '#/components/schemas/unstableLegacyEvaluationObject'
description: >-
Trace, dataset item, or observation type from which the value is
read.
objectName:
type: string
nullable: true
description: >-
Observation name to match, or `null` when `langfuseObject` is
`trace` or `dataset_item`.
source:
type: string
description: Stored field selected from the trace, dataset item, or observation.
jsonPath:
type: string
nullable: true
description: Optional JSONPath selector applied to the selected field.
required:
- variable
- langfuseObject
- objectName
- source
unstableLegacyEvaluationObject:
title: unstableLegacyEvaluationObject
type: string
enum:
- trace
- span
- generation
- event
- agent
- tool
- chain
- retriever
- evaluator
- embedding
- guardrail
- dataset_item
unstableEvaluationRuleEvaluator:
title: unstableEvaluationRuleEvaluator
type: object
description: |-
Resolved evaluator currently used by the evaluation rule.
`id` is the exact active evaluator version.
`name`, `scope`, and `type` 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.
type:
$ref: '#/components/schemas/unstableEvaluatorType'
description: Evaluator engine type.
required:
- id
- name
- scope
- type
unstableDeleteEvaluatorResponse:
title: unstableDeleteEvaluatorResponse
type: object
description: Confirmation response returned after successful deletion.
properties:
message:
type: string
description: Always `Evaluator successfully deleted`.
required:
- message
unstableEvaluator:
title: unstableEvaluator
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- llm_as_judge
- $ref: '#/components/schemas/unstableLlmAsJudgeEvaluator'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- code
- $ref: '#/components/schemas/unstableCodeEvaluator'
required:
- type
description: >-
One evaluator that can be used for scoring.
An evaluator describes **how** to score data.
It does not define **which** live objects are evaluated. That is the job
of `evaluation-rules`.
For agent clients, the most important fields are:
- `type`: determines which evaluator fields are present
- `variables`: for LLM evaluators, use these exact names when building
the evaluation-rule `mapping` array. LLM evaluators require every
variable to be mapped. Code evaluators always expose the fixed runtime
payload fields and Langfuse maps them automatically.
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`).
unstableEvaluatorBase:
title: unstableEvaluatorBase
type: object
properties:
id:
type: string
description: Identifier of this evaluator.
name:
type: string
description: Evaluator name.
version:
type: integer
description: Version number of this evaluator.
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: >-
Where this evaluator comes from: your project or Langfuse-managed
defaults.
variables:
type: array
items:
type: string
description: >-
Variables that can be mapped when creating an evaluation rule.
LLM evaluators require every variable to be mapped exactly once.
Code evaluators always expose the fixed runtime payload fields and
Langfuse maps them automatically.
evaluationRuleCount:
type: integer
description: >-
Number of evaluation rules in the project that currently use this
evaluator version.
createdAt:
type: string
format: date-time
description: Timestamp when this evaluator was created.
updatedAt:
type: string
format: date-time
description: Timestamp when this evaluator was last updated.
required:
- id
- name
- version
- scope
- variables
- evaluationRuleCount
- createdAt
- updatedAt
unstableLlmAsJudgeEvaluator:
title: unstableLlmAsJudgeEvaluator
type: object
properties:
prompt:
type: string
description: Prompt template used during evaluation.
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.
required:
- prompt
- outputDefinition
- modelConfig
allOf:
- $ref: '#/components/schemas/unstableEvaluatorBase'
unstableCodeEvaluator:
title: unstableCodeEvaluator
type: object
properties:
sourceCode:
type: string
description: Source code executed for each matched observation.
sourceCodeLanguage:
$ref: '#/components/schemas/unstableCodeEvaluatorSourceCodeLanguage'
description: Runtime language for `sourceCode`.
required:
- sourceCode
- sourceCodeLanguage
allOf:
- $ref: '#/components/schemas/unstableEvaluatorBase'
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
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- llm_as_judge
- $ref: '#/components/schemas/unstableCreateLlmAsJudgeEvaluatorRequest'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- code
- $ref: '#/components/schemas/unstableCreateCodeEvaluatorRequest'
required:
- type
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.
If `type` is omitted, Langfuse defaults it to `llm_as_judge` for
backwards compatibility.
unstableCreateLlmAsJudgeEvaluatorRequest:
title: unstableCreateLlmAsJudgeEvaluatorRequest
type: object
properties:
name:
type: string
description: Evaluator name within the authenticated project.
prompt:
type: string
description: Prompt template used by the evaluator.
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
unstableCreateCodeEvaluatorRequest:
title: unstableCreateCodeEvaluatorRequest
type: object
properties:
name:
type: string
description: Evaluator name within the authenticated project.
sourceCode:
type: string
description: Code executed for each matched observation.
sourceCodeLanguage:
$ref: '#/components/schemas/unstableCodeEvaluatorSourceCodeLanguage'
description: Runtime language for `sourceCode`.
required:
- name
- sourceCode
- sourceCodeLanguage
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