openapi: 3.0.1
info:
title: langfuse
version: ''
description: >-
## Authentication
Authenticate with the API using [Basic
Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API
keys in the project settings:
- username: Langfuse Public Key
- password: Langfuse Secret Key
## Exports
- OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
paths:
/api/public/annotation-queues:
get:
description: Get all annotation queues
operationId: annotationQueues_listQueues
tags:
- AnnotationQueues
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueues'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create an annotation queue
operationId: annotationQueues_createQueue
tags:
- AnnotationQueues
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueRequest'
/api/public/annotation-queues/{queueId}:
get:
description: Get an annotation queue by ID
operationId: annotationQueues_getQueue
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/annotation-queues/{queueId}/items:
get:
description: Get items for a specific annotation queue
operationId: annotationQueues_listQueueItems
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: status
in: query
description: Filter by status
required: false
schema:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueueItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Add an item to an annotation queue
operationId: annotationQueues_createQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueItemRequest'
/api/public/annotation-queues/{queueId}/items/{itemId}:
get:
description: Get a specific item from an annotation queue
operationId: annotationQueues_getQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Update an annotation queue item
operationId: annotationQueues_updateQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAnnotationQueueItemRequest'
delete:
description: Remove an item from an annotation queue
operationId: annotationQueues_deleteQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/annotation-queues/{queueId}/assignments:
post:
description: Create an assignment for a user to an annotation queue
operationId: annotationQueues_createQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
delete:
description: Delete an assignment for a user to an annotation queue
operationId: annotationQueues_deleteQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
/api/public/integrations/blob-storage:
get:
description: >-
Get all blob storage integrations for the organization (requires
organization-scoped API key)
operationId: blobStorageIntegrations_getBlobStorageIntegrations
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a blob storage integration for a specific project
(requires organization-scoped API key). The configuration is validated
by performing a test upload to the bucket.
operationId: blobStorageIntegrations_upsertBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBlobStorageIntegrationRequest'
/api/public/integrations/blob-storage/{id}:
get:
description: >-
Get the sync status of a blob storage integration by integration ID
(requires organization-scoped API key)
operationId: blobStorageIntegrations_getBlobStorageIntegrationStatus
tags:
- BlobStorageIntegrations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationStatusResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete a blob storage integration by ID (requires organization-scoped
API key)
operationId: blobStorageIntegrations_deleteBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/comments:
post:
description: >-
Create a comment. Comments may be attached to different object types
(trace, observation, session, prompt).
operationId: comments_create
tags:
- Comments
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
get:
description: Get all comments
operationId: comments_get
tags:
- Comments
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
- name: objectType
in: query
description: >-
Filter comments by object type (trace, observation, session,
prompt).
required: false
schema:
type: string
nullable: true
- name: objectId
in: query
description: >-
Filter comments by object id. If objectType is not provided, an
error will be thrown.
required: false
schema:
type: string
nullable: true
- name: authorUserId
in: query
description: Filter comments by author user id.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetCommentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/comments/{commentId}:
get:
description: Get a comment by id
operationId: comments_get-by-id
tags:
- Comments
parameters:
- name: commentId
in: path
description: The unique langfuse identifier of a comment
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-items:
post:
description: Create a dataset item
operationId: datasetItems_create
tags:
- DatasetItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetItemRequest'
get:
description: >-
Get dataset items. Optionally specify a version to get the items as they
existed at that point in time.
Note: If version parameter is provided, datasetName must also be
provided.
operationId: datasetItems_list
tags:
- DatasetItems
parameters:
- name: datasetName
in: query
required: false
schema:
type: string
nullable: true
- name: sourceTraceId
in: query
required: false
schema:
type: string
nullable: true
- name: sourceObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: version
in: query
description: >-
ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
"2026-01-21T14:35:42Z").
If provided, returns state of dataset at this timestamp.
If not provided, returns the latest version. Requires datasetName to
be specified.
required: false
schema:
type: string
format: date-time
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-items/{id}:
get:
description: Get a dataset item
operationId: datasetItems_get
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete a dataset item and all its run items. This action is
irreversible.
operationId: datasetItems_delete
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-run-items:
post:
description: Create a dataset run item
operationId: datasetRunItems_create
tags:
- DatasetRunItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRunItemRequest'
get:
description: List dataset run items
operationId: datasetRunItems_list
tags:
- DatasetRunItems
parameters:
- name: datasetId
in: query
required: true
schema:
type: string
- name: runName
in: query
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRunItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/datasets:
get:
description: Get all datasets
operationId: datasets_list
tags:
- Datasets
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasets'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a dataset
operationId: datasets_create
tags:
- Datasets
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRequest'
/api/public/v2/datasets/{datasetName}:
get:
description: Get a dataset
operationId: datasets_get
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/datasets/{datasetName}/runs/{runName}:
get:
description: Get a dataset run and its items
operationId: datasets_getRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunWithItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete a dataset run and all its run items. This action is irreversible.
operationId: datasets_deleteRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetRunResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/datasets/{datasetName}/runs:
get:
description: Get dataset runs
operationId: datasets_getRuns
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRuns'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/health:
get:
description: Check health of API and database
operationId: health_health
tags:
- Health
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'503':
description: ''
/api/public/ingestion:
post:
description: >-
**Legacy endpoint for batch ingestion for Langfuse Observability.**
-> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`).
Learn more: https://langfuse.com/integrations/native/opentelemetry
Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Internally, we refer to this as the "event envelope" as it tells us
something about the event but not the trace.
We use the event id within this envelope to deduplicate messages to
avoid processing the same event twice, i.e. the event id should be
unique per request.
The event.body.id is the ID of the actual trace and will be used for
updates and will be visible within the Langfuse App.
I.e. if you want to update a trace, you'd use the same body id, but
separate event IDs.
Notes:
- Introduction to data model:
https://langfuse.com/docs/observability/data-model
- Batch sizes are limited to 3.5 MB in total. You need to adjust the
number of events per batch accordingly.
- The API does not return a 4xx status code for input errors. Instead,
it responds with a 207 status code, which includes a list of the
encountered errors.
operationId: ingestion_batch
tags:
- Ingestion
parameters: []
responses:
'207':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionResponse'
examples:
Example1:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
Example2:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
Example3:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
batch:
type: array
items:
$ref: '#/components/schemas/IngestionEvent'
description: >-
Batch of tracing events to be ingested. Discriminated by
attribute `type`.
metadata:
nullable: true
description: >-
Optional. Metadata field used by the Langfuse SDKs for
debugging.
required:
- batch
examples:
Example1:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: trace-create
body:
id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
environment: production
name: My Trace
userId: 1234-5678-90ab-cdef
input: My input
output: My output
sessionId: 1234-5678-90ab-cdef
release: 1.0.0
version: 1.0.0
metadata: My metadata
tags:
- tag1
- tag2
public: true
Example2:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: span-create
body:
id: abcdef-1234-5678-90ab
traceId: 1234-5678-90ab-cdef
startTime: '2022-01-01T00:00:00.000Z'
environment: test
Example3:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: score-create
body:
id: abcdef-1234-5678-90ab
traceId: 1234-5678-90ab-cdef
name: My Score
value: 0.9
environment: default
/api/public/metrics:
get:
description: >-
Get metrics from the Langfuse project using a query object.
Consider using the [v2 metrics
endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for
better performance.
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
operationId: legacy_metricsV1_metrics
tags:
- LegacyMetricsV1
parameters:
- name: query
in: query
description: >-
JSON string containing the query parameters with the following
structure:
```json
{
"view": string, // Required. One of "traces", "observations", "scores-numeric", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by, e.g. "name", "userId", "sessionId"
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure, e.g. "count", "latency", "value"
"aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on
"operator": string, // Operator, e.g. "=", ">", "<", "contains"
"value": any, // Value to compare against
"type": string, // Data type, e.g. "string", "number", "stringObject"
"key": string // Required only when filtering on metadata
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "minute", "hour", "day", "week", "month", "auto"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram (1-100), default: 10
"row_limit": number // Optional. Row limit for results (1-1000)
}
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/legacyMetricsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/observations/{observationId}:
get:
description: Get a observation
operationId: legacy_observationsV1_get
tags:
- LegacyObservationsV1
parameters:
- name: observationId
in: path
description: >-
The unique langfuse identifier of an observation, can be an event,
span or generation
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsView'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/observations:
get:
description: >-
Get a list of observations.
Consider using the [v2 observations
endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations)
for cursor-based pagination and field selection.
operationId: legacy_observationsV1_getMany
tags:
- LegacyObservationsV1
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: type
in: query
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
required: false
schema:
type: string
nullable: true
- name: level
in: query
description: >-
Optional filter for observations with a specific level (e.g.
"DEBUG", "DEFAULT", "WARNING", "ERROR").
required: false
schema:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
- name: parentObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for observations where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fromStartTime
in: query
description: >-
Retrieve only observations with a start_time on or after this
datetime (ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: toStartTime
in: query
description: >-
Retrieve only observations with a start_time before this datetime
(ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: version
in: query
description: Optional filter to only include observations with a certain version.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
type, level, environment, fromStartTime, ...).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Associated Trace Fields (requires join with traces table)
- `userId` (string) - User ID from associated trace
- `traceName` (string) - Name from associated trace
- `traceEnvironment` (string) - Environment from associated trace
- `traceTags` (arrayOptions) - Tags from associated trace
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/legacyObservationsViews'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scores:
post:
description: Create a score (supports both trace and session scores)
operationId: legacy_scoreV1_create
tags:
- LegacyScoreV1
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/legacyCreateScoreResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/legacyCreateScoreRequest'
/api/public/scores/{scoreId}:
delete:
description: Delete a score (supports both trace and session scores)
operationId: legacy_scoreV1_delete
tags:
- LegacyScoreV1
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/llm-connections:
get:
description: Get all LLM connections in a project
operationId: llmConnections_list
tags:
- LlmConnections
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedLlmConnections'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update an LLM connection. The connection is upserted on
provider.
operationId: llmConnections_upsert
tags:
- LlmConnections
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/LlmConnection'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertLlmConnectionRequest'
/api/public/llm-connections/{id}:
delete:
description: >-
Delete an LLM connection by id. Evaluators that depend on the deleted
connection are automatically paused.
operationId: llmConnections_delete
tags:
- LlmConnections
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteLlmConnectionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/media/{mediaId}:
get:
description: Get a media record
operationId: media_get
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Patch a media record
operationId: media_patch
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchMediaBody'
/api/public/media:
post:
description: Get a presigned upload URL for a media record
operationId: media_getUploadUrl
tags:
- Media
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlRequest'
/api/public/v2/metrics:
get:
description: >-
Get metrics from the Langfuse project using a query object. V2 endpoint
with optimized performance.
## V2 Differences
- Supports `observations`, `scores-numeric`, and `scores-categorical`
views only (traces view not supported)
- Direct access to tags and release fields on observations
- Backwards-compatible: traceName, traceRelease, traceVersion dimensions
are still available on observations view
- High cardinality dimensions are not supported and will return a 400
error (see below)
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
## Available Views
### observations
Query observation-level data (spans, generations, events).
**Dimensions:**
- `environment` - Deployment environment (e.g., production, staging)
- `type` - Type of observation (SPAN, GENERATION, EVENT)
- `name` - Name of the observation
- `level` - Logging level of the observation
- `version` - Version of the observation
- `tags` - User-defined tags
- `release` - Release version
- `traceName` - Name of the parent trace (backwards-compatible)
- `traceRelease` - Release version of the parent trace
(backwards-compatible, maps to release)
- `traceVersion` - Version of the parent trace (backwards-compatible,
maps to version)
- `providedModelName` - Name of the model used
- `promptName` - Name of the prompt used
- `promptVersion` - Version of the prompt used
- `startTimeMonth` - Month of start_time in YYYY-MM format
**Measures:**
- `count` - Total number of observations
- `latency` - Observation latency (milliseconds)
- `streamingLatency` - Generation latency from completion start to end
(milliseconds)
- `inputTokens` - Sum of input tokens consumed
- `outputTokens` - Sum of output tokens produced
- `totalTokens` - Sum of all tokens consumed
- `outputTokensPerSecond` - Output tokens per second
- `tokensPerSecond` - Total tokens per second
- `inputCost` - Input cost (USD)
- `outputCost` - Output cost (USD)
- `totalCost` - Total cost (USD)
- `timeToFirstToken` - Time to first token (milliseconds)
- `countScores` - Number of scores attached to the observation
### scores-numeric
Query numeric and boolean score data.
**Dimensions:**
- `environment` - Deployment environment
- `name` - Name of the score (e.g., accuracy, toxicity)
- `source` - Origin of the score (API, ANNOTATION, EVAL)
- `dataType` - Data type (NUMERIC, BOOLEAN)
- `configId` - Identifier of the score config
- `timestampMonth` - Month in YYYY-MM format
- `timestampDay` - Day in YYYY-MM-DD format
- `value` - Numeric value of the score
- `traceName` - Name of the parent trace
- `tags` - Tags
- `traceRelease` - Release version
- `traceVersion` - Version
- `observationName` - Name of the associated observation
- `observationModelName` - Model name of the associated observation
- `observationPromptName` - Prompt name of the associated observation
- `observationPromptVersion` - Prompt version of the associated
observation
**Measures:**
- `count` - Total number of scores
- `value` - Score value (for aggregations)
### scores-categorical
Query categorical score data. Same dimensions as scores-numeric except
uses `stringValue` instead of `value`.
**Measures:**
- `count` - Total number of scores
## High Cardinality Dimensions
The following dimensions cannot be used as grouping dimensions in v2
metrics API as they can cause performance issues.
Use them in filters instead.
**observations view:**
- `id` - Use traceId filter to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `parentObservationId` - Use parentObservationId filter instead
**scores-numeric / scores-categorical views:**
- `id` - Use specific filters to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `observationId` - Use observationId filter instead
## Aggregations
Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,
`p50`, `p75`, `p90`, `p95`, `p99`, `histogram`
## Time Granularities
Available granularities for timeDimension: `auto`, `minute`, `hour`,
`day`, `week`, `month`
- `auto` bins the data into approximately 50 buckets based on the time
range
operationId: metrics_metrics
tags:
- Metrics
parameters:
- name: query
in: query
description: >-
JSON string containing the query parameters with the following
structure:
```json
{
"view": string, // Required. One of "observations", "scores-numeric", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by (see available dimensions above)
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure (see available measures above)
"aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on (any dimension field)
"operator": string, // Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject/numberObject: same as string/number with required "key"
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Value to compare against
"type": string, // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"key": string // Required only for stringObject/numberObject types (e.g., metadata filtering)
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "auto", "minute", "hour", "day", "week", "month"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range (must be after fromTimestamp)
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by (dimension or metric alias)
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram aggregation (1-100), default: 10
"row_limit": number // Optional. Maximum number of rows to return (1-1000), default: 100
}
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/models:
post:
description: Create a model
operationId: models_create
tags:
- Models
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
get:
description: Get all models
operationId: models_list
tags:
- Models
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedModels'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/models/{id}:
get:
description: Get a model
operationId: models_get
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete a model. Cannot delete models managed by Langfuse. You can create
your own definition with the same modelName to override the definition
though.
operationId: models_delete
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/observations:
get:
description: >-
Get a list of observations with cursor-based pagination and flexible
field selection.
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of
large datasets.
The cursor is returned in the response metadata and should be passed in
subsequent requests
to retrieve the next page of results.
## Field Selection
Use the `fields` parameter to control which observation fields are
returned:
- `core` - Always included: id, traceId, startTime, endTime, projectId,
parentObservationId, type
- `basic` - name, level, statusMessage, version, environment,
bookmarked, public, userId, sessionId
- `time` - completionStartTime, createdAt, updatedAt
- `io` - input, output
- `metadata` - metadata (truncated to 200 chars by default, use
`expandMetadata` to get full values)
- `model` - providedModelName, internalModelId, modelParameters
- `usage` - usageDetails, costDetails, totalCost, 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: type
in: query
description: >-
Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
"AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
"GUARDRAIL")
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
required: false
schema:
type: string
nullable: true
- name: level
in: query
description: >-
Optional filter for observations with a specific level (e.g.
"DEBUG", "DEFAULT", "WARNING", "ERROR").
required: false
schema:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
- name: parentObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for observations where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fromStartTime
in: query
description: >-
Retrieve only observations with a start_time on or after this
datetime (ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: toStartTime
in: query
description: >-
Retrieve only observations with a start_time before this datetime
(ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: version
in: query
description: Optional filter to only include observations with a certain version.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
type, level, environment, fromStartTime, ...).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
### Trace-Related Fields
- `traceName` (string) - Name of the parent trace
- `traceTags` (arrayOptions) - Tags from the parent trace
- `tags` (arrayOptions) - Alias for traceTags
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name (alias:
`providedModelName`)
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/otel/v1/traces:
post:
description: >-
**OpenTelemetry Traces Ingestion Endpoint**
This endpoint implements the OTLP/HTTP specification for trace
ingestion, providing native OpenTelemetry integration for Langfuse
Observability.
**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`
- JSON Protobuf: `Content-Type: application/json`
- Supports gzip compression via `Content-Encoding: gzip` header
**Specification Compliance:**
- Conforms to [OTLP/HTTP Trace
Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
- Implements `ExportTraceServiceRequest` message format
**Documentation:**
- Integration guide:
https://langfuse.com/integrations/native/opentelemetry
- Data model: https://langfuse.com/docs/observability/data-model
operationId: opentelemetry_exportTraces
tags:
- Opentelemetry
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OtelTraceResponse'
examples:
BasicTraceExport:
value: {}
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
resourceSpans:
type: array
items:
$ref: '#/components/schemas/OtelResourceSpan'
description: >-
Array of resource spans containing trace data as defined in
the OTLP specification
required:
- resourceSpans
examples:
BasicTraceExport:
value:
resourceSpans:
- resource:
attributes:
- key: service.name
value:
stringValue: my-service
- key: service.version
value:
stringValue: 1.0.0
scopeSpans:
- scope:
name: langfuse-sdk
version: 2.60.3
spans:
- traceId: 0123456789abcdef0123456789abcdef
spanId: 0123456789abcdef
name: my-operation
kind: 1
startTimeUnixNano: '1747872000000000000'
endTimeUnixNano: '1747872001000000000'
attributes:
- key: langfuse.observation.type
value:
stringValue: generation
status: {}
/api/public/organizations/memberships:
get:
description: >-
Get all memberships for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationMemberships
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a membership for the organization associated with the
API key (requires organization-scoped API key)
operationId: organizations_updateOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_deleteOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/projects/{projectId}/memberships:
get:
description: >-
Get all memberships for a specific project (requires organization-scoped
API key)
operationId: organizations_getProjectMemberships
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a membership for a specific project (requires
organization-scoped API key). The user must already be a member of the
organization.
operationId: organizations_updateProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from a specific project (requires
organization-scoped API key). The user must be a member of the
organization.
operationId: organizations_deleteProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/organizations/projects:
get:
description: >-
Get all projects for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationProjects
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationProjectsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/organizations/apiKeys:
get:
description: >-
Get all API keys for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationApiKeys
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationApiKeysResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/projects:
get:
description: >-
Get Project associated with API key (requires project-scoped API key).
You can use GET /api/public/organizations/projects to get all projects
with an organization-scoped key.
operationId: projects_get
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Projects'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a new project (requires organization-scoped API key)
operationId: projects_create
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
description: >-
Number of days to retain data. Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional.
required:
- name
- retention
/api/public/projects/{projectId}:
put:
description: Update a project by ID (requires organization-scoped API key).
operationId: projects_update
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
nullable: true
description: |-
Number of days to retain data.
Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional. Will retain existing retention setting if omitted.
required:
- name
delete:
description: >-
Delete a project by ID (requires organization-scoped API key). Project
deletion is processed asynchronously.
operationId: projects_delete
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'202':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/projects/{projectId}/apiKeys:
get:
description: Get all API keys for a project (requires organization-scoped API key)
operationId: projects_getApiKeys
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyList'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: >-
Create a new API key for a project (requires organization-scoped API
key)
operationId: projects_createApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
nullable: true
description: Optional note for the API key
publicKey:
type: string
nullable: true
description: >-
Optional predefined public key. Must start with 'pk-lf-'. If
provided, secretKey must also be provided.
secretKey:
type: string
nullable: true
description: >-
Optional predefined secret key. Must start with 'sk-lf-'. If
provided, publicKey must also be provided.
/api/public/projects/{projectId}/apiKeys/{apiKeyId}:
delete:
description: Delete an API key for a project (requires organization-scoped API key)
operationId: projects_deleteApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
- name: apiKeyId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/prompts/{name}/versions/{version}:
patch:
description: Update labels for a specific prompt version
operationId: promptVersion_update
tags:
- PromptVersion
parameters:
- name: name
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: path
description: Version of the prompt to update
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
newLabels:
type: array
items:
type: string
description: >-
New labels for the prompt version. Labels are unique across
versions. The "latest" label is reserved and managed by
Langfuse.
required:
- newLabels
/api/public/v2/prompts/{promptName}:
get:
description: Get a prompt
operationId: prompts_get
tags:
- Prompts
parameters:
- name: promptName
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: query
description: Version of the prompt to be retrieved.
required: false
schema:
type: integer
nullable: true
- name: label
in: query
description: >-
Label of the prompt to be retrieved. Defaults to "production" if no
label or version is set.
required: false
schema:
type: string
nullable: true
- name: resolve
in: query
description: >-
Resolve prompt dependencies before returning the prompt. Defaults to
`true`. Set to `false` to return the raw stored prompt with
dependency tags intact. This bypasses prompt caching and is intended
for debugging or one-off jobs, not production runtime fetches.
required: false
schema:
type: boolean
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete prompt versions. If neither version nor label is specified, all
versions of the prompt are deleted.
operationId: prompts_delete
tags:
- Prompts
parameters:
- name: promptName
in: path
description: The name of the prompt
required: true
schema:
type: string
- name: label
in: query
description: >-
Optional label to filter deletion. If specified, deletes all prompt
versions that have this label.
required: false
schema:
type: string
nullable: true
- name: version
in: query
description: >-
Optional version to filter deletion. If specified, deletes only this
specific version of the prompt.
required: false
schema:
type: integer
nullable: true
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/prompts:
get:
description: Get a list of prompt names with versions and labels
operationId: prompts_list
tags:
- Prompts
parameters:
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: label
in: query
required: false
schema:
type: string
nullable: true
- name: tag
in: query
required: false
schema:
type: string
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
- name: fromUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated on
or after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated
before a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PromptMetaListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a new version for the prompt with the given `name`
operationId: prompts_create
tags:
- Prompts
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePromptRequest'
/api/public/scim/ServiceProviderConfig:
get:
description: >-
Get SCIM Service Provider Configuration (requires organization-scoped
API key)
operationId: scim_getServiceProviderConfig
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceProviderConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/ResourceTypes:
get:
description: Get SCIM Resource Types (requires organization-scoped API key)
operationId: scim_getResourceTypes
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceTypesResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/Schemas:
get:
description: Get SCIM Schemas (requires organization-scoped API key)
operationId: scim_getSchemas
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SchemasResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/Users:
get:
description: List users in the organization (requires organization-scoped API key)
operationId: scim_listUsers
tags:
- Scim
parameters:
- name: filter
in: query
description: Filter expression (e.g. userName eq "value")
required: false
schema:
type: string
nullable: true
- name: startIndex
in: query
description: 1-based index of the first result to return (default 1)
required: false
schema:
type: integer
nullable: true
- name: count
in: query
description: Maximum number of results to return (default 100)
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUsersListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: >-
Create a new user in the organization (requires organization-scoped API
key)
operationId: scim_createUser
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userName:
type: string
description: User's email address (required)
name:
$ref: '#/components/schemas/ScimName'
description: User's name information
emails:
type: array
items:
$ref: '#/components/schemas/ScimEmail'
nullable: true
description: User's email addresses
active:
type: boolean
nullable: true
description: Whether the user is active
password:
type: string
nullable: true
description: Initial password for the user
required:
- userName
- name
/api/public/scim/Users/{userId}:
get:
description: Get a specific user by ID (requires organization-scoped API key)
operationId: scim_getUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Remove a user from the organization (requires organization-scoped API
key). Note that this only removes the user from the organization but
does not delete the user entity itself.
operationId: scim_deleteUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/score-configs:
post:
description: >-
Create a score configuration (config). Score configs are used to define
the structure of scores
operationId: scoreConfigs_create
tags:
- ScoreConfigs
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreConfigRequest'
get:
description: Get all score configs
operationId: scoreConfigs_get
tags:
- ScoreConfigs
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfigs'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/score-configs/{configId}:
get:
description: Get a score config
operationId: scoreConfigs_get-by-id
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Update a score config
operationId: scoreConfigs_update
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScoreConfigRequest'
/api/public/v2/scores:
get:
description: Get a list of scores (supports both trace and session scores)
operationId: scores_get-many
tags:
- Scores
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. 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:
- BasicAuth: []
/api/public/v2/scores/{scoreId}:
get:
description: Get a score (supports both trace and session scores)
operationId: scores_get-by-id
tags:
- Scores
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Score'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/sessions:
get:
description: Get sessions
operationId: sessions_list
tags:
- Sessions
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include sessions created on or after a
certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include sessions created before a certain
datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: environment
in: query
description: >-
Optional filter for sessions where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSessions'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/sessions/{sessionId}:
get:
description: >-
Get a session. Please note that `traces` on this endpoint are not
paginated, if you plan to fetch large sessions, consider `GET
/api/public/traces?sessionId=<sessionId>`
operationId: sessions_get
tags:
- Sessions
parameters:
- name: sessionId
in: path
description: The unique id of a session
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SessionWithTraces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/traces/{traceId}:
get:
description: Get a specific trace
operationId: trace_get
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of a trace
required: true
schema:
type: string
- name: fields
in: query
description: >-
Comma-separated list of fields to include in the response. Available
field groups: 'core' (always included), 'io' (input, output,
metadata), 'scores', 'observations', 'metrics'. If not specified,
all fields are returned. Example: 'core,scores,metrics'. Note:
Excluded 'observations' or 'scores' fields return empty arrays;
excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWithFullDetails'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete a specific trace
operationId: trace_delete
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of the trace to delete
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/traces:
get:
description: Get list of traces
operationId: trace_list
tags:
- Trace
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp on or
after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp before
a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: orderBy
in: query
description: >-
Format of the string [field].[asc/desc]. Fields: id, timestamp,
name, userId, release, version, public, bookmarked, sessionId.
Example: timestamp.asc
required: false
schema:
type: string
nullable: true
- name: tags
in: query
description: Only traces that include all of these tags will be returned.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: version
in: query
description: Optional filter to only include traces with a certain version.
required: false
schema:
type: string
nullable: true
- name: release
in: query
description: Optional filter to only include traces with a certain release.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for traces where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated list of fields to include in the response. Available
field groups: 'core' (always included), 'io' (input, output,
metadata), 'scores', 'observations', 'metrics'. If not specified,
all fields are returned. Example: 'core,scores,metrics'. Note:
Excluded 'observations' or 'scores' fields return empty arrays;
excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
sessionId, tags, version, release, environment, fromTimestamp,
toTimestamp).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Trace Fields
- `id` (string) - Trace ID
- `name` (string) - Trace name
- `timestamp` (datetime) - Trace timestamp
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
- `environment` (string) - Environment tag
- `version` (string) - Version tag
- `release` (string) - Release tag
- `tags` (arrayOptions) - Array of tags
- `bookmarked` (boolean) - Bookmark status
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Aggregated Metrics (from observations)
These metrics are aggregated from all observations within the trace:
- `latency` (number) - Latency in seconds (time from first
observation start to last observation end)
- `inputTokens` (number) - Total input tokens across all
observations
- `outputTokens` (number) - Total output tokens across all
observations
- `totalTokens` (number) - Total tokens (alias: `tokens`)
- `inputCost` (number) - Total input cost in USD
- `outputCost` (number) - Total output cost in USD
- `totalCost` (number) - Total cost in USD
### Observation Level Aggregations
These fields aggregate observation levels within the trace:
- `level` (string) - Highest severity level (ERROR > WARNING >
DEFAULT > DEBUG)
- `warningCount` (number) - Count of WARNING level observations
- `errorCount` (number) - Count of ERROR level observations
- `defaultCount` (number) - Count of DEFAULT level observations
- `debugCount` (number) - Count of DEBUG level observations
### Scores (requires join with scores table)
- `scores_avg` (number) - Average of numeric scores (alias:
`scores`)
- `score_categories` (categoryOptions) - Categorical score values
## Filter Examples
```json
[
{
"type": "datetime",
"column": "timestamp",
"operator": ">=",
"value": "2024-01-01T00:00:00Z"
},
{
"type": "string",
"column": "userId",
"operator": "=",
"value": "user-123"
},
{
"type": "number",
"column": "totalCost",
"operator": ">=",
"value": 0.01
},
{
"type": "arrayOptions",
"column": "tags",
"operator": "all of",
"value": ["production", "critical"]
},
{
"type": "stringObject",
"column": "metadata",
"key": "customer_tier",
"operator": "=",
"value": "enterprise"
}
]
```
## Performance Notes
- Filtering on `userId`, `sessionId`, or `metadata` may enable skip
indexes for better query performance
- Score filters require a join with the scores table and may impact
query performance
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Traces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete multiple traces
operationId: trace_deleteMultiple
tags:
- Trace
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
traceIds:
type: array
items:
type: string
description: List of trace IDs to delete
required:
- traceIds
/api/public/unstable/evaluation-rules:
post:
description: >-
Create an evaluation rule.
An evaluation rule defines **what** incoming data should be evaluated
and **how prompt variables should be populated** from that data.
Use this resource after choosing an evaluator from the evaluator
endpoints.
Key rules:
- `name` must be unique within the project for public evaluation rules
- `target` must be `observation` or `experiment`
- `evaluator.name` + `evaluator.scope` must identify an existing
evaluator family returned by the evaluator endpoints
- Langfuse resolves that family to its latest version before saving the
evaluation rule
- for `target=experiment`, use dataset `id` values from `GET
/api/public/v2/datasets` when filtering by `datasetId`
- every evaluator prompt variable must be mapped exactly once
- `expected_output` mappings are only valid for `target=experiment`
- if `enabled=true`, Langfuse validates that the referenced evaluator
can currently run
- at most 50 evaluation rules can be effectively active in one project
at the same time
If an evaluation rule with the same `name` already exists in the
project, the API returns `409`.
In that case, update the existing resource with `PATCH
/api/public/unstable/evaluation-rules/{evaluationRuleId}` instead of
creating a second one.
If enabling this resource would exceed the 50-active limit, the API also
returns `409`.
In that case, disable or pause another active evaluation rule before
enabling a new one.
Current scope:
- evaluation rules are live-ingestion rules only
- they do not trigger historical backfills
Recovery guidance:
- `400 invalid_filter_value`: fix the filter `column` or `value` using
`details.column`, `details.invalidValues`, and `details.allowedValues`
- `400 invalid_filter_value` with `details.column=datasetId`: call `GET
/api/public/v2/datasets`, then retry with dataset `id` values from that
response
- `400 missing_variable_mapping`: fetch the evaluator again and make
sure every variable in `variables` appears exactly once in `mapping`
- `400 duplicate_variable_mapping`: remove repeated mappings for the
same variable
- `400 invalid_variable_mapping`: switch to a valid `source` for the
selected `target`, or fix the variable name
- `400 invalid_json_path`: remove or correct the `jsonPath`
- `422 evaluator_preflight_failed`: the selected evaluator cannot run
with the resolved model configuration. Fix the evaluator/default model
setup, then retry the create request.
operationId: unstable_evaluationRules_create
tags:
- UnstableEvaluationRules
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluationRule'
examples:
CreateObservationEvaluationRule:
value:
id: erule_123
name: answer-correctness-live
evaluator:
id: evaltmpl_123
name: answer-correctness
scope: project
target: observation
enabled: true
status: active
sampling: 1
filter:
- type: stringOptions
column: type
operator: any of
value:
- GENERATION
mapping:
- variable: input
source: input
- variable: output
source: output
createdAt: '2026-03-30T09:20:00.000Z'
updatedAt: '2026-03-30T09:20:00.000Z'
CreateExperimentEvaluationRule:
value:
id: erule_456
name: experiment-expected-output-match
evaluator:
id: evaltmpl_456
name: expected-output-match
scope: project
target: experiment
enabled: true
status: active
sampling: 0.5
filter:
- type: stringOptions
column: datasetId
operator: any of
value:
- 550e8400-e29b-41d4-a716-446655440000
mapping:
- variable: output
source: output
- variable: expected_output
source: expected_output
createdAt: '2026-03-30T09:30:00.000Z'
updatedAt: '2026-03-30T09:30:00.000Z'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'422':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateEvaluationRuleRequest'
examples:
CreateObservationEvaluationRule:
value:
name: answer-correctness-live
evaluator:
name: answer-correctness
scope: project
target: observation
enabled: true
sampling: 1
filter:
- type: stringOptions
column: type
operator: any of
value:
- GENERATION
mapping:
- variable: input
source: input
- variable: output
source: output
CreateExperimentEvaluationRule:
value:
name: experiment-expected-output-match
evaluator:
name: expected-output-match
scope: project
target: experiment
enabled: true
sampling: 0.5
filter:
- type: stringOptions
column: datasetId
operator: any of
value:
- 550e8400-e29b-41d4-a716-446655440000
mapping:
- variable: output
source: output
- variable: expected_output
source: expected_output
get:
description: >-
List evaluation rules in the authenticated project.
Each item describes one live evaluation rule and its effective runtime
status.
operationId: unstable_evaluationRules_list
tags:
- UnstableEvaluationRules
parameters:
- name: page
in: query
description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluationRules'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
/api/public/unstable/evaluation-rules/{evaluationRuleId}:
get:
description: >-
Get one evaluation rule by its identifier.
Use this endpoint to inspect the current evaluator, target, mapping,
filters, and effective runtime status.
operationId: unstable_evaluationRules_get
tags:
- UnstableEvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: >-
Evaluation rule identifier returned by the evaluation rule
endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
patch:
description: >-
Update an evaluation rule.
Typical uses:
- enable or disable live execution
- switch to another evaluator
- adjust sampling
- change filters
- update variable mappings
Important behavior:
- provide only the fields you want to change
- if you provide `evaluator`, Langfuse resolves that evaluator family to
its latest version before saving
- changing `target`, `filter`, or `mapping` must still produce a valid
target-specific configuration
- if you change `target`, also send a compatible `filter` and `mapping`
in the same request unless the existing ones are still valid for the new
target
- if the resulting config is enabled, Langfuse re-validates that the
selected evaluator can run
- if the update would move a non-active evaluation rule into the active
state and the project already has 50 active evaluation rules, the API
returns `409`
Recovery guidance:
- if the update fails with `missing_variable_mapping` or
`invalid_variable_mapping` after changing `evaluator` or `target`,
resend the request with a complete new `mapping`
- if the update fails with `invalid_filter_value` after changing
`target`, resend the request with a target-compatible `filter`
operationId: unstable_evaluationRules_update
tags:
- UnstableEvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: Evaluation rule identifier.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'422':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateEvaluationRuleRequest'
delete:
description: >-
Delete an evaluation rule.
This removes the live-ingestion rule only. It does not delete the
referenced evaluator.
operationId: unstable_evaluationRules_delete
tags:
- UnstableEvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: Evaluation rule identifier.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteEvaluationRuleResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
/api/public/unstable/evaluators:
post:
description: >-
Create an evaluator in the authenticated project.
Use evaluators to define **how** Langfuse should score data: the prompt,
the expected structured output, and the optional model configuration.
Naming behavior:
- If this is a new evaluator name in your project, Langfuse creates
version `1`.
- If the name already exists in your project, Langfuse creates the next
version and returns it.
- When a new project version is created, existing evaluation rules in
that project automatically move to the newest version for that evaluator
name.
Recommended workflow:
1. Create the evaluator.
2. Read the returned `variables` array.
3. Read the returned `outputDefinition.dataType` so the client knows
whether future scores will be numeric, boolean, or categorical.
4. Create one or more evaluation rules that reference the returned
evaluator family using `name` and `scope`.
Recovery guidance:
- `422` with `code=evaluator_preflight_failed`: the evaluator cannot run
with the resolved model configuration. Add a valid explicit
`modelConfig`, or configure the project's default evaluation model, then
retry the same request.
- `400` with `code=invalid_body`: the request shape is malformed. Use
the structured `details.issues` array to fix the specific fields and
retry.
- `400` with `code=invalid_body` on `outputDefinition`: send `dataType`,
`reasoning.description`, and `score.description`. Do not send `version`;
it is not part of the public request shape.
Unstable API note:
- This surface may evolve while the underlying evaluation data model is
being redesigned.
operationId: unstable_evaluators_create
tags:
- UnstableEvaluators
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluator'
examples:
CreateEvaluatorVersion:
value:
id: evaltmpl_123
name: answer-correctness
version: 2
scope: project
type: llm_as_judge
prompt: |
You are grading an answer.
Input:
{{input}}
Output:
{{output}}
Return a score between 0 and 1.
variables:
- input
- output
outputDefinition:
dataType: NUMERIC
reasoning:
description: Explain why the score was assigned.
score:
description: Correctness score between 0 and 1.
modelConfig:
provider: openai
model: gpt-4.1-mini
evaluationRuleCount: 0
createdAt: '2026-03-30T09:00:00.000Z'
updatedAt: '2026-03-30T09:00:00.000Z'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'422':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateEvaluatorRequest'
examples:
CreateEvaluatorVersion:
value:
name: answer-correctness
prompt: |
You are grading an answer.
Input:
{{input}}
Output:
{{output}}
Return a score between 0 and 1.
outputDefinition:
dataType: NUMERIC
reasoning:
description: Explain why the score was assigned.
score:
description: Correctness score between 0 and 1.
modelConfig:
provider: openai
model: gpt-4.1-mini
get:
description: >-
List the evaluators available to the authenticated project.
Important behavior:
- This endpoint returns the latest version of each available evaluator.
- Results can include evaluators from your project and Langfuse-managed
evaluators.
- If the same evaluator name exists in both places, both are returned as
separate items with different `scope` values.
operationId: unstable_evaluators_list
tags:
- UnstableEvaluators
parameters:
- name: page
in: query
description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluators'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
/api/public/unstable/evaluators/{evaluatorId}:
get:
description: >-
Get one evaluator by `id`.
Use this endpoint when you want the prompt, output definition, model
configuration, and derived variables for the evaluator you plan to use
in an evaluation rule.
operationId: unstable_evaluators_get
tags:
- UnstableEvaluators
parameters:
- name: evaluatorId
in: path
description: Evaluator identifier returned by the evaluator endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableEvaluator'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security:
- BasicAuth: []
components:
schemas:
AnnotationQueueStatus:
title: AnnotationQueueStatus
type: string
enum:
- PENDING
- COMPLETED
AnnotationQueueObjectType:
title: AnnotationQueueObjectType
type: string
enum:
- TRACE
- OBSERVATION
- SESSION
AnnotationQueue:
title: AnnotationQueue
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- scoreConfigIds
- createdAt
- updatedAt
AnnotationQueueItem:
title: AnnotationQueueItem
type: object
properties:
id:
type: string
queueId:
type: string
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
completedAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- queueId
- objectId
- objectType
- status
- createdAt
- updatedAt
PaginatedAnnotationQueues:
title: PaginatedAnnotationQueues
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueue'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PaginatedAnnotationQueueItems:
title: PaginatedAnnotationQueueItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueueItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateAnnotationQueueRequest:
title: CreateAnnotationQueueRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
required:
- name
- scoreConfigIds
CreateAnnotationQueueItemRequest:
title: CreateAnnotationQueueItemRequest
type: object
properties:
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
description: Defaults to PENDING for new queue items
required:
- objectId
- objectType
UpdateAnnotationQueueItemRequest:
title: UpdateAnnotationQueueItemRequest
type: object
properties:
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
DeleteAnnotationQueueItemResponse:
title: DeleteAnnotationQueueItemResponse
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
AnnotationQueueAssignmentRequest:
title: AnnotationQueueAssignmentRequest
type: object
properties:
userId:
type: string
required:
- userId
DeleteAnnotationQueueAssignmentResponse:
title: DeleteAnnotationQueueAssignmentResponse
type: object
properties:
success:
type: boolean
required:
- success
CreateAnnotationQueueAssignmentResponse:
title: CreateAnnotationQueueAssignmentResponse
type: object
properties:
userId:
type: string
queueId:
type: string
projectId:
type: string
required:
- userId
- queueId
- projectId
BlobStorageIntegrationType:
title: BlobStorageIntegrationType
type: string
enum:
- S3
- S3_COMPATIBLE
- AZURE_BLOB_STORAGE
BlobStorageIntegrationFileType:
title: BlobStorageIntegrationFileType
type: string
enum:
- JSON
- CSV
- JSONL
BlobStorageExportMode:
title: BlobStorageExportMode
type: string
enum:
- FULL_HISTORY
- FROM_TODAY
- FROM_CUSTOM_DATE
BlobStorageExportFrequency:
title: BlobStorageExportFrequency
type: string
enum:
- 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
with a fixed column set. The `exportFieldGroups` field is not
applicable.
- `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. For the
`OBSERVATIONS_V2` portion, columns 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 for the OBSERVATIONS_V2 and
LEGACY_TRACES_AND_ENRICHED_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)
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, the column default
(`LEGACY_TRACES_OBSERVATIONS`) applies. Required when
`exportFieldGroups` is provided.
exportFieldGroups:
type: array
items:
$ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
Field groups to include in each exported row.
For exportSource `OBSERVATIONS_V2` or
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: must include `core` if
provided. When omitted on create, the column default (all groups)
applies. When omitted on update, the existing value is preserved.
For exportSource `LEGACY_TRACES_OBSERVATIONS`: this field must be
omitted or null. Sending an array (including an empty array) returns
400, because that source uses a fixed column set and does not honor
field groups.
`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/BlobStorageIntegrationFileType'
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 row for `OBSERVATIONS_V2` /
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` sources. Always `null`
when exportSource is `LEGACY_TRACES_OBSERVATIONS` (the field does
not apply to that source; any legacy DB value is hidden from the
public surface).
nextSyncAt:
type: string
format: date-time
nullable: true
lastSyncAt:
type: string
format: date-time
nullable: true
lastError:
type: string
nullable: true
lastErrorAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- projectId
- type
- bucketName
- region
- prefix
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
- compressed
- exportSource
- createdAt
- updatedAt
BlobStorageIntegrationsResponse:
title: BlobStorageIntegrationsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
required:
- data
BlobStorageSyncStatus:
title: BlobStorageSyncStatus
type: string
enum:
- idle
- queued
- up_to_date
- disabled
- error
description: >-
Sync status of the blob storage integration:
- `disabled` — integration is not enabled
- `error` — last export failed (see `lastError` for details)
- `idle` — enabled but has never exported yet
- `queued` — next export is overdue (`nextSyncAt` is in the past) and
waiting to be picked up by the worker
- `up_to_date` — all available data has been exported; next export is
scheduled for the future
**ETL usage**: poll this endpoint and check for `up_to_date` status.
Compare `lastSyncAt` against your
ETL bookmark to determine if new data is available. Note that exports
run with a 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
BlobStorageIntegrationDeletionResponse:
title: BlobStorageIntegrationDeletionResponse
type: object
properties:
message:
type: string
required:
- message
CreateCommentRequest:
title: CreateCommentRequest
type: object
properties:
projectId:
type: string
description: The id of the project to attach the comment to.
objectType:
type: string
description: >-
The type of the object to attach the comment to (trace, observation,
session, prompt).
objectId:
type: string
description: >-
The id of the object to attach the comment to. If this does not
reference a valid existing object, an error will be thrown.
content:
type: string
description: >-
The content of the comment. May include markdown. Currently limited
to 5000 characters.
authorUserId:
type: string
nullable: true
description: The id of the user who created the comment.
required:
- projectId
- objectType
- objectId
- content
CreateCommentResponse:
title: CreateCommentResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
GetCommentsResponse:
title: GetCommentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Trace:
title: Trace
type: object
properties:
id:
type: string
description: The unique identifier of a trace
timestamp:
type: string
format: date-time
description: The timestamp when the trace was created
name:
type: string
nullable: true
description: The name of the trace
input:
nullable: true
description: The input data of the trace. Can be any JSON.
output:
nullable: true
description: The output data of the trace. Can be any JSON.
sessionId:
type: string
nullable: true
description: The session identifier associated with the trace
release:
type: string
nullable: true
description: The release version of the application when the trace was created
version:
type: string
nullable: true
description: The version of the trace
userId:
type: string
nullable: true
description: The user identifier associated with the trace
metadata:
nullable: true
description: The metadata associated with the trace. Can be any JSON.
tags:
type: array
items:
type: string
description: The tags associated with the trace.
public:
type: boolean
description: Public traces are accessible via url without login
environment:
type: string
description: >-
The environment from which this trace originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- timestamp
- tags
- public
- environment
TraceWithDetails:
title: TraceWithDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
type: string
nullable: true
description: List of observation ids
scores:
type: array
items:
type: string
nullable: true
description: List of score ids
required:
- htmlPath
allOf:
- $ref: '#/components/schemas/Trace'
TraceWithFullDetails:
title: TraceWithFullDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
description: List of observations
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV1'
description: List of scores
required:
- htmlPath
- observations
- scores
allOf:
- $ref: '#/components/schemas/Trace'
Session:
title: Session
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
projectId:
type: string
environment:
type: string
description: The environment from which this session originated.
required:
- id
- createdAt
- projectId
- environment
SessionWithTraces:
title: SessionWithTraces
type: object
properties:
traces:
type: array
items:
$ref: '#/components/schemas/Trace'
required:
- traces
allOf:
- $ref: '#/components/schemas/Session'
Observation:
title: Observation
type: object
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
type:
type: string
description: The type of the observation
name:
type: string
nullable: true
description: The name of the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation.
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
model:
type: string
nullable: true
description: The model used for the observation
modelParameters:
description: The parameters of the model used for the observation
input:
description: The input data of the observation
version:
type: string
nullable: true
description: The version of the observation
metadata:
description: Additional metadata of the observation
output:
description: The output data of the observation
usage:
$ref: '#/components/schemas/Usage'
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The usage
data of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
parentObservationId:
type: string
nullable: true
description: The parent observation ID
promptId:
type: string
nullable: true
description: The prompt ID associated with the observation
usageDetails:
type: object
additionalProperties:
type: integer
description: >-
The usage details of the observation. Key is the name of the usage
metric, value is the number of units consumed. The total key is the
sum of all (non-total) usage metrics or the total value ingested.
costDetails:
type: object
additionalProperties:
type: number
format: double
description: >-
The cost details of the observation. Key is the name of the cost
metric, value is the cost in USD. The total key is the sum of all
(non-total) cost metrics or the total value ingested.
environment:
type: string
description: >-
The environment from which this observation originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- type
- startTime
- modelParameters
- input
- metadata
- output
- usage
- level
- usageDetails
- costDetails
- environment
ObservationsView:
title: ObservationsView
type: object
properties:
promptName:
type: string
nullable: true
description: The name of the prompt associated with the observation
promptVersion:
type: integer
nullable: true
description: The version of the prompt associated with the observation
modelId:
type: string
nullable: true
description: The unique identifier of the model
inputPrice:
type: number
format: double
nullable: true
description: The price of the input in USD
outputPrice:
type: number
format: double
nullable: true
description: The price of the output in USD.
totalPrice:
type: number
format: double
nullable: true
description: The total price in USD.
calculatedInputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the input in USD
calculatedOutputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the output in USD
calculatedTotalCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated total cost in USD
latency:
type: number
format: double
nullable: true
description: The latency in seconds.
timeToFirstToken:
type: number
format: double
nullable: true
description: The time to the first token in seconds
allOf:
- $ref: '#/components/schemas/Observation'
ObservationV2:
title: ObservationV2
type: object
description: >-
An observation from the v2 API with field-group-based selection.
Core fields are always present. Other fields are included only when
their field group is requested.
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation
projectId:
type: string
description: The project ID this observation belongs to
parentObservationId:
type: string
nullable: true
description: The parent observation ID
type:
type: string
description: The type of the observation (e.g. GENERATION, SPAN, EVENT)
name:
type: string
nullable: true
description: The name of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
version:
type: string
nullable: true
description: The version of the observation
environment:
type: string
nullable: true
description: The environment from which this observation originated
bookmarked:
type: boolean
nullable: true
description: Whether the observation is bookmarked
public:
type: boolean
nullable: true
description: Whether the observation is public
userId:
type: string
nullable: true
description: The user ID associated with the observation
sessionId:
type: string
nullable: true
description: The session ID associated with the observation
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
createdAt:
type: string
format: date-time
nullable: true
description: The creation timestamp of the observation
updatedAt:
type: string
format: date-time
nullable: true
description: The last update timestamp of the observation
input:
nullable: true
description: The input data of the observation
output:
nullable: true
description: The output data of the observation
metadata:
nullable: true
description: Additional metadata of the observation
providedModelName:
type: string
nullable: true
description: The model name as provided by the user
internalModelId:
type: string
nullable: true
description: The internal model ID matched by Langfuse
modelParameters:
nullable: true
description: The parameters of the model used for the observation
usageDetails:
type: object
additionalProperties:
type: integer
nullable: true
description: >-
The usage details of the observation. Key is the usage metric name,
value is the number of units consumed.
costDetails:
type: object
additionalProperties:
type: number
format: double
nullable: true
description: >-
The cost details of the observation. Key is the cost metric name,
value is the cost in USD.
totalCost:
type: number
format: double
nullable: true
description: The total cost of the observation in USD
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
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
- startTime
- projectId
- type
Usage:
title: Usage
type: object
description: >-
(Deprecated. Use usageDetails and costDetails instead.) Standard
interface for usage and cost
properties:
input:
type: integer
description: Number of input units (e.g. tokens)
output:
type: integer
description: Number of output units (e.g. tokens)
total:
type: integer
description: Defaults to input+output if not set
unit:
type: string
nullable: true
description: Unit of measurement
inputCost:
type: number
format: double
nullable: true
description: USD input cost
outputCost:
type: number
format: double
nullable: true
description: USD output cost
totalCost:
type: number
format: double
nullable: true
description: USD total cost, defaults to input+output
required:
- input
- output
- total
ScoreConfig:
title: ScoreConfig
type: object
description: Configuration for a score
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
type: string
dataType:
$ref: '#/components/schemas/ScoreConfigDataType'
isArchived:
type: boolean
description: Whether the score config is archived. Defaults to false
minValue:
type: number
format: double
nullable: true
description: >-
Sets minimum value for numerical scores. If not set, the minimum
value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Sets maximum value for numerical scores. If not set, the maximum
value defaults to +∞
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: Configures custom categories for categorical scores
description:
type: string
nullable: true
description: Description of the score config
required:
- id
- name
- createdAt
- updatedAt
- projectId
- dataType
- isArchived
ConfigCategory:
title: ConfigCategory
type: object
properties:
value:
type: number
format: double
label:
type: string
required:
- value
- label
BaseScoreV1:
title: BaseScoreV1
type: object
properties:
id:
type: string
traceId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
observationId:
type: string
nullable: true
description: The observation ID associated with the score
timestamp:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
authorUserId:
type: string
nullable: true
description: The user ID of the author
comment:
type: string
nullable: true
description: Comment on the score
metadata:
description: Metadata associated with the score
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, config and score name
must be equal and value must comply to optionally defined numerical
range
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
environment:
type: string
description: >-
The environment from which this score originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- traceId
- name
- source
- timestamp
- createdAt
- updatedAt
- metadata
- environment
NumericScoreV1:
title: NumericScoreV1
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
BooleanScoreV1:
title: BooleanScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for
"False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
CategoricalScoreV1:
title: CategoricalScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
TextScoreV1:
title: TextScoreV1
type: object
properties:
stringValue:
type: string
description: The text content of the score (1-500 characters)
required:
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
ScoreV1:
title: ScoreV1
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
- metadata
- environment
NumericScore:
title: NumericScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScore'
BooleanScore:
title: BooleanScore
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for
"False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CategoricalScore:
title: CategoricalScore
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CorrectionScore:
title: CorrectionScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score. Always 0 for correction scores.
stringValue:
type: string
description: The string representation of the correction content
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
TextScore:
title: TextScore
type: object
properties:
stringValue:
type: string
description: The text content of the score (1-500 characters)
required:
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
Score:
title: Score
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
CreateScoreValue:
title: CreateScoreValue
oneOf:
- type: number
format: double
- type: string
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores
Comment:
title: Comment
type: object
properties:
id:
type: string
projectId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
objectType:
$ref: '#/components/schemas/CommentObjectType'
objectId:
type: string
content:
type: string
authorUserId:
type: string
nullable: true
description: The user ID of the comment author
required:
- id
- projectId
- createdAt
- updatedAt
- objectType
- objectId
- content
Dataset:
title: Dataset
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
description: Description of the dataset
metadata:
description: Metadata associated with the dataset
inputSchema:
nullable: true
description: JSON Schema for validating dataset item inputs
expectedOutputSchema:
nullable: true
description: JSON Schema for validating dataset item expected outputs
projectId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- metadata
- projectId
- createdAt
- updatedAt
DatasetItem:
title: DatasetItem
type: object
properties:
id:
type: string
status:
$ref: '#/components/schemas/DatasetStatus'
input:
description: Input data for the dataset item
expectedOutput:
description: Expected output for the dataset item
metadata:
description: Metadata associated with the dataset item
sourceTraceId:
type: string
nullable: true
description: The trace ID that sourced this dataset item
sourceObservationId:
type: string
nullable: true
description: The observation ID that sourced this dataset item
datasetId:
type: string
datasetName:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- status
- input
- expectedOutput
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunItem:
title: DatasetRunItem
type: object
properties:
id:
type: string
datasetRunId:
type: string
datasetRunName:
type: string
datasetItemId:
type: string
traceId:
type: string
observationId:
type: string
nullable: true
description: The observation ID associated with this run item
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- datasetRunId
- datasetRunName
- datasetItemId
- traceId
- createdAt
- updatedAt
DatasetRun:
title: DatasetRun
type: object
properties:
id:
type: string
description: Unique identifier of the dataset run
name:
type: string
description: Name of the dataset run
description:
type: string
nullable: true
description: Description of the run
metadata:
description: Metadata of the dataset run
datasetId:
type: string
description: Id of the associated dataset
datasetName:
type: string
description: Name of the associated dataset
createdAt:
type: string
format: date-time
description: The date and time when the dataset run was created
updatedAt:
type: string
format: date-time
description: The date and time when the dataset run was last updated
required:
- id
- name
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunWithItems:
title: DatasetRunWithItems
type: object
properties:
datasetRunItems:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
required:
- datasetRunItems
allOf:
- $ref: '#/components/schemas/DatasetRun'
Model:
title: Model
type: object
description: >-
Model definition used for transforming usage into USD cost and/or
tokenization.
Models can have either simple flat pricing or tiered pricing:
- Flat pricing: Single price per usage type (legacy, but still
supported)
- Tiered pricing: Multiple pricing tiers with conditional matching based
on usage patterns
The pricing tiers approach is recommended for models with usage-based
pricing variations.
When using tiered pricing, the flat price fields (inputPrice,
outputPrice, prices) are populated
from the default tier for backward compatibility.
properties:
id:
type: string
modelName:
type: string
description: >-
Name of the model definition. If multiple with the same name exist,
they are applied in the following order: (1) custom over built-in,
(2) newest according to startTime where
model.startTime<observation.startTime
matchPattern:
type: string
description: >-
Regex pattern which matches this model definition to
generation.model. Useful in case of fine-tuned models. If you want
to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per input unit
outputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per output unit
totalPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot
be set if input or output price is set.
tokenizerId:
type: string
nullable: true
description: >-
Optional. Tokenizer to be applied to observations which match to
this model. See docs for more details.
tokenizerConfig:
description: >-
Optional. Configuration for the selected tokenizer. Needs to be
JSON. See docs for more details.
isLangfuseManaged:
type: boolean
createdAt:
type: string
format: date-time
description: Timestamp when the model was created
prices:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelPrice'
description: >-
Deprecated. Use 'pricingTiers' instead for models with usage-based
pricing variations.
This field shows prices by usage type from the default pricing tier.
Maintained for backward compatibility.
If the model uses tiered pricing, this field will be populated from
the default tier's prices.
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTier'
description: >-
Array of pricing tiers with conditional pricing based on usage
thresholds.
Pricing tiers enable accurate cost tracking for models that charge
different rates based on usage patterns
(e.g., different rates for high-volume usage, large context windows,
or cached tokens).
Each model must have exactly one default tier (isDefault=true,
priority=0) that serves as a fallback.
Additional conditional tiers can be defined with specific matching
criteria.
If this array is empty, the model uses legacy flat pricing from the
inputPrice/outputPrice/totalPrice fields.
required:
- id
- modelName
- matchPattern
- tokenizerConfig
- isLangfuseManaged
- createdAt
- prices
- pricingTiers
ModelPrice:
title: ModelPrice
type: object
properties:
price:
type: number
format: double
required:
- price
PricingTierCondition:
title: PricingTierCondition
type: object
description: >-
Condition for matching a pricing tier based on usage details. Used to
implement tiered pricing models where costs vary based on usage
thresholds.
How it works:
1. The regex pattern matches against usage detail keys (e.g.,
"input_tokens", "input_cached")
2. Values of all matching keys are summed together
3. The sum is compared against the threshold value using the specified
operator
4. All conditions in a tier must be met (AND logic) for the tier to
match
Common use cases:
- Threshold-based pricing: Match when accumulated usage exceeds a
certain amount
- Usage-type-specific pricing: Different rates for cached vs non-cached
tokens, or input vs output
- Volume-based pricing: Different rates based on total request or token
count
properties:
usageDetailPattern:
type: string
description: >-
Regex pattern to match against usage detail keys. All matching keys'
values are summed for threshold comparison.
Examples:
- "^input" matches "input", "input_tokens", "input_cached", etc.
- "^(input|prompt)" matches both "input_tokens" and "prompt_tokens"
- "_cache$" matches "input_cache", "output_cache", etc.
The pattern is case-insensitive by default. If no keys match, the
sum is treated as zero.
operator:
$ref: '#/components/schemas/PricingTierOperator'
description: >-
Comparison operator to apply between the summed value and the
threshold.
- gt: greater than (sum > threshold)
- gte: greater than or equal (sum >= threshold)
- lt: less than (sum < threshold)
- lte: less than or equal (sum <= threshold)
- eq: equal (sum == threshold)
- neq: not equal (sum != threshold)
value:
type: number
format: double
description: >-
Threshold value for comparison. For token-based pricing, this is
typically the token count threshold (e.g., 200000 for a 200K token
threshold).
caseSensitive:
type: boolean
description: >-
Whether the regex pattern matching is case-sensitive. Default is
false (case-insensitive matching).
required:
- usageDetailPattern
- operator
- value
- caseSensitive
PricingTier:
title: PricingTier
type: object
description: >-
Pricing tier definition with conditional pricing based on usage
thresholds.
Pricing tiers enable accurate cost tracking for LLM providers that
charge different rates based on usage patterns.
For example, some providers charge higher rates when context size
exceeds certain thresholds.
How tier matching works:
1. Tiers are evaluated in ascending priority order (priority 1 before
priority 2, etc.)
2. The first tier where ALL conditions match is selected
3. If no conditional tiers match, the default tier is used as a fallback
4. The default tier has priority 0 and no conditions
Why priorities matter:
- Lower priority numbers are evaluated first, allowing you to define
specific cases before general ones
- Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
"medium usage" (>100K tokens), Priority 0 for default
- Without proper ordering, a less specific condition might match before
a more specific one
Every model must have exactly one default tier to ensure cost
calculation always succeeds.
properties:
id:
type: string
description: Unique identifier for the pricing tier
name:
type: string
description: >-
Name of the pricing tier for display and identification purposes.
Examples: "Standard", "High Volume Tier", "Large Context", "Extended
Context Tier"
isDefault:
type: boolean
description: >-
Whether this is the default tier. Every model must have exactly one
default tier with priority 0 and no conditions.
The default tier serves as a fallback when no conditional tiers
match, ensuring cost calculation always succeeds.
It typically represents the base pricing for standard usage
patterns.
priority:
type: integer
description: >-
Priority for tier matching evaluation. Lower numbers = higher
priority (evaluated first).
The default tier must always have priority 0. Conditional tiers
should have priority 1, 2, 3, etc.
Example ordering:
- Priority 0: Default tier (no conditions, always matches as
fallback)
- Priority 1: High usage tier (e.g., >200K tokens)
- Priority 2: Medium usage tier (e.g., >100K tokens)
This ensures more specific conditions are checked before general
ones.
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: >-
Array of conditions that must ALL be met for this tier to match (AND
logic).
The default tier must have an empty conditions array. Conditional
tiers should have one or more conditions
that define when this tier's pricing applies.
Multiple conditions enable complex matching scenarios (e.g., "high
input tokens AND low output tokens").
prices:
type: object
additionalProperties:
type: number
format: double
description: >-
Prices (USD) by usage type for this tier.
Common usage types: "input", "output", "total", "request", "image"
Prices are specified in USD per unit (e.g., per token, per request,
per second).
Example: {"input": 0.000003, "output": 0.000015} means $3 per
million input tokens and $15 per million output tokens.
required:
- id
- name
- isDefault
- priority
- conditions
- prices
PricingTierInput:
title: PricingTierInput
type: object
description: >-
Input schema for creating a pricing tier. The tier ID will be
automatically generated server-side.
When creating a model with pricing tiers:
- Exactly one tier must have isDefault=true (the fallback tier)
- The default tier must have priority=0 and conditions=[]
- All tier names and priorities must be unique within the model
- Each tier must define at least one price
See PricingTier for detailed information about how tiers work and why
they're useful.
properties:
name:
type: string
description: >-
Name of the pricing tier for display and identification purposes.
Must be unique within the model. Common patterns: "Standard", "High
Volume Tier", "Extended Context"
isDefault:
type: boolean
description: >-
Whether this is the default tier. Exactly one tier per model must be
marked as default.
Requirements for default tier:
- Must have isDefault=true
- Must have priority=0
- Must have empty conditions array (conditions=[])
The default tier acts as a fallback when no conditional tiers match.
priority:
type: integer
description: >-
Priority for tier matching evaluation. Lower numbers = higher
priority (evaluated first).
Must be unique within the model. The default tier must have
priority=0.
Conditional tiers should use priority 1, 2, 3, etc. based on their
specificity.
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: >-
Array of conditions that must ALL be met for this tier to match (AND
logic).
The default tier must have an empty array (conditions=[]).
Conditional tiers should define one or more conditions that specify
when this tier's pricing applies.
Each condition specifies a regex pattern, operator, and threshold
value for matching against usage details.
prices:
type: object
additionalProperties:
type: number
format: double
description: >-
Prices (USD) by usage type for this tier. At least one price must be
defined.
Common usage types: "input", "output", "total", "request", "image"
Prices are in USD per unit (e.g., per token).
Example: {"input": 0.000003, "output": 0.000015} represents $3 per
million input tokens and $15 per million output tokens.
required:
- name
- isDefault
- priority
- conditions
- prices
PricingTierOperator:
title: PricingTierOperator
type: string
enum:
- gt
- gte
- lt
- lte
- eq
- neq
description: Comparison operators for pricing tier conditions
ModelUsageUnit:
title: ModelUsageUnit
type: string
enum:
- CHARACTERS
- TOKENS
- MILLISECONDS
- SECONDS
- IMAGES
- REQUESTS
description: Unit of usage in Langfuse
ObservationLevel:
title: ObservationLevel
type: string
enum:
- DEBUG
- DEFAULT
- WARNING
- ERROR
MapValue:
title: MapValue
oneOf:
- type: string
nullable: true
- type: integer
nullable: true
- type: 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) and cannot be reused across datasets.
status:
$ref: '#/components/schemas/DatasetStatus'
nullable: true
description: Defaults to ACTIVE for newly created items
required:
- datasetName
PaginatedDatasetItems:
title: PaginatedDatasetItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRunItemRequest:
title: CreateDatasetRunItemRequest
type: object
properties:
runName:
type: string
runDescription:
type: string
nullable: true
description: Description of the run. If run exists, description will be updated.
metadata:
nullable: true
description: Metadata of the dataset run, updates run if run already exists
datasetItemId:
type: string
observationId:
type: string
nullable: true
traceId:
type: string
nullable: true
description: >-
traceId should always be provided. For compatibility with older SDK
versions it can also be inferred from the provided observationId.
datasetVersion:
type: string
format: date-time
nullable: true
description: >-
ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
"2026-01-21T14:35:42Z").
Specifies the dataset version to use for this experiment run.
If provided, the experiment will use dataset items as they existed
at or before this timestamp.
If not provided, uses the latest version of dataset items.
createdAt:
type: string
format: date-time
nullable: true
description: >-
Optional timestamp to set the createdAt field of the dataset run
item. If not provided or null, defaults to current timestamp.
required:
- runName
- datasetItemId
PaginatedDatasetRunItems:
title: PaginatedDatasetRunItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PaginatedDatasets:
title: PaginatedDatasets
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Dataset'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRequest:
title: CreateDatasetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
metadata:
nullable: true
inputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item inputs. When set, all new
and existing dataset items will be validated against this schema.
expectedOutputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item expected outputs. When set,
all new and existing dataset items will be validated against this
schema.
required:
- name
PaginatedDatasetRuns:
title: PaginatedDatasetRuns
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRun'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
DeleteDatasetRunResponse:
title: DeleteDatasetRunResponse
type: object
properties:
message:
type: string
required:
- message
HealthResponse:
title: HealthResponse
type: object
properties:
version:
type: string
description: Langfuse server version
example: 1.25.0
status:
type: string
example: OK
required:
- version
- status
IngestionEvent:
title: IngestionEvent
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.
example: novelty
environment:
type: string
nullable: true
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores. Boolean
score values must equal either 1 or 0 (true or false). Text score
values must be between 1 and 500 characters.
comment:
type: string
nullable: true
metadata:
nullable: true
dataType:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
description: >-
When set, must match the score value's type. If not set, will be
inferred from the score value or config
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, the score name must
equal the config name and scores must comply with the config's range
and data type. For categorical scores, the value must map to a
config category. Numeric scores might be constrained by the score
config's max and min values
required:
- name
- value
BaseEvent:
title: BaseEvent
type: object
properties:
id:
type: string
description: UUID v4 that identifies the event
timestamp:
type: string
description: >-
Datetime (ISO 8601) of event creation in client. Should be as close
to actual event creation in client as possible, this timestamp will
be used for ordering of events in future release. Resolution:
milliseconds (required), microseconds (optimal).
metadata:
nullable: true
description: Optional. Metadata field used by the Langfuse SDKs for debugging.
required:
- id
- timestamp
TraceEvent:
title: TraceEvent
type: object
properties:
body:
$ref: '#/components/schemas/TraceBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateObservationEvent:
title: CreateObservationEvent
type: object
properties:
body:
$ref: '#/components/schemas/ObservationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateObservationEvent:
title: UpdateObservationEvent
type: object
properties:
body:
$ref: '#/components/schemas/ObservationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
ScoreEvent:
title: ScoreEvent
type: object
properties:
body:
$ref: '#/components/schemas/ScoreBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
SDKLogEvent:
title: SDKLogEvent
type: object
properties:
body:
$ref: '#/components/schemas/SDKLogBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateGenerationEvent:
title: CreateGenerationEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateGenerationEvent:
title: UpdateGenerationEvent
type: object
properties:
body:
$ref: '#/components/schemas/UpdateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateSpanEvent:
title: CreateSpanEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateSpanEvent:
title: UpdateSpanEvent
type: object
properties:
body:
$ref: '#/components/schemas/UpdateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateEventEvent:
title: CreateEventEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateEventBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
IngestionSuccess:
title: IngestionSuccess
type: object
properties:
id:
type: string
status:
type: integer
required:
- id
- status
IngestionError:
title: IngestionError
type: object
properties:
id:
type: string
status:
type: integer
message:
type: string
nullable: true
error:
nullable: true
required:
- id
- status
IngestionResponse:
title: IngestionResponse
type: object
properties:
successes:
type: array
items:
$ref: '#/components/schemas/IngestionSuccess'
errors:
type: array
items:
$ref: '#/components/schemas/IngestionError'
required:
- successes
- errors
OpenAICompletionUsageSchema:
title: OpenAICompletionUsageSchema
type: object
description: OpenAI Usage schema from (Chat-)Completion APIs
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
prompt_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
completion_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
required:
- prompt_tokens
- completion_tokens
- total_tokens
OpenAIResponseUsageSchema:
title: OpenAIResponseUsageSchema
type: object
description: OpenAI Usage schema from Response API
properties:
input_tokens:
type: integer
output_tokens:
type: integer
total_tokens:
type: integer
input_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
output_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
required:
- input_tokens
- output_tokens
- total_tokens
UsageDetails:
title: UsageDetails
oneOf:
- type: object
additionalProperties:
type: integer
- $ref: '#/components/schemas/OpenAICompletionUsageSchema'
- $ref: '#/components/schemas/OpenAIResponseUsageSchema'
legacyMetricsResponse:
title: legacyMetricsResponse
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
required:
- data
legacyObservations:
title: legacyObservations
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Observation'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
legacyObservationsViews:
title: legacyObservationsViews
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
legacyCreateScoreRequest:
title: legacyCreateScoreRequest
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
sessionId:
type: string
nullable: true
observationId:
type: string
nullable: true
datasetRunId:
type: string
nullable: true
name:
type: string
example: novelty
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores. Boolean
score values must equal either 1 or 0 (true or false). Text score
values must be between 1 and 500 characters.
comment:
type: string
nullable: true
metadata:
type: object
additionalProperties: true
nullable: true
environment:
type: string
nullable: true
description: >-
The environment of the score. Can be any lowercase alphanumeric
string with hyphens and underscores that does not start with
'langfuse'.
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
dataType:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
description: >-
The data type of the score. When passing a configId this field is
inferred. Otherwise, this field must be passed or will default to
numeric.
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. The unique langfuse identifier
of a score config. When passing this field, the dataType and
stringValue fields are automatically populated.
source:
$ref: '#/components/schemas/legacyCreateScoreSource'
nullable: true
description: >-
The source of the score. Defaults to API. Set to ANNOTATION to
prefill scores (e.g. from an LLM) for a human reviewer to verify in
an annotation queue. When source is ANNOTATION, a configId is
required unless dataType is CORRECTION. EVAL is reserved for
internal evaluator outputs and is not accepted on this endpoint.
required:
- name
- value
legacyCreateScoreSource:
title: legacyCreateScoreSource
type: string
enum:
- API
- ANNOTATION
description: |-
Source values accepted when creating a score via the public REST API.
EVAL is reserved for internal evaluator outputs and is intentionally not
exposed here — use commons.ScoreSource when reading scores.
legacyCreateScoreResponse:
title: legacyCreateScoreResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
LlmConnection:
title: LlmConnection
type: object
description: LLM API connection configuration (secrets excluded)
properties:
id:
type: string
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
type: string
description: The adapter used to interface with the LLM
displaySecretKey:
type: string
description: Masked version of the secret key for display purposes
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
description: List of custom model names available for this connection
withDefaultModels:
type: boolean
description: Whether to include default models for this adapter
extraHeaderKeys:
type: array
items:
type: string
description: >-
Keys of extra headers sent with requests (values excluded for
security)
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Required for Bedrock
(`{"region":"us-east-1"}`), optional for VertexAI
(`{"location":"us-central1"}`), not used by other adapters.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- provider
- adapter
- displaySecretKey
- customModels
- withDefaultModels
- extraHeaderKeys
- createdAt
- updatedAt
PaginatedLlmConnections:
title: PaginatedLlmConnections
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LlmConnection'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
UpsertLlmConnectionRequest:
title: UpsertLlmConnectionRequest
type: object
description: Request to create or update an LLM connection (upsert)
properties:
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
$ref: '#/components/schemas/LlmAdapter'
description: The adapter used to interface with the LLM
secretKey:
type: string
description: Secret key for the LLM API.
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
nullable: true
description: List of custom model names
withDefaultModels:
type: boolean
nullable: true
description: Whether to include default models. Default is true.
extraHeaders:
type: object
additionalProperties:
type: string
nullable: true
description: Extra headers to send with requests
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Validation rules: - **Bedrock**:
Required. Must be `{"region": "<aws-region>"}` (e.g.,
`{"region":"us-east-1"}`) - **VertexAI**: Optional. If provided,
must be `{"location": "<gcp-location>"}` (e.g.,
`{"location":"us-central1"}`) - **Other adapters**: Not supported.
Omit this field or set to null.
required:
- provider
- adapter
- secretKey
DeleteLlmConnectionResponse:
title: DeleteLlmConnectionResponse
type: object
properties:
message:
type: string
required:
- message
LlmAdapter:
title: LlmAdapter
type: string
enum:
- anthropic
- openai
- azure
- bedrock
- google-vertex-ai
- google-ai-studio
GetMediaResponse:
title: GetMediaResponse
type: object
properties:
mediaId:
type: string
description: The unique langfuse identifier of a media record
contentType:
type: string
description: The MIME type of the media record
contentLength:
type: integer
description: The size of the media record in bytes
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
url:
type: string
description: The download URL of the media record
urlExpiry:
type: string
description: The expiry date and time of the media record download URL
required:
- mediaId
- contentType
- contentLength
- uploadedAt
- url
- urlExpiry
PatchMediaBody:
title: PatchMediaBody
type: object
properties:
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
uploadHttpStatus:
type: integer
description: The HTTP status code of the upload
uploadHttpError:
type: string
nullable: true
description: The HTTP error message of the upload
uploadTimeMs:
type: integer
nullable: true
description: The time in milliseconds it took to upload the media record
required:
- uploadedAt
- uploadHttpStatus
GetMediaUploadUrlRequest:
title: GetMediaUploadUrlRequest
type: object
properties:
traceId:
type: string
description: The trace ID associated with the media record
observationId:
type: string
nullable: true
description: >-
The observation ID associated with the media record. If the media
record is associated directly with a trace, this will be null.
contentType:
$ref: '#/components/schemas/MediaContentType'
contentLength:
type: integer
description: The size of the media record in bytes
sha256Hash:
type: string
description: The SHA-256 hash of the media record
field:
type: string
description: >-
The trace / observation field the media record is associated with.
This can be one of `input`, `output`, `metadata`
required:
- traceId
- contentType
- contentLength
- sha256Hash
- field
GetMediaUploadUrlResponse:
title: GetMediaUploadUrlResponse
type: object
properties:
uploadUrl:
type: string
nullable: true
description: >-
The presigned upload URL. If the asset is already uploaded, this
will be null
mediaId:
type: string
description: The unique langfuse identifier of a media record
required:
- mediaId
MediaContentType:
title: MediaContentType
type: string
enum:
- image/png
- image/jpeg
- image/jpg
- image/webp
- image/gif
- image/svg+xml
- image/tiff
- image/bmp
- image/avif
- image/heic
- audio/mpeg
- audio/mp3
- audio/wav
- audio/ogg
- audio/oga
- audio/aac
- audio/mp4
- audio/flac
- audio/opus
- audio/webm
- video/mp4
- video/webm
- video/ogg
- video/mpeg
- video/quicktime
- video/x-msvideo
- video/x-matroska
- text/plain
- text/html
- text/css
- text/csv
- text/markdown
- text/x-python
- application/javascript
- text/x-typescript
- application/x-yaml
- application/pdf
- application/msword
- application/vnd.ms-excel
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/zip
- application/json
- application/xml
- application/octet-stream
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/rtf
- application/x-ndjson
- application/vnd.apache.parquet
- application/gzip
- application/x-tar
- application/x-7z-compressed
description: The MIME type of the media record
MetricsV2Response:
title: MetricsV2Response
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
required:
- data
PaginatedModels:
title: PaginatedModels
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Model'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateModelRequest:
title: CreateModelRequest
type: object
properties:
modelName:
type: string
description: >-
Name of the model definition. If multiple with the same name exist,
they are applied in the following order: (1) custom over built-in,
(2) newest according to startTime where
model.startTime<observation.startTime
matchPattern:
type: string
description: >-
Regex pattern which matches this model definition to
generation.model. Useful in case of fine-tuned models. If you want
to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit.
Creates a default tier if pricingTiers not provided.
outputPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit.
Creates a default tier if pricingTiers not provided.
totalPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per total units.
Cannot be set if input or output price is set. Creates a default
tier if pricingTiers not provided.
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTierInput'
nullable: true
description: >-
Optional. Array of pricing tiers for this model.
Use pricing tiers for all models - both those with threshold-based
pricing variations and those with simple flat pricing:
- For models with standard flat pricing: Create a single default
tier with your prices
(e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices)
- For models with threshold-based pricing: Create a default tier
plus additional conditional tiers
(e.g., default tier for standard usage + high-volume tier for usage above certain thresholds)
Requirements:
- Cannot be provided with flat prices
(inputPrice/outputPrice/totalPrice) - use one approach or the other
- Must include exactly one default tier with isDefault=true,
priority=0, and conditions=[]
- All tier names and priorities must be unique within the model
- Each tier must define at least one price
If omitted, you must provide flat prices instead
(inputPrice/outputPrice/totalPrice),
which will automatically create a single default tier named
"Standard".
tokenizerId:
type: string
nullable: true
description: >-
Optional. Tokenizer to be applied to observations which match to
this model. See docs for more details.
tokenizerConfig:
nullable: true
description: >-
Optional. Configuration for the selected tokenizer. Needs to be
JSON. See docs for more details.
required:
- modelName
- matchPattern
ObservationsV2Response:
title: ObservationsV2Response
type: object
description: >-
Response containing observations with field-group-based filtering and
cursor-based pagination.
The `data` array contains observation objects with only the requested
field groups included.
Use the `cursor` in `meta` to retrieve the next page of results.
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObservationV2'
description: >-
Array of observation objects. Fields included depend on the `fields`
parameter in the request.
meta:
$ref: '#/components/schemas/ObservationsV2Meta'
required:
- data
- meta
ObservationsV2Meta:
title: ObservationsV2Meta
type: object
description: Metadata for cursor-based pagination
properties:
cursor:
type: string
nullable: true
description: >-
Base64-encoded cursor to use for retrieving the next page. If not
present, there are no more results.
OtelResourceSpan:
title: OtelResourceSpan
type: object
description: >-
Represents a collection of spans from a single resource as per OTLP
specification
properties:
resource:
$ref: '#/components/schemas/OtelResource'
nullable: true
description: Resource information
scopeSpans:
type: array
items:
$ref: '#/components/schemas/OtelScopeSpan'
nullable: true
description: Array of scope spans
OtelResource:
title: OtelResource
type: object
description: Resource attributes identifying the source of telemetry
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: Resource attributes like service.name, service.version, etc.
OtelScopeSpan:
title: OtelScopeSpan
type: object
description: Collection of spans from a single instrumentation scope
properties:
scope:
$ref: '#/components/schemas/OtelScope'
nullable: true
description: Instrumentation scope information
spans:
type: array
items:
$ref: '#/components/schemas/OtelSpan'
nullable: true
description: Array of spans
OtelScope:
title: OtelScope
type: object
description: Instrumentation scope information
properties:
name:
type: string
nullable: true
description: Instrumentation scope name
version:
type: string
nullable: true
description: Instrumentation scope version
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: Additional scope attributes
OtelSpan:
title: OtelSpan
type: object
description: Individual span representing a unit of work or operation
properties:
traceId:
nullable: true
description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary)
spanId:
nullable: true
description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary)
parentSpanId:
nullable: true
description: Parent span ID if this is a child span
name:
type: string
nullable: true
description: Span name describing the operation
kind:
type: integer
nullable: true
description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER)
startTimeUnixNano:
nullable: true
description: Start time in nanoseconds since Unix epoch
endTimeUnixNano:
nullable: true
description: End time in nanoseconds since Unix epoch
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: >-
Span attributes including Langfuse-specific attributes
(langfuse.observation.*)
status:
nullable: true
description: Span status object
OtelAttribute:
title: OtelAttribute
type: object
description: Key-value attribute pair for resources, scopes, or spans
properties:
key:
type: string
nullable: true
description: Attribute key (e.g., "service.name", "langfuse.observation.type")
value:
$ref: '#/components/schemas/OtelAttributeValue'
nullable: true
description: Attribute value
OtelAttributeValue:
title: OtelAttributeValue
type: object
description: Attribute value wrapper supporting different value types
properties:
stringValue:
type: string
nullable: true
description: String value
intValue:
type: integer
nullable: true
description: Integer value
doubleValue:
type: number
format: double
nullable: true
description: Double value
boolValue:
type: boolean
nullable: true
description: Boolean value
OtelTraceResponse:
title: OtelTraceResponse
type: object
description: Response from trace export request. Empty object indicates success.
properties: {}
MembershipRole:
title: MembershipRole
type: string
enum:
- OWNER
- ADMIN
- MEMBER
- VIEWER
MembershipRequest:
title: MembershipRequest
type: object
properties:
userId:
type: string
role:
$ref: '#/components/schemas/MembershipRole'
required:
- userId
- role
DeleteMembershipRequest:
title: DeleteMembershipRequest
type: object
properties:
userId:
type: string
required:
- userId
MembershipResponse:
title: MembershipResponse
type: object
properties:
userId:
type: string
role:
$ref: '#/components/schemas/MembershipRole'
email:
type: string
name:
type: string
required:
- userId
- role
- email
- name
MembershipDeletionResponse:
title: MembershipDeletionResponse
type: object
properties:
message:
type: string
userId:
type: string
required:
- message
- userId
MembershipsResponse:
title: MembershipsResponse
type: object
properties:
memberships:
type: array
items:
$ref: '#/components/schemas/MembershipResponse'
required:
- memberships
OrganizationProject:
title: OrganizationProject
type: object
properties:
id:
type: string
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- createdAt
- updatedAt
OrganizationProjectsResponse:
title: OrganizationProjectsResponse
type: object
properties:
projects:
type: array
items:
$ref: '#/components/schemas/OrganizationProject'
required:
- projects
OrganizationApiKey:
title: OrganizationApiKey
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
nullable: true
lastUsedAt:
type: string
format: date-time
nullable: true
note:
type: string
nullable: true
publicKey:
type: string
displaySecretKey:
type: string
required:
- id
- createdAt
- publicKey
- displaySecretKey
OrganizationApiKeysResponse:
title: OrganizationApiKeysResponse
type: object
properties:
apiKeys:
type: array
items:
$ref: '#/components/schemas/OrganizationApiKey'
required:
- apiKeys
Projects:
title: Projects
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Project'
required:
- data
Organization:
title: Organization
type: object
properties:
id:
type: string
description: The unique identifier of the organization
name:
type: string
description: The name of the organization
required:
- id
- name
Project:
title: Project
type: object
properties:
id:
type: string
name:
type: string
organization:
$ref: '#/components/schemas/Organization'
description: The organization this project belongs to
metadata:
type: object
additionalProperties: true
description: Metadata for the project
retentionDays:
type: integer
nullable: true
description: >-
Number of days to retain data. Null or 0 means no retention. Omitted
if no retention is configured.
required:
- id
- name
- organization
- metadata
ProjectDeletionResponse:
title: ProjectDeletionResponse
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
ApiKeyList:
title: ApiKeyList
type: object
description: List of API keys for a project
properties:
apiKeys:
type: array
items:
$ref: '#/components/schemas/ApiKeySummary'
required:
- apiKeys
ApiKeySummary:
title: ApiKeySummary
type: object
description: Summary of an API key
properties:
id:
type: string
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
nullable: true
lastUsedAt:
type: string
format: date-time
nullable: true
note:
type: string
nullable: true
publicKey:
type: string
displaySecretKey:
type: string
required:
- id
- createdAt
- publicKey
- displaySecretKey
ApiKeyResponse:
title: ApiKeyResponse
type: object
description: Response for API key creation
properties:
id:
type: string
createdAt:
type: string
format: date-time
publicKey:
type: string
secretKey:
type: string
displaySecretKey:
type: string
note:
type: string
nullable: true
required:
- id
- createdAt
- publicKey
- secretKey
- displaySecretKey
ApiKeyDeletionResponse:
title: ApiKeyDeletionResponse
type: object
description: Response for API key deletion
properties:
success:
type: boolean
required:
- success
PromptMetaListResponse:
title: PromptMetaListResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PromptMeta'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PromptMeta:
title: PromptMeta
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/PromptType'
description: Indicates whether the prompt is a text or chat prompt.
versions:
type: array
items:
type: integer
labels:
type: array
items:
type: string
tags:
type: array
items:
type: string
lastUpdatedAt:
type: string
format: date-time
lastConfig:
description: >-
Config object of the most recent prompt version that matches the
filters (if any are provided)
required:
- name
- type
- versions
- labels
- tags
- lastUpdatedAt
- lastConfig
CreatePromptRequest:
title: CreatePromptRequest
oneOf:
- $ref: '#/components/schemas/CreateChatPromptRequest'
- $ref: '#/components/schemas/CreateTextPromptRequest'
CreateChatPromptRequest:
title: CreateChatPromptRequest
type: object
properties:
name:
type: string
prompt:
type: array
items:
$ref: '#/components/schemas/ChatMessageWithPlaceholders'
config:
nullable: true
type:
$ref: '#/components/schemas/CreateChatPromptType'
labels:
type: array
items:
type: string
nullable: true
description: List of deployment labels of this prompt version.
tags:
type: array
items:
type: string
nullable: true
description: List of tags to apply to all versions of this prompt.
commitMessage:
type: string
nullable: true
description: Commit message for this prompt version.
required:
- name
- prompt
- type
CreateTextPromptRequest:
title: CreateTextPromptRequest
type: object
properties:
name:
type: string
prompt:
type: string
config:
nullable: true
type:
$ref: '#/components/schemas/CreateTextPromptType'
nullable: true
labels:
type: array
items:
type: string
nullable: true
description: List of deployment labels of this prompt version.
tags:
type: array
items:
type: string
nullable: true
description: List of tags to apply to all versions of this prompt.
commitMessage:
type: string
nullable: true
description: Commit message for this prompt version.
required:
- name
- prompt
Prompt:
title: Prompt
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
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'
required:
- data
- meta
PaginatedSessions:
title: PaginatedSessions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Session'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Traces:
title: Traces
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TraceWithDetails'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
properties:
message:
type: string
required:
- message
Sort:
title: Sort
type: object
properties:
id:
type: string
required:
- id
unstableEvaluatorType:
title: unstableEvaluatorType
type: string
enum:
- llm_as_judge
description: >-
The evaluator engine type.
The unstable public API currently supports only LLM-as-a-judge
evaluators.
unstableEvaluatorScope:
title: unstableEvaluatorScope
type: string
enum:
- project
- managed
description: |-
Where an evaluator comes from.
- `project`: created in your project
- `managed`: provided by Langfuse
unstableEvaluationRuleTarget:
title: unstableEvaluationRuleTarget
type: string
enum:
- observation
- experiment
description: >-
The ingestion object type that should trigger evaluation runs.
Choose the target first, because it changes both the valid filter
columns and the valid variable-mapping sources:
- `observation` evaluates live-ingested observations such as
generations, spans, and events.
It supports mapping from `input`, `output`, and `metadata`.
- `experiment` evaluates live experiment executions and can additionally
map `expected_output`.
It currently supports filtering by `datasetId`.
Discover valid dataset IDs with `GET /api/public/v2/datasets`, then use the returned dataset `id` values in your filter.
unstableEvaluationRuleStatus:
title: unstableEvaluationRuleStatus
type: string
enum:
- active
- inactive
- paused
description: >-
Effective runtime status of the evaluation rule.
- `active`: enabled and currently runnable.
- `inactive`: disabled by configuration.
- `paused`: enabled, but Langfuse has blocked execution until the
underlying issue is resolved.
unstableEvaluationRuleMappingSource:
title: unstableEvaluationRuleMappingSource
type: string
enum:
- input
- output
- metadata
- expected_output
description: >-
Source field used to populate a prompt variable.
Use these values when mapping evaluator prompt variables to live data.
Target-specific rules:
- `target=observation` supports `input`, `output`, and `metadata`
- `target=experiment` supports `input`, `output`, `metadata`, and
`expected_output`
Source semantics:
- `input`: the observation or experiment input payload
- `output`: the observation or experiment output payload
- `metadata`: the metadata object for the target. Combine with
`jsonPath` when you need one nested field instead of the whole object.
- `expected_output`: the experiment item's expected output. Only valid
for `target=experiment`.
unstableEvaluatorModelConfig:
title: unstableEvaluatorModelConfig
type: object
description: >-
Optional explicit model configuration for an evaluator.
If omitted, Langfuse uses the project's default evaluation model.
If provided, the model must be available to the project when the
evaluator or evaluation rule is enabled.
To discover valid configured `provider` values for a project, call `GET
/api/public/llm-connections` and read the `provider` field from the
returned connections.
Use a `provider` value that matches one of the connections already
configured in the same project.
Recovery guidance:
- If evaluator creation returns `422` with
`code=evaluator_preflight_failed`, either provide a valid explicit
`modelConfig` here or configure the project's default evaluation model,
then retry the same request.
properties:
provider:
type: string
description: >-
Provider identifier to use for this evaluator, for example `openai`
or `anthropic`.
To discover valid values for the current project, call `GET
/api/public/llm-connections` and use one of the returned `provider`
values.
example: openai
model:
type: string
description: >-
Model identifier exposed by the provider, for example
`gpt-4.1-mini`.
example: gpt-4.1-mini
required:
- provider
- model
unstableEvaluatorOutputDataType:
title: unstableEvaluatorOutputDataType
type: string
enum:
- NUMERIC
- BOOLEAN
- CATEGORICAL
description: >-
Structured score type returned by an evaluator.
This controls the type of score value Langfuse stores for evaluation
results:
- `NUMERIC`: a numeric score such as `0.82`
- `BOOLEAN`: a boolean score such as `true`
- `CATEGORICAL`: one or more category labels from a fixed list
unstableEvaluatorOutputFieldDefinition:
title: unstableEvaluatorOutputFieldDefinition
type: object
properties:
description:
type: string
description: >-
Human-readable instructions for what the evaluator should return in
this field.
required:
- description
unstableEvaluatorOutputDefinition:
title: unstableEvaluatorOutputDefinition
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 prompt variable to one source field from the target
object.
How to build a valid mapping list:
1. Create the evaluator or fetch it with `GET /evaluators/{id}`.
2. Read the evaluator `variables` array.
3. Add exactly one mapping object for each variable in that array.
4. Use the variable name exactly as returned, without braces such as
`{{` or `}}`.
5. Choose a `source` that is valid for the selected `target`.
`jsonPath` is optional. Use it only when the selected source is a JSON
object and you want to extract one nested field before inserting it into
the evaluator prompt.
Recovery guidance:
- `invalid_variable_mapping`: the variable name is unknown for this
evaluator, or the selected `source` is not valid for the chosen `target`
- `missing_variable_mapping`: one or more evaluator variables are not
mapped yet
- `duplicate_variable_mapping`: the same evaluator variable appears more
than once
- `invalid_json_path`: the JSONPath expression is malformed. Remove it
or correct it.
properties:
variable:
type: string
description: >-
Prompt variable name without braces.
Example: for the prompt `Judge {{input}} against {{output}}`, use
`input` and `output`.
example: input
source:
$ref: '#/components/schemas/unstableEvaluationRuleMappingSource'
description: >-
Source field that should populate the prompt variable.
Quick reference:
- `target=observation`: `input`, `output`, `metadata`
- `target=experiment`: `input`, `output`, `metadata`,
`expected_output`
jsonPath:
type: string
nullable: true
description: >-
Optional JSONPath selector applied to the selected source before it
is passed to the evaluator prompt.
Requirements:
- Must start with `$`
- Must be a syntactically valid JSONPath expression
- Most useful with `source=metadata`
required:
- variable
- source
unstableEvaluationRuleFilter:
title: unstableEvaluationRuleFilter
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`
- `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`
- `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.
unstablePublicApiErrorCode:
title: unstablePublicApiErrorCode
type: string
enum:
- authentication_failed
- access_denied
- invalid_request
- invalid_query
- invalid_body
- invalid_filter_value
- invalid_json_path
- invalid_variable_mapping
- missing_variable_mapping
- duplicate_variable_mapping
- resource_not_found
- name_conflict
- evaluator_preflight_failed
- conflict
- unprocessable_content
- rate_limited
- method_not_allowed
- internal_error
description: >-
Machine-readable error code returned by the unstable evaluators API.
SDKs, CLIs, and agents should branch on `code` rather than parsing the
human-readable `message`.
The HTTP status still indicates the broad error class, while `code`
gives the specific failure reason.
unstablePublicApiValidationIssue:
title: unstablePublicApiValidationIssue
type: object
description: >-
One validation issue returned for malformed request bodies or query
parameters.
This mirrors the most important parts of a Zod issue: a machine-readable
`code`,
a human-readable `message`, and a structured `path`.
properties:
code:
type: string
description: >-
Machine-readable validation issue code emitted by the server
validator.
message:
type: string
description: Human-readable explanation of the validation failure.
path:
type: array
items: {}
description: Path to the invalid field, for example `["mapping", 0, "jsonPath"]`.
required:
- code
- message
- path
unstablePublicApiErrorDetails:
title: unstablePublicApiErrorDetails
type: object
description: >-
Optional structured context attached to an unstable-evals error.
The populated fields depend on the error `code`:
- request parsing failures populate `issues`
- filter validation failures populate `field`, `column`,
`invalidValues`, and `allowedValues`
- variable mapping failures populate `field`, `variable`, or `variables`
- JSONPath validation failures populate `field`, `variable`, and `value`
- evaluator preflight failures populate `evaluatorName`, `provider`, and
`model`
- rate limiting populates `retryAfterSeconds`, `limit`, `remaining`, and
`resetAt`
properties:
issues:
type: array
items:
$ref: '#/components/schemas/unstablePublicApiValidationIssue'
nullable: true
description: Validation issues for malformed request bodies or query parameters.
field:
type: string
nullable: true
description: >-
Path-like reference to the failing field, for example
`mapping[1].jsonPath`.
column:
type: string
nullable: true
description: Filter column that failed validation.
invalidValues:
type: array
items:
type: string
nullable: true
description: Unsupported values supplied by the caller.
allowedValues:
type: array
items:
type: string
nullable: true
description: Allowed values for the failing filter column.
variable:
type: string
nullable: true
description: Evaluator variable involved in the failure.
variables:
type: array
items:
type: string
nullable: true
description: >-
Multiple evaluator variables involved in the failure, for example
missing mappings.
value:
type: string
nullable: true
description: Raw invalid value supplied by the caller.
evaluatorName:
type: string
nullable: true
description: Evaluator name used during preflight validation.
provider:
type: string
nullable: true
description: Provider resolved during evaluator preflight, if any.
model:
type: string
nullable: true
description: Model resolved during evaluator preflight, if any.
retryAfterSeconds:
type: integer
nullable: true
description: Suggested retry delay for rate-limited requests.
limit:
type: integer
nullable: true
description: >-
Numeric limit associated with the failure, for example the active
evaluation-rule cap or the current rate-limit window.
remaining:
type: integer
nullable: true
description: Remaining requests in the current rate-limit window.
resetAt:
type: string
nullable: true
description: ISO-8601 timestamp when the current rate-limit window resets.
unstablePublicApiError:
title: unstablePublicApiError
type: object
description: >-
Standard error envelope for the unstable evaluators API.
Response handling guidance:
- Use the HTTP status code for the broad class of failure.
- Use `code` for precise branching in SDKs, CLIs, or agents.
- Inspect `details` for field-level validation context such as invalid
filter values, malformed JSONPath expressions, or missing variable
mappings.
- Retry only after fixing the specific issue described by `code` and
`details`.
properties:
message:
type: string
description: Human-readable description of the failure.
example: 'Filter column "type" contains unsupported value(s): INVALID'
code:
$ref: '#/components/schemas/unstablePublicApiErrorCode'
description: Stable machine-readable error code.
details:
$ref: '#/components/schemas/unstablePublicApiErrorDetails'
nullable: true
description: >-
Optional structured error context. Inspect the populated fields
based on `code`.
required:
- message
- code
unstableEvaluationRule:
title: unstableEvaluationRule
type: object
description: >-
Live evaluation rule for incoming data.
An evaluation rule answers:
- which evaluator should be used
- which target objects should trigger scoring
- how often scoring should run
- which target fields should populate each evaluator variable
- whether the deployment is active, inactive, or paused
Important status semantics:
- `enabled` is the desired on/off setting from the client
- `status` is the effective runtime state after Langfuse applies
validation and blocking rules
- `enabled=true` with `status=paused` means the rule should run, but
Langfuse has paused it until the underlying problem is fixed
properties:
id:
type: string
description: Stable evaluation rule identifier.
example: erule_123
name:
type: string
description: >-
Human-readable deployment name. This is independent from the
evaluator name.
example: answer-correctness-live
evaluator:
$ref: '#/components/schemas/unstableEvaluationRuleEvaluator'
description: >-
Evaluator currently used by this rule.
`name` and `scope` identify the evaluator family conceptually.
`id` is the currently active evaluator version in that family.
If you create a newer project version with the same evaluator name
later, existing evaluation rules are moved to it automatically.
target:
$ref: '#/components/schemas/unstableEvaluationRuleTarget'
description: Target object type that should trigger scoring.
enabled:
type: boolean
description: Desired enabled state configured by the client.
example: true
status:
$ref: '#/components/schemas/unstableEvaluationRuleStatus'
description: >-
Effective runtime status after Langfuse applies validation and
blocking rules.
pausedReason:
type: string
nullable: true
description: Machine-readable reason when `status=paused`, otherwise `null`.
pausedMessage:
type: string
nullable: true
description: Human-readable explanation when `status=paused`, otherwise `null`.
sampling:
type: number
format: double
description: |-
Fraction of matching target objects that should be evaluated.
Must be greater than `0` and less than or equal to `1`.
- `1` means evaluate every matching target.
- `0.25` means evaluate approximately 25% of matching targets.
example: 1
filter:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleFilter'
description: >-
List of filter conditions used to decide whether a target should be
evaluated.
mapping:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleMapping'
description: >-
Variable mappings used to populate the evaluator prompt from the
live target object.
createdAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was created.
example: '2026-03-30T09:20:00.000Z'
updatedAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was last updated.
example: '2026-03-30T09:20:00.000Z'
required:
- id
- name
- evaluator
- target
- enabled
- status
- sampling
- filter
- mapping
- createdAt
- updatedAt
unstableEvaluationRules:
title: unstableEvaluationRules
type: object
description: Paginated list of evaluation rules.
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRule'
description: Evaluation rules in the current page.
meta:
$ref: '#/components/schemas/utilsMetaResponse'
description: Standard pagination metadata.
required:
- data
- meta
unstableCreateEvaluationRuleRequest:
title: unstableCreateEvaluationRuleRequest
type: object
description: >-
Request body for creating an evaluation rule.
Checklist for agents and SDK clients:
- reference an existing evaluator family by `evaluator.name` and
`evaluator.scope`
- choose `target=observation` or `target=experiment`
- if `target=experiment` and you want a dataset filter, call `GET
/api/public/v2/datasets` first and use dataset `id` values in
`filter[].value`
- fetch or inspect the evaluator first, then provide a complete variable
mapping for every evaluator variable listed in `variables`
- optionally narrow execution with `filter`
- set `enabled=true` only when you want live execution immediately
properties:
name:
type: string
description: Human-readable deployment name.
example: answer-correctness-live
evaluator:
$ref: '#/components/schemas/unstableEvaluationRuleEvaluatorReference'
description: >-
Evaluator family to use.
Use `name` and `scope` from the evaluator endpoints.
Langfuse resolves that family to its latest version before saving
the rule.
target:
$ref: '#/components/schemas/unstableEvaluationRuleTarget'
description: Target object type to evaluate.
enabled:
type: boolean
description: Whether the deployment should be active immediately after creation.
example: true
sampling:
type: number
format: double
nullable: true
description: Optional sampling fraction. Defaults to `1`.
filter:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleFilter'
nullable: true
description: >-
Optional filter list.
Omit or pass an empty list to evaluate all matching targets for the
selected `target`.
Each filter object must use a column that is valid for that
`target`.
For `target=experiment`, `column=datasetId` expects dataset `id`
values from `GET /api/public/v2/datasets`, not dataset names.
mapping:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleMapping'
description: >-
Required variable mappings.
Every evaluator variable must appear exactly once.
Build this list from the evaluator `variables` array returned by the
evaluator endpoints.
required:
- name
- evaluator
- target
- enabled
- mapping
unstableUpdateEvaluationRuleRequest:
title: unstableUpdateEvaluationRuleRequest
type: object
description: >-
Partial update body for an evaluation rule.
Provide only the fields you want to change.
An empty body is rejected.
Practical guidance:
- If you only want to rename the rule or change sampling, send just
those fields.
- If you change `evaluator`, send a fresh `mapping` unless you are
certain the existing mapping still matches the evaluator variables.
- If you change `target`, usually send both `filter` and `mapping` in
the same request.
- If you change an experiment `datasetId` filter, call `GET
/api/public/v2/datasets` and use dataset `id` values from that response.
properties:
name:
type: string
nullable: true
description: Updated deployment name.
evaluator:
$ref: '#/components/schemas/unstableEvaluationRuleEvaluatorReference'
nullable: true
description: >-
Updated evaluator family.
Langfuse resolves the provided evaluator family to its latest
version before saving the rule.
target:
$ref: '#/components/schemas/unstableEvaluationRuleTarget'
nullable: true
description: Updated target object type.
enabled:
type: boolean
nullable: true
description: Updated desired enabled state.
sampling:
type: number
format: double
nullable: true
description: Updated sampling fraction.
filter:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleFilter'
nullable: true
description: >-
Updated filter list.
For `target=experiment`, `column=datasetId` expects dataset `id`
values from `GET /api/public/v2/datasets`, not dataset names.
mapping:
type: array
items:
$ref: '#/components/schemas/unstableEvaluationRuleMapping'
nullable: true
description: Updated variable mappings.
unstableDeleteEvaluationRuleResponse:
title: unstableDeleteEvaluationRuleResponse
type: object
description: Confirmation response returned after successful deletion.
properties:
message:
type: string
description: Always `Evaluation rule successfully deleted`.
required:
- message
unstableEvaluationRuleEvaluatorReference:
title: unstableEvaluationRuleEvaluatorReference
type: object
description: >-
Evaluator family reference used when creating or updating an evaluation
rule.
`name` and `scope` are enough to identify the evaluator family in the
authenticated project context.
properties:
name:
type: string
description: Evaluator family name.
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: Whether the evaluator family is project-owned or Langfuse-managed.
required:
- name
- scope
unstableEvaluationRuleEvaluator:
title: unstableEvaluationRuleEvaluator
type: object
description: |-
Resolved evaluator currently used by the evaluation rule.
`id` is the exact active evaluator version.
`name` and `scope` identify the evaluator family conceptually.
properties:
id:
type: string
description: >-
Identifier of the exact evaluator version currently used by the
rule.
name:
type: string
description: Evaluator family name.
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: Whether the evaluator family is project-owned or Langfuse-managed.
required:
- id
- name
- scope
unstableEvaluator:
title: unstableEvaluator
type: object
description: >-
One evaluator that can be used for scoring.
An evaluator describes **how** to score data:
- prompt
- extracted prompt variables
- output schema
- optional explicit model configuration
It does not define **which** live objects are evaluated. That is the job
of `evaluation-rules`.
For agent clients, the most important fields are:
- `variables`: use these exact names when building the evaluation-rule
`mapping` array
- `outputDefinition`: tells you the expected score type and the
evaluator's response instructions
- `modelConfig`: tells you whether the evaluator uses the project
default model (`null`) or an explicit provider/model
Versioning behavior:
- `GET /evaluators` returns the latest version of each available
evaluator.
- `GET /evaluators/{id}` can return an older version.
- Evaluation rules always run against the latest version for the
selected evaluator name within the same source (`project` or `managed`).
properties:
id:
type: string
description: Identifier of this evaluator.
example: evaltmpl_123
name:
type: string
description: Evaluator name.
example: answer-correctness
version:
type: integer
description: Version number of this evaluator.
example: 2
scope:
$ref: '#/components/schemas/unstableEvaluatorScope'
description: >-
Where this evaluator comes from: your project or Langfuse-managed
defaults.
type:
$ref: '#/components/schemas/unstableEvaluatorType'
description: Evaluator engine type. Currently always `llm_as_judge`.
prompt:
type: string
description: Prompt template used during evaluation.
example: |
You are grading an answer.
Input:
{{input}}
Output:
{{output}}
Return a score between 0 and 1.
variables:
type: array
items:
type: string
description: >-
Variables extracted from the evaluator prompt.
Every variable in this list must be mapped exactly once when
creating an evaluation rule.
example:
- input
- output
outputDefinition:
$ref: '#/components/schemas/unstablePublicEvaluatorOutputDefinition'
description: >-
Structured output schema returned by this evaluator.
Responses always include `dataType` and omit the internal
output-definition `version`.
Use `dataType` to decide how future scores should be interpreted.
modelConfig:
$ref: '#/components/schemas/unstableEvaluatorModelConfig'
nullable: true
description: >-
Explicit model configuration, or `null` when the project default
evaluation model is used.
evaluationRuleCount:
type: integer
description: >-
Number of evaluation rules in the project that currently use this
evaluator version.
example: 0
createdAt:
type: string
format: date-time
description: Timestamp when this evaluator was created.
example: '2026-03-30T09:00:00.000Z'
updatedAt:
type: string
format: date-time
description: Timestamp when this evaluator was last updated.
example: '2026-03-30T09:00:00.000Z'
required:
- id
- name
- version
- scope
- type
- prompt
- variables
- outputDefinition
- evaluationRuleCount
- createdAt
- updatedAt
unstableEvaluators:
title: unstableEvaluators
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableEvaluator'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableCreateEvaluatorRequest:
title: unstableCreateEvaluatorRequest
type: object
description: >-
Request body for creating an evaluator.
If the same `name` already exists in your project, Langfuse creates the
next version and returns it.
Existing evaluation rules in the same project are then moved to that new
latest version automatically.
properties:
name:
type: string
description: Evaluator name within the authenticated project.
example: answer-correctness
prompt:
type: string
description: Prompt template used by the evaluator.
example: |
You are grading an answer.
Input:
{{input}}
Output:
{{output}}
Return a score between 0 and 1.
outputDefinition:
$ref: '#/components/schemas/unstableEvaluatorOutputDefinition'
description: >-
Structured output schema the evaluator must return.
Always send `dataType`.
Do not send `version`; it is an internal storage detail and not part
of the public request contract.
modelConfig:
$ref: '#/components/schemas/unstableEvaluatorModelConfig'
nullable: true
description: >-
Optional explicit model configuration. Omit or set to `null` to use
the project default evaluation model.
required:
- name
- prompt
- outputDefinition
utilsMetaResponse:
title: utilsMetaResponse
type: object
properties:
page:
type: integer
description: current page number
limit:
type: integer
description: number of items per page
totalItems:
type: integer
description: number of total items given the current filters/selection (if any)
totalPages:
type: integer
description: number of total pages given the current limit
required:
- page
- limit
- totalItems
- totalPages
securitySchemes:
BasicAuth:
type: http
scheme: basic