openapi: 3.0.1
info:
title: server
version: ''
description: >-
## Real-time data
The only real-time path to get tracing data is to ingest via OpenTelemetry
(`POST /api/public/otel/v1/traces`) and retrieve via Observations API v2
(`GET /api/public/v2/observations`) and Metrics API v2 (`GET
/api/public/v2/metrics`). Other public API write and read endpoints can
delay data by about 10 minutes. Direct OpenTelemetry exporters must send the
`x-langfuse-ingestion-version: 4` header; current Python and JS SDKs already
do. See the [Public API
docs](https://langfuse.com/docs/api-and-data-platform/features/public-api)
and [real-time
ingestion](https://langfuse.com/integrations/native/opentelemetry.md#real-time-ingestion).
## 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
- Self-hosted deployments: interactive API reference at `/api/docs` and
OpenAPI spec at `/api/openapi.yaml`
paths:
/api/public/annotation-queues:
get:
description: Get all annotation queues
operationId: annotationQueues_listQueues
tags:
- AnnotationQueues
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueues'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: &ref_0
- BasicAuth: []
post:
description: Create an annotation queue
operationId: annotationQueues_createQueue
tags:
- AnnotationQueues
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueRequest'
/api/public/annotation-queues/{queueId}:
get:
description: Get an annotation queue by ID
operationId: annotationQueues_getQueue
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/annotation-queues/{queueId}/items:
get:
description: Get items for a specific annotation queue
operationId: annotationQueues_listQueueItems
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: status
in: query
description: Filter by status
required: false
schema:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueueItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: Add an item to an annotation queue
operationId: annotationQueues_createQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueItemRequest'
/api/public/annotation-queues/{queueId}/items/{itemId}:
get:
description: Get a specific item from an annotation queue
operationId: annotationQueues_getQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
patch:
description: Update an annotation queue item
operationId: annotationQueues_updateQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAnnotationQueueItemRequest'
delete:
description: Remove an item from an annotation queue
operationId: annotationQueues_deleteQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/annotation-queues/{queueId}/assignments:
post:
description: Create an assignment for a user to an annotation queue
operationId: annotationQueues_createQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
delete:
description: Delete an assignment for a user to an annotation queue
operationId: annotationQueues_deleteQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
/api/public/integrations/blob-storage:
get:
description: >-
Get all blob storage integrations for the organization (requires
organization-scoped API key)
operationId: blobStorageIntegrations_getBlobStorageIntegrations
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
put:
description: >-
Create or update a blob storage integration for a specific project
(requires organization-scoped API key). The configuration is validated
by performing a test upload to the bucket.
operationId: blobStorageIntegrations_upsertBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBlobStorageIntegrationRequest'
/api/public/integrations/blob-storage/{id}:
get:
description: >-
Get the sync status of a blob storage integration by integration ID
(requires organization-scoped API key)
operationId: blobStorageIntegrations_getBlobStorageIntegrationStatus
tags:
- BlobStorageIntegrations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationStatusResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
delete:
description: >-
Delete a blob storage integration by ID (requires organization-scoped
API key)
operationId: blobStorageIntegrations_deleteBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/comments:
post:
description: >-
Create a comment. Comments may be attached to different object types
(trace, observation, session, prompt).
operationId: comments_create
tags:
- Comments
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
get:
description: Get all comments
operationId: comments_get
tags:
- Comments
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
- name: objectType
in: query
description: >-
Filter comments by object type (trace, observation, session, prompt).
required: false
schema:
type: string
nullable: true
- name: objectId
in: query
description: >-
Filter comments by object id. If objectType is not provided, an
error will be thrown.
required: false
schema:
type: string
nullable: true
- name: authorUserId
in: query
description: Filter comments by author user id.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetCommentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/comments/{commentId}:
get:
description: Get a comment by id
operationId: comments_get-by-id
tags:
- Comments
parameters:
- name: commentId
in: path
description: The unique langfuse identifier of a comment
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/dataset-items:
post:
description: Create a dataset item
operationId: datasetItems_create
tags:
- DatasetItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetItemRequest'
get:
description: >-
Get dataset items. Optionally specify a version to get the items as they
existed at that point in time.
Note: If version parameter is provided, datasetName must also be
provided.
operationId: datasetItems_list
tags:
- DatasetItems
parameters:
- name: datasetName
in: query
required: false
schema:
type: string
nullable: true
- name: sourceTraceId
in: query
required: false
schema:
type: string
nullable: true
- name: sourceObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: version
in: query
description: >-
ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
"2026-01-21T14:35:42Z").
If provided, returns state of dataset at this timestamp.
If not provided, returns the latest version. Requires datasetName to
be specified.
required: false
schema:
type: string
format: date-time
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/dataset-items/{id}:
get:
description: Get a dataset item
operationId: datasetItems_get
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
delete:
description: >-
Delete a dataset item and all its run items. This action is irreversible.
operationId: datasetItems_delete
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/dataset-run-items:
post:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, create
experiment data via the SDK experiment runner or the OpenTelemetry
endpoint at POST /api/public/otel/v1/traces. Self-hosted deployments are
unaffected by this date; the endpoint becomes unavailable when they
upgrade to Langfuse v4. See the [Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Create a dataset run item
operationId: datasetRunItems_create
tags:
- DatasetRunItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRunItemRequest'
deprecated: true
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, dataset
run items are replaced by experiment items; use `GET
/api/public/experiment-items?fromStartTime=<from>&toStartTime=<to>`
instead. Self-hosted deployments are unaffected by this date; the
endpoint becomes unavailable when they upgrade to Langfuse v4. See the
[Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
List dataset run items
operationId: datasetRunItems_list
tags:
- DatasetRunItems
parameters:
- name: datasetId
in: query
required: true
schema:
type: string
- name: runName
in: query
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRunItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/v2/datasets:
get:
description: Get all datasets
operationId: datasets_list
tags:
- Datasets
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasets'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: Create a dataset
operationId: datasets_create
tags:
- Datasets
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRequest'
/api/public/v2/datasets/{datasetName}:
get:
description: Get a dataset
operationId: datasets_get
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/datasets/{datasetName}/runs/{runName}:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, dataset
runs are replaced by experiments; use GET /api/public/experiments
instead. Self-hosted deployments are unaffected by this date; the
endpoint becomes unavailable when they upgrade to Langfuse v4. See the
[Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get a dataset run and its items
operationId: datasets_getRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunWithItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
delete:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, dataset
runs are replaced by experiments. Self-hosted deployments are unaffected
by this date; the endpoint becomes unavailable when they upgrade to
Langfuse v4. See the [Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Delete a dataset run and all its run items. This action is irreversible.
operationId: datasets_deleteRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetRunResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/datasets/{datasetName}/runs:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, dataset
runs are replaced by experiments; use GET /api/public/experiments
instead. Self-hosted deployments are unaffected by this date; the
endpoint becomes unavailable when they upgrade to Langfuse v4. See the
[Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get dataset runs
operationId: datasets_getRuns
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRuns'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/v2/evaluation-rules:
post:
description: >-
Create an evaluation rule using stable evaluator identifiers.
An evaluation rule defines **which** incoming observations should be
evaluated and how prompt variables should be populated.
Key behavior:
- rule names are not identifiers and do not need to be unique
- rules always use the latest version of each associated evaluator
- an enabled rule requires at least one evaluator assignment
- omit `sampling` to evaluate every matching observation
- omit `filter` to match every incoming observation
- `datasetId` is the public filter name for selecting experiment
datasets
operationId: evaluationRules_create
tags:
- EvaluationRules
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluationRuleRequest'
get:
description: >-
List evaluation rules in newest-first creation order.
This includes legacy trace and dataset rules so they can be inspected
and migrated. Treat the cursor as opaque and return it unchanged.
operationId: evaluationRules_list
tags:
- EvaluationRules
parameters:
- name: limit
in: query
description: >-
Maximum number of items to return. Defaults to `50` and cannot
exceed `100`.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Opaque cursor returned by the previous page.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationRulesPage'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
/api/public/v2/evaluation-rules/{evaluationRuleId}:
get:
description: >-
Get one evaluation rule, including a legacy trace or dataset rule, by
its stable identifier.
operationId: evaluationRules_get
tags:
- EvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: >-
Stable evaluation-rule identifier returned by the evaluation-rule
endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
patch:
description: >-
Update an evaluation rule by its stable identifier.
Provide only the fields to change. Providing `evaluatorAssignments`
replaces the complete assignment list. Replacing the list with an empty
array disables the rule. Setting `enabled=true` is rejected when the
resulting assignment list is empty, including when both fields are sent
in the same request.
Legacy trace and dataset rules follow the existing lifecycle
restrictions: they can be deactivated with `enabled=false`, but their
name, filters, sampling, and evaluator assignments cannot be changed.
operationId: evaluationRules_update
tags:
- EvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: >-
Stable evaluation-rule identifier returned by the evaluation-rule
endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEvaluationRuleRequest'
delete:
description: >-
Delete an evaluation rule.
This removes the live-ingestion rule only. It does not delete associated
evaluators or scores already produced by them.
Legacy trace and dataset rules can also be deleted. Their evaluators and
previously produced scores are preserved.
operationId: evaluationRules_delete
tags:
- EvaluationRules
parameters:
- name: evaluationRuleId
in: path
description: >-
Stable evaluation-rule identifier returned by the evaluation-rule
endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedEvaluationRule'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
/api/public/v2/evaluators:
post:
description: >-
Create an evaluator in the authenticated project.
An evaluator defines **how** Langfuse should score data. LLM-as-a-judge
evaluators define a prompt, expected structured output, and optional
model configuration. Code evaluators define source code and a runtime
language.
This always creates a new evaluator with version `1`. Names are not
identifiers and do not need to be unique.
operationId: evaluators_create
tags:
- Evaluators
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Evaluator'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'412':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEvaluatorRequest'
get:
description: >-
List evaluators in newest-first creation order.
Every evaluator includes its latest definition and version metadata
flattened into the evaluator object, plus associated evaluation rules.
Treat the cursor as opaque and return it unchanged.
operationId: evaluators_list
tags:
- Evaluators
parameters:
- name: limit
in: query
description: >-
Maximum number of items to return. Defaults to `50` and cannot
exceed `100`.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Opaque cursor returned by the previous page.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluatorsPage'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
/api/public/v2/evaluators/{evaluatorId}:
get:
description: >-
Get one evaluator by its stable identifier.
The response includes the evaluator's latest definition and version
metadata flattened into the evaluator object, plus associated evaluation
rules. Use the version-history endpoint when older definitions are
needed.
operationId: evaluators_get
tags:
- Evaluators
parameters:
- name: evaluatorId
in: path
description: Stable evaluator identifier returned by the evaluator endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Evaluator'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
patch:
description: >-
Update an evaluator by its stable identifier.
Provide only the top-level fields to change. Metadata-only changes do
not create a version. Evaluator type cannot change.
Definition fields are flattened into the request. To replace a
definition, include `type` and every definition field for that type.
Definition fields are replaced as a complete unit rather than merged.
For LLM-as-a-judge evaluators, omitting or setting `modelConfig` to
`null` selects the project's default evaluation model.
Replacing a definition automatically returns an evaluator paused by an
invalid or missing model configuration to `active`, while preserving its
id and evaluation-rule assignments. Pauses caused by provider
authentication, billing, connectivity, account state, or an unknown
legacy reason remain paused until the explicit reactivation check
succeeds.
operationId: evaluators_update
tags:
- Evaluators
parameters:
- name: evaluatorId
in: path
description: Stable evaluator identifier returned by the evaluator endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Evaluator'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'412':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEvaluatorRequest'
delete:
description: >-
Delete an evaluator and all of its stored versions.
Associated evaluation-rule assignments are also removed. Scores already
produced by the evaluator are preserved.
operationId: evaluators_delete
tags:
- Evaluators
parameters:
- name: evaluatorId
in: path
description: Stable evaluator identifier returned by the evaluator endpoints.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeletedEvaluator'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
/api/public/v2/evaluators/{evaluatorId}/versions:
get:
description: >-
List an evaluator's version history in newest-first order.
This endpoint is intended for history and audit use cases. Ordinary
clients can use the flattened `version` and definition fields on the
evaluator response.
operationId: evaluators_listVersions
tags:
- Evaluators
parameters:
- name: evaluatorId
in: path
description: Stable evaluator identifier returned by the evaluator endpoints.
required: true
schema:
type: string
- name: limit
in: query
description: >-
Maximum number of versions to return. Defaults to `50` and cannot
exceed `100`.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Opaque cursor returned by the previous page.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EvaluatorVersionsPage'
'400':
description: ''
content:
application/json:
schema: {}
'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/PublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
security: *ref_0
/api/public/experiments:
get:
description: |-
List experiments with cursor-based pagination. Results are ordered by
latest experiment activity descending.
operationId: experiments_list
tags:
- Experiments
parameters:
- name: fields
in: query
description: |-
Comma-separated list of field groups to include. Available groups:
`core`, `metadata`, `scores`. If omitted, `core` is returned.
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: Number of experiments to return per page. Maximum 100, default 50.
required: false
schema:
type: integer
nullable: true
- name: scoreLimit
in: query
description: >-
Number of scores to return per experiment when `fields=scores` is
requested. Maximum 50, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Versioned base64url cursor from the previous response page.
required: false
schema:
type: string
nullable: true
- name: fromStartTime
in: query
description: |-
Required. Retrieve only experiments with events on or after this
datetime. A lower bound is required so the query stays fast on
large projects; pair it with `toStartTime` to select a specific
window.
required: true
schema:
type: string
format: date-time
- name: toStartTime
in: query
description: Retrieve only experiments before this datetime.
required: false
schema:
type: string
format: date-time
nullable: true
- name: id
in: query
description: Comma-separated list of experiment IDs.
required: false
schema:
type: string
nullable: true
- name: name
in: query
description: Comma-separated list of experiment names.
required: false
schema:
type: string
nullable: true
- name: datasetId
in: query
description: Comma-separated list of dataset IDs.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: |-
JSON string containing an array of structured filter conditions.
Supported columns are `id`, `name`, and `datasetId`.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExperimentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/experiment-items:
get:
description: |-
List experiment items with cursor-based pagination. Use this endpoint
to export experiment item inputs, outputs, expected outputs, metadata,
and optionally item/trace scores. Results are ordered by time
descending.
operationId: experiments_listItems
tags:
- Experiments
parameters:
- name: fields
in: query
description: |-
Comma-separated list of field groups to include. Available groups:
`core`, `dataset`, `io`, `metadata`, `itemMetadata`,
`experimentMetadata`, `scores`. If omitted, `core,dataset` is
returned.
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: >-
Number of experiment items to return per page. Maximum 100, default
50.
required: false
schema:
type: integer
nullable: true
- name: scoreLimit
in: query
description: >-
Number of scores to return per experiment item when `fields=scores`
is requested. Maximum 50, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: Versioned base64url cursor from the previous response page.
required: false
schema:
type: string
nullable: true
- name: fromStartTime
in: query
description: |-
Required. Retrieve only experiment items started on or after this
datetime. A lower bound is required so the query stays fast on
large projects; pair it with `toStartTime` to select a specific
window.
required: true
schema:
type: string
format: date-time
- name: toStartTime
in: query
description: Retrieve only experiment items started before this datetime.
required: false
schema:
type: string
format: date-time
nullable: true
- name: experimentId
in: query
description: Comma-separated list of experiment IDs.
required: false
schema:
type: string
nullable: true
- name: experimentName
in: query
description: Comma-separated list of experiment names.
required: false
schema:
type: string
nullable: true
- name: experimentItemId
in: query
description: Comma-separated list of experiment item IDs.
required: false
schema:
type: string
nullable: true
- name: datasetId
in: query
description: Comma-separated list of dataset IDs.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: |-
JSON string containing an array of structured filter conditions.
Supported columns are `experimentId`, `experimentName`,
`experimentItemId`, and `datasetId`.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExperimentItemsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/feedback:
post:
description: >-
Submit explicit user-approved feedback about Langfuse skills, MCP tools,
CLI, docs, or public API. Do not include secrets, credentials, customer
data, trace payloads, or unrelated use-case details.
Not available in the HIPAA cloud region.
operationId: feedback_submit
tags:
- Feedback
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitFeedbackResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'409':
description: ''
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmitFeedbackRequest'
/api/public/health:
get:
description: Check health of API and database
operationId: health_health
tags:
- Health
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'503':
description: ''
/api/public/ingestion:
post:
description: >-
**Deprecated:** On Langfuse Cloud, this is the deprecated Langfuse v3
ingestion API and it is shut down on November 16, 2026, except for score
events: from that date it accepts only `score-create` events and rejects
all other event types. To write scores, prefer `POST
/api/public/scores`; see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs; if you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for
example with curl); see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`; all other
public APIs may have data delays of several minutes. Self-hosted
deployments are unaffected by the November 16 date; this behavior begins
only when they enable v4-only write mode. See the [Langfuse v3 to v4
upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
**Legacy endpoint for batch ingestion for Langfuse Observability.**
This is the deprecated Langfuse v3 ingestion API. It is shut down on
November 16, 2026, except for score events: from that date it accepts
only `score-create` events and rejects all other event types.
To write scores, prefer `POST /api/public/scores`:
https://langfuse.com/docs/api-and-data-platform/features/scores-api
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl:
https://langfuse.com/integrations/native/opentelemetry
To read data back, use the v4 read APIs:
https://langfuse.com/docs/api-and-data-platform/features/observations-api
and https://langfuse.com/docs/metrics/features/metrics-api
The only path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Internally, we refer to this as the "event envelope" as it tells us
something about the event but not the trace.
We use the event id within this envelope to deduplicate messages to
avoid processing the same event twice, i.e. the event id should be
unique per request.
The event.body.id is the ID of the actual trace and will be used for
updates and will be visible within the Langfuse App.
I.e. if you want to update a trace, you'd use the same body id, but
separate event IDs.
Notes:
- Introduction to data model:
https://langfuse.com/docs/observability/data-model
- Batch sizes are limited to 3.5 MB in total. You need to adjust the
number of events per batch accordingly.
- The API does not return a 4xx status code for input errors. Instead,
it responds with a 207 status code, which includes a list of the
encountered errors.
operationId: ingestion_batch
tags:
- Ingestion
parameters: []
responses:
'207':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
batch:
type: array
items:
$ref: '#/components/schemas/IngestionEvent'
description: >-
Batch of events to be ingested, discriminated by attribute
`type`. From November 16, 2026 on Langfuse Cloud, only
`score-create` events are accepted; all other event types
are rejected.
metadata:
nullable: true
description: >-
Optional. Metadata field used by the Langfuse SDKs for
debugging.
required:
- batch
deprecated: true
/api/public/metrics:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. Use `GET
/api/public/v2/metrics?query=<urlencoded json query>` instead.
Self-hosted deployments are unaffected by this date; the endpoint
becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse
v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get metrics from the Langfuse project using a query object.
Consider using the [v2 metrics
endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for
better performance.
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
operationId: legacy_metricsV1_metrics
tags:
- LegacyMetricsV1
parameters:
- name: query
in: query
description: >-
JSON string containing the query parameters with the following
structure:
```json
{
"view": string, // Required. One of "traces", "observations", "scores-numeric", "scores-boolean", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by, e.g. "name", "userId", "sessionId"
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure, e.g. "count", "latency", "value"
"aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on
"operator": string, // Operator, e.g. "=", ">", "<", "contains"
"value": any, // Value to compare against
"type": string, // Data type, e.g. "string", "number", "stringObject"
"key": string // Required only when filtering on metadata
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "minute", "hour", "day", "week", "month", "auto"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram (1-100), default: 10
"row_limit": number // Optional. Row limit for results (1-1000)
}
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/legacyMetricsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/observations/{observationId}:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. Use `GET
/api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`
instead. Self-hosted deployments are unaffected by this date; the
endpoint becomes unavailable when they upgrade to Langfuse v4. See the
[Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
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
- name: startTime
in: query
description: >-
The start time of the observation (ISO 8601 with offset, e.g.
2024-01-01T00:00:00Z). Optional performance hint - when provided,
Langfuse narrows the lookup to make the request substantially
faster. It only affects speed - an incorrect or omitted value never
changes the result.
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsViewSingle'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/observations:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. Use `GET
/api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`
instead. Self-hosted deployments are unaffected by this date; the
endpoint becomes unavailable when they upgrade to Langfuse v4. See the
[Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
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", "is set", "is not set"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Associated Trace Fields (requires join with traces table)
- `userId` (string) - User ID from associated trace
- `traceName` (string) - Name from associated trace
- `traceEnvironment` (string) - Environment from associated trace
- `traceTags` (arrayOptions) - Tags from associated trace
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/legacyObservationsViews'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/scores/{scoreId}:
delete:
description: Delete a score (supports both trace and session scores)
operationId: legacy_scoreV1_delete
tags:
- LegacyScoreV1
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/llm-connections:
get:
description: Get all LLM connections in a project
operationId: llmConnections_list
tags:
- LlmConnections
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedLlmConnections'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
put:
description: >-
Create or update an LLM connection. The connection is upserted on
provider.
operationId: llmConnections_upsert
tags:
- LlmConnections
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/LlmConnection'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertLlmConnectionRequest'
/api/public/llm-connections/{id}:
delete:
description: >-
Delete an LLM connection by id. Evaluators that depend on the deleted
connection are automatically paused.
operationId: llmConnections_delete
tags:
- LlmConnections
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteLlmConnectionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/media/{mediaId}:
get:
description: Get a media record
operationId: media_get
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
patch:
description: Patch a media record
operationId: media_patch
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchMediaBody'
/api/public/media:
post:
description: Get a presigned upload URL for a media record
operationId: media_getUploadUrl
tags:
- Media
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlRequest'
/api/public/v2/metrics:
get:
description: >-
Get metrics from the Langfuse project using a query object. V2 endpoint
with optimized performance.
Together with OpenTelemetry ingestion and Observations API v2, this is
the only real-time read path. Other public API endpoints can delay data
by about 10 minutes.
## V2 Differences
- Supports `observations`, `scores-numeric`, `scores-boolean`, and
`scores-categorical` views only (traces view not supported)
- Direct access to tags and release fields on observations
- Semantic-root filtering and grouping through the v2-only
`isRootObservation` dimension
- Backwards-compatible: traceName, traceRelease, traceVersion dimensions
are still available on observations view
- High cardinality dimensions are not supported and will return a 400
error (see below)
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
## Available Views
### observations
Query observation-level data (spans, generations, events).
**Dimensions:**
- `environment` - Deployment environment (e.g., production, staging)
- `type` - Type of observation (SPAN, GENERATION, EVENT)
- `name` - Name of the observation
- `level` - Logging level of the observation
- `version` - Version of the observation
- `tags` - User-defined tags
- `release` - Release version
- `traceName` - Name of the parent trace (backwards-compatible)
- `traceRelease` - Release version of the parent trace
(backwards-compatible, maps to release)
- `traceVersion` - Version of the parent trace (backwards-compatible,
maps to version)
- `providedModelName` - Name of the model used
- `promptName` - Name of the prompt used
- `promptVersion` - Version of the prompt used
- `isRootObservation` - Boolean semantic-root status. `true` includes
physical roots and app roots whose SDK parent is external (so
`parentObservationId` may be non-null).
- `startTimeMonth` - Month of start_time in YYYY-MM format
**Measures:**
- `count` - Total number of observations
- `latency` - Observation latency (milliseconds)
- `streamingLatency` - Generation latency from completion start to end
(milliseconds)
- `inputTokens` - Sum of input tokens consumed
- `outputTokens` - Sum of output tokens produced
- `totalTokens` - Sum of all tokens consumed
- `outputTokensPerSecond` - Output tokens per second
- `tokensPerSecond` - Total tokens per second
- `inputCost` - Input cost (USD)
- `outputCost` - Output cost (USD)
- `totalCost` - Total cost (USD)
- `timeToFirstToken` - Time to first token (milliseconds)
- `countScores` - Number of scores attached to the observation
### scores-numeric
Query numeric and boolean score data.
**Dimensions:**
- `environment` - Deployment environment
- `name` - Name of the score (e.g., accuracy, toxicity)
- `source` - Origin of the score (API, ANNOTATION, EVAL)
- `dataType` - Data type (NUMERIC, BOOLEAN)
- `configId` - Identifier of the score config
- `timestampMonth` - Month in YYYY-MM format
- `timestampDay` - Day in YYYY-MM-DD format
- `value` - Numeric value of the score
- `traceName` - Name of the parent trace
- `tags` - Tags
- `traceRelease` - Release version
- `traceVersion` - Version
- `observationName` - Name of the associated observation
- `observationModelName` - Model name of the associated observation
- `observationPromptName` - Prompt name of the associated observation
- `observationPromptVersion` - Prompt version of the associated
observation
**Measures:**
- `count` - Total number of scores
- `value` - Score value (for aggregations)
### scores-boolean
Query boolean score data. It has the same score and parent
trace/observation dimensions as scores-numeric, plus:
**Dimensions:**
- `booleanValue` - Boolean value for true/false grouping and filtering
**Measures:**
- `count` - Total number of boolean scores
- `value` - Numeric 0/1 score value; `avg` returns the true-rate
### scores-categorical
Query categorical score data. Same dimensions as scores-numeric except
uses `stringValue` instead of `value`.
**Measures:**
- `count` - Total number of scores
## High Cardinality Dimensions
The following dimensions cannot be used as grouping dimensions in v2
metrics API as they can cause performance issues.
Use them in filters instead.
**observations view:**
- `id` - Use traceId filter to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `parentObservationId` - Use parentObservationId filter instead
**scores-numeric / scores-boolean / scores-categorical views:**
- `id` - Use specific filters to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `observationId` - Use observationId filter instead
## Aggregations
Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,
`p50`, `p75`, `p90`, `p95`, `p99`, `histogram`
## Time Granularities
Available granularities for timeDimension: `auto`, `minute`, `hour`,
`day`, `week`, `month`
- `auto` bins the data into approximately 50 buckets based on the time
range
operationId: metrics_metrics
tags:
- Metrics
parameters:
- name: query
in: query
description: >-
JSON string containing the query parameters with the following
structure:
```json
{
"view": string, // Required. One of "observations", "scores-numeric", "scores-boolean", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by (see available dimensions above)
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure (see available measures above)
"aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on (any dimension field)
"operator": string, // Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject/numberObject: same as string/number with required "key"
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Value to compare against
"type": string, // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"key": string // Required only for stringObject/numberObject types (e.g., metadata filtering)
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "auto", "minute", "hour", "day", "week", "month"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range (must be after fromTimestamp)
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by (dimension or metric alias)
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram aggregation (1-100), default: 10
"row_limit": number // Optional. Maximum number of rows to return (1-1000), default: 100
}
}
```
For example, to count semantic roots (including app roots with a
non-null external parent), use a boolean filter:
```json
{
"view": "observations",
"metrics": [{"measure": "count", "aggregation": "count"}],
"filters": [{"column": "isRootObservation", "operator": "=", "value": true, "type": "boolean"}],
"fromTimestamp": "2025-01-01T00:00:00.000Z",
"toTimestamp": "2025-02-01T00:00:00.000Z"
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/models:
post:
description: Create a model
operationId: models_create
tags:
- Models
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
get:
description: Get all models
operationId: models_list
tags:
- Models
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedModels'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/models/{id}:
put:
description: >-
Create or replace a project-owned model using its id. Built-in models
cannot be modified.
operationId: models_upsert
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
get:
description: Get a model
operationId: models_get
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
delete:
description: >-
Delete a model. Cannot delete models managed by Langfuse. You can create
your own definition with the same modelName to override the definition
though.
operationId: models_delete
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/v2/observations:
get:
description: >-
Get a list of observations with cursor-based pagination and flexible
field selection.
Together with OpenTelemetry ingestion and Metrics API v2, this is the
only real-time read path. Other public API endpoints can delay data by
about 10 minutes.
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of
large datasets.
The cursor is returned in the response metadata and should be passed in
subsequent requests
to retrieve the next page of results.
## Field Selection
Use the `fields` parameter to control which observation fields are
returned:
- `core` - Always included: id, traceId, startTime, endTime, projectId,
parentObservationId, type
- `basic` - name, level, statusMessage, version, environment,
bookmarked, public, userId, sessionId, isRootObservation
- `time` - completionStartTime, createdAt, updatedAt
- `io` - input, output
- `metadata` - metadata (truncated to 200 chars by default, use
`expandMetadata` to get full values)
- `model` - model, internalModelId, modelParameters
- `usage` - usageDetails, costDetails, totalCost, usagePricingTierName
- `prompt` - promptId, promptName, promptVersion
- `metrics` - latency, timeToFirstToken
- `trace_context` - tags, release, traceName
If not specified, `core` and `basic` field groups are returned.
## Filters
Multiple filtering options are available via query parameters or the
structured `filter` parameter.
When using the `filter` parameter, it takes precedence over individual
query parameter filters.
operationId: observations_getMany
tags:
- Observations
parameters:
- name: fields
in: query
description: >-
Comma-separated list of field groups to include in the response.
Available groups: core, basic, time, io, metadata, model, usage,
prompt, metrics, trace_context.
If not specified, `core` and `basic` field groups are returned.
Example: "basic,usage,model"
required: false
schema:
type: string
nullable: true
- name: expandMetadata
in: query
description: |-
Comma-separated list of metadata keys to return non-truncated.
By default, metadata values over 200 characters are truncated.
Use this parameter to retrieve full values for specific keys.
Example: "key1,key2"
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: Number of items to return per page. Maximum 1000, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: >-
Base64-encoded cursor for pagination. Use the cursor from the
previous response to get the next page.
required: false
schema:
type: string
nullable: true
- name: parseIoAsJson
in: query
description: |-
**Deprecated.** Setting this to `true` will return a 400 error.
Input/output fields are always returned as raw strings.
Remove this parameter or set it to `false`.
required: false
schema:
type: boolean
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
description: Filter by session ID.
required: false
schema:
type: string
nullable: true
- name: type
in: query
description: >-
Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
"AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
"GUARDRAIL")
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
required: false
schema:
type: string
nullable: true
- name: level
in: query
description: >-
Optional filter for observations with a specific level (e.g.
"DEBUG", "DEFAULT", "WARNING", "ERROR").
required: false
schema:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
- name: parentObservationId
in: query
description: >-
Filter by the physical parent observation ID.
An empty value matches only observations without a physical parent.
Use `isRootObservation` to include observations marked as app roots
by the SDK, which may retain a non-null `parentObservationId`.
required: false
schema:
type: string
nullable: true
- name: isRootObservation
in: query
description: >-
Filter by whether an observation is a logical root.
Root observations include observations without a physical parent and
observations marked as app roots by the SDK.
An app-root observation may have `isRootObservation=true` and a
non-null `parentObservationId`.
required: false
schema:
type: boolean
nullable: true
- name: environment
in: query
description: >-
Optional filter for observations where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fromStartTime
in: query
description: >-
Retrieve only observations with a start_time on or after this
datetime (ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: toStartTime
in: query
description: >-
Retrieve only observations with a start_time before this datetime
(ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: version
in: query
description: Optional filter to only include observations with a certain version.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
type, level, environment, fromStartTime, ...).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with", "matches"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
- `isRootObservation` (boolean) - Whether the observation is a
logical root. Observations marked as app roots by the SDK may retain
a non-null parentObservationId.
### Trace-Related Fields
- `traceName` (string) - Name of the parent trace
- `traceTags` (arrayOptions) - Tags from the parent trace
- `tags` (arrayOptions) - Alias for traceTags
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name (alias:
`providedModelName`)
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `input` (string) - Observation input. Supports accelerated indexed
literal search with the `matches` operator.
- `output` (string) - Observation output. Supports accelerated
indexed literal search with the `matches` operator.
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
The `matches` operator is only supported for `input`, `output`, and
stringObject `metadata` filters. It performs indexed literal search
with token-boundary pruning using the events table text indexes.
Case sensitivity differs by target: `input` and `output` matches are
case-insensitive, while metadata value matches are case-sensitive.
Unlike SQL `LIKE`, `%` and `_` are treated as literal characters.
Use `contains` for legacy substring semantics where the API allows
it. Any v2 `input` or `output` filter must be accompanied by at
least one `=` or `matches` filter on `input` or `output`; standalone
`contains`, `starts with`, `ends with`, and `does not contain`
filters on these columns are rejected.
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
},
{
"type": "string",
"column": "output",
"operator": "matches",
"value": "needle"
},
{
"type": "boolean",
"column": "isRootObservation",
"operator": "=",
"value": true
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/otel/v1/traces:
post:
description: >-
**OpenTelemetry Traces Ingestion Endpoint**
This endpoint implements the OTLP/HTTP specification for trace
ingestion, providing native OpenTelemetry integration for Langfuse
Observability.
Together with Observations API v2 and Metrics API v2, this is the only
real-time write path. Other public API endpoints can delay data by about
10 minutes. Direct exporters must send `x-langfuse-ingestion-version:
4`; current Python and JS SDKs already do.
**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`
- JSON Protobuf: `Content-Type: application/json`
- Supports gzip compression via `Content-Encoding: gzip` header
**Specification Compliance:**
- Conforms to [OTLP/HTTP Trace
Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
- Implements `ExportTraceServiceRequest` message format
**Documentation:**
- Integration guide:
https://langfuse.com/integrations/native/opentelemetry
- Data model: https://langfuse.com/docs/observability/data-model
operationId: opentelemetry_exportTraces
tags:
- Opentelemetry
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OtelTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
resourceSpans:
type: array
items:
$ref: '#/components/schemas/OtelResourceSpan'
description: >-
Array of resource spans containing trace data as defined in
the OTLP specification
required:
- resourceSpans
/api/public/organizations/memberships:
get:
description: >-
Get all memberships for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationMemberships
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
put:
description: >-
Create or update a membership for the organization associated with the
API key (requires organization-scoped API key)
operationId: organizations_updateOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_deleteOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/projects/{projectId}/memberships:
get:
description: >-
Get all memberships for a specific project (requires organization-scoped
API key)
operationId: organizations_getProjectMemberships
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
put:
description: >-
Create or update a membership for a specific project (requires
organization-scoped API key). The user must already be a member of the
organization.
operationId: organizations_updateProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from a specific project (requires
organization-scoped API key). The user must be a member of the
organization.
operationId: organizations_deleteProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/organizations/projects:
get:
description: >-
Get all projects for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationProjects
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationProjectsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/organizations/apiKeys:
get:
description: >-
Get all API keys for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationApiKeys
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationApiKeysResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/projects:
get:
description: >-
Get Project associated with API key (requires project-scoped API key).
You can use GET /api/public/organizations/projects to get all projects
with an organization-scoped key.
operationId: projects_get
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Projects'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: Create a new project (requires organization-scoped API key)
operationId: projects_create
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
description: >-
Number of days to retain data. Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional.
required:
- name
- retention
/api/public/projects/{projectId}:
put:
description: Update a project by ID (requires organization-scoped API key).
operationId: projects_update
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
nullable: true
description: |-
Number of days to retain data.
Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional. Will retain existing retention setting if omitted.
required:
- name
delete:
description: >-
Delete a project by ID (requires organization-scoped API key). Project
deletion is processed asynchronously.
operationId: projects_delete
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'202':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/projects/{projectId}/apiKeys:
get:
description: Get all API keys for a project (requires organization-scoped API key)
operationId: projects_getApiKeys
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyList'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: >-
Create a new API key for a project (requires organization-scoped API key)
operationId: projects_createApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
nullable: true
description: Optional note for the API key
publicKey:
type: string
nullable: true
description: >-
Optional predefined public key. Must start with 'pk-lf-'. If
provided, secretKey must also be provided.
secretKey:
type: string
nullable: true
description: >-
Optional predefined secret key. Must start with 'sk-lf-'. If
provided, publicKey must also be provided.
/api/public/projects/{projectId}/apiKeys/{apiKeyId}:
delete:
description: Delete an API key for a project (requires organization-scoped API key)
operationId: projects_deleteApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
- name: apiKeyId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/v2/prompts/{name}/versions/{version}:
patch:
description: Update labels for a specific prompt version
operationId: promptVersion_update
tags:
- PromptVersion
parameters:
- name: name
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: path
description: Version of the prompt to update
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
newLabels:
type: array
items:
type: string
description: >-
New labels for the prompt version. Labels are unique across
versions. The "latest" label is reserved and managed by
Langfuse.
required:
- newLabels
/api/public/v2/prompts/{promptName}:
get:
description: Get a prompt
operationId: prompts_get
tags:
- Prompts
parameters:
- name: promptName
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: query
description: Version of the prompt to be retrieved.
required: false
schema:
type: integer
nullable: true
- name: label
in: query
description: >-
Label of the prompt to be retrieved. Defaults to "production" if no
label or version is set.
required: false
schema:
type: string
nullable: true
- name: resolve
in: query
description: >-
Resolve prompt dependencies before returning the prompt. Defaults to
`true`. Set to `false` to return the raw stored prompt with
dependency tags intact. This bypasses prompt caching and is intended
for debugging or one-off jobs, not production runtime fetches.
required: false
schema:
type: boolean
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
delete:
description: >-
Delete prompt versions. If neither version nor label is specified, all
versions of the prompt are deleted.
operationId: prompts_delete
tags:
- Prompts
parameters:
- name: promptName
in: path
description: The name of the prompt
required: true
schema:
type: string
- name: label
in: query
description: >-
Optional label to filter deletion. If specified, deletes all prompt
versions that have this label.
required: false
schema:
type: string
nullable: true
- name: version
in: query
description: >-
Optional version to filter deletion. If specified, deletes only this
specific version of the prompt.
required: false
schema:
type: integer
nullable: true
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/v2/prompts:
get:
description: Get a list of prompt names with versions and labels
operationId: prompts_list
tags:
- Prompts
parameters:
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: label
in: query
required: false
schema:
type: string
nullable: true
- name: tag
in: query
required: false
schema:
type: string
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
- name: fromUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated on
or after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated
before a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions, combined with
AND.
When provided, this takes precedence over name, version,
label, tag, fromUpdatedAt, and toUpdatedAt. An empty array applies
no
filters. Project scoping and pagination always apply.
Each condition requires `type`, `column`, `operator`, and `value`.
Supported types and columns:
- `string`: `id`, `name`, `type`. Operators: `=`, `contains`, `does
not contain`, `starts with`, `ends with`, `is not empty`.
- `stringOptions`: `id`, `name`, `type`. Operators: `any of`, `none
of`. Value: non-empty string array.
- `number`: `version`. Operators: `=`, `>`, `<`, `>=`, `<=`. Value:
number.
- `datetime`: `createdAt`, `updatedAt`. Operators: `>`, `<`, `>=`,
`<=`. Value: ISO 8601 timestamp.
- `arrayOptions`: `labels`, `tags`. Operators: `any of`, `all of`,
`none of`. Value: non-empty string array.
- `stringObject`: `config`. Requires an additional `key` field.
Operators: `=`, `contains`, `does not contain`, `starts with`, `ends
with`, `is set`, `is not set`. Value: string (use an empty string
for key-presence operators).
String equality is case-sensitive. String search operators use
case-insensitive SQL pattern matching: `%` matches any sequence and
`_` matches a single character. A backslash escapes these
characters;
JSON-escape the backslash in the filter value. Asterisks are
literal.
For config, an empty search value is treated as `is set`.
Filters apply to prompt versions before aggregation: returned
versions,
labels, and lastConfig reflect only matching versions.
Example: [{"type":"string","column":"name","operator":"starts
with","value":"tools/"},{"type":"string","column":"name","operator":"ends
with","value":"/description"}]
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PromptMetaListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: Create a new version for the prompt with the given `name`
operationId: prompts_create
tags:
- Prompts
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePromptRequest'
/api/public/scim/ServiceProviderConfig:
get:
description: >-
Get SCIM Service Provider Configuration (requires organization-scoped
API key)
operationId: scim_getServiceProviderConfig
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceProviderConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/scim/ResourceTypes:
get:
description: Get SCIM Resource Types (requires organization-scoped API key)
operationId: scim_getResourceTypes
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceTypesResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/scim/Schemas:
get:
description: Get SCIM Schemas (requires organization-scoped API key)
operationId: scim_getSchemas
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SchemasResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/scim/Users:
get:
description: List users in the organization (requires organization-scoped API key)
operationId: scim_listUsers
tags:
- Scim
parameters:
- name: filter
in: query
description: Filter expression (e.g. userName eq "value")
required: false
schema:
type: string
nullable: true
- name: startIndex
in: query
description: 1-based index of the first result to return (default 1)
required: false
schema:
type: integer
nullable: true
- name: count
in: query
description: Maximum number of results to return (default 100)
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUsersListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: >-
Create a new user in the organization (requires organization-scoped API
key)
operationId: scim_createUser
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userName:
type: string
description: User's email address (required)
name:
$ref: '#/components/schemas/ScimName'
description: User's name information
emails:
type: array
items:
$ref: '#/components/schemas/ScimEmail'
nullable: true
description: User's email addresses
active:
type: boolean
nullable: true
description: Whether the user is active
password:
type: string
nullable: true
description: >-
Ignored. Accepted only for compatibility with identity
providers that always send a password on user creation (Okta
sends a placeholder value even when password sync is
disabled). No credential is created for the user;
provisioned users authenticate via SSO or set a password
themselves through the password reset flow.
required:
- userName
- name
/api/public/scim/Users/{userId}:
get:
description: Get a specific user by ID (requires organization-scoped API key)
operationId: scim_getUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
delete:
description: >-
Remove a user from the organization (requires organization-scoped API
key). Note that this only removes the user from the organization but
does not delete the user entity itself.
operationId: scim_deleteUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/score-configs:
post:
description: >-
Create a score configuration (config). Score configs are used to define
the structure of scores
operationId: scoreConfigs_create
tags:
- ScoreConfigs
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreConfigRequest'
get:
description: Get all score configs
operationId: scoreConfigs_get
tags:
- ScoreConfigs
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfigs'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/score-configs/{configId}:
get:
description: Get a score config
operationId: scoreConfigs_get-by-id
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
patch:
description: Update a score config
operationId: scoreConfigs_update
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScoreConfigRequest'
/api/public/v3/scores:
get:
description: |-
Get a list of scores with a polymorphic `value` field (v3).
The `value` field type depends on `dataType`:
- `NUMERIC` → number
- `BOOLEAN` → boolean
- `CATEGORICAL`, `TEXT`, `CORRECTION` → string
The response always includes the core fields: id, projectId, name,
value, dataType, source, timestamp, environment, createdAt, updatedAt.
Additional field groups can be requested via the `fields` parameter:
- `details` — adds comment, configId, metadata
- `subject` — adds the subject object describing the entity the score
is attached to: kind (trace, observation, session, or experiment),
id, and traceId for observation-level scores
- `annotation` — adds authorUserId, queueId
Unknown group names return HTTP 400.
operationId: scoresV3_getManyV3
tags:
- ScoresV3
parameters:
- name: limit
in: query
description: >-
Number of items per page. Maximum 100, default 50. Requests with a
limit greater than 100 return HTTP 400.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: >-
URL-safe base64 (base64url) cursor for pagination. Use the cursor
from the previous response to get the next page. Absent on the final
page.
required: false
schema:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated field groups to include in addition to the
always-returned core fields. Allowed: details, subject, annotation —
see the endpoint description for the fields each group adds. Unknown
names return HTTP 400.
required: false
schema:
type: string
nullable: true
- name: id
in: query
description: >-
Comma-separated list of score IDs to filter by (OR within, AND
across filters).
required: false
schema:
type: string
nullable: true
- name: name
in: query
description: Comma-separated list of score names to filter by.
required: false
schema:
type: string
nullable: true
- name: source
in: query
description: >-
Comma-separated list of score sources to filter by (e.g. API,
ANNOTATION, EVAL). Case-insensitive — `api` and `API` are
equivalent.
required: false
schema:
type: string
nullable: true
- name: dataType
in: query
description: >-
Comma-separated list of data types to filter by (NUMERIC, BOOLEAN,
CATEGORICAL, TEXT, CORRECTION). Case-insensitive — `numeric` and
`NUMERIC` are equivalent. Must be a single value when used with
value, valueMin, or valueMax; otherwise the request returns HTTP
400. Must be NUMERIC when used with valueMin or valueMax.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: Comma-separated list of environments to filter by.
required: false
schema:
type: string
nullable: true
- name: configId
in: query
description: Comma-separated list of score config IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: queueId
in: query
description: Comma-separated list of annotation queue IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: authorUserId
in: query
description: Comma-separated list of author user IDs to filter by.
required: false
schema:
type: string
nullable: true
- name: value
in: query
description: >-
Comma-separated list of exact values to filter by. Requires a single
dataType from NUMERIC, BOOLEAN, or CATEGORICAL; any other dataType,
multiple dataTypes, or omitting dataType returns HTTP 400. For
BOOLEAN, each value must be "true" or "false"; for NUMERIC, each
value must be a finite number. Otherwise the request returns HTTP
400.
required: false
schema:
type: string
nullable: true
- name: valueMin
in: query
description: >-
Inclusive lower bound on the numeric value. Requires
dataType=NUMERIC as a single value; otherwise the request returns
HTTP 400.
required: false
schema:
type: number
format: double
nullable: true
- name: valueMax
in: query
description: >-
Inclusive upper bound on the numeric value. Requires
dataType=NUMERIC as a single value; otherwise the request returns
HTTP 400.
required: false
schema:
type: number
format: double
nullable: true
- name: traceId
in: query
description: >-
Comma-separated list of trace IDs to filter by. Mutually exclusive
with sessionId, experimentId. May be combined with observationId to
scope the observation lookup to a specific trace.
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
description: >-
Comma-separated list of session IDs to filter by. Mutually exclusive
with traceId, observationId, experimentId.
required: false
schema:
type: string
nullable: true
- name: observationId
in: query
description: >-
Comma-separated list of observation IDs to filter by. Requires
traceId to be specified, because observation IDs are scoped to a
trace. Mutually exclusive with sessionId, experimentId. Returns HTTP
400 when used without traceId.
required: false
schema:
type: string
nullable: true
- name: experimentId
in: query
description: >-
Comma-separated list of dataset run IDs (experiment IDs) to filter
by. Mutually exclusive with traceId, sessionId, observationId.
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: Inclusive lower bound on the score timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: Exclusive upper bound on the score timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetScoresV3Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/scores:
post:
description: >-
Create a score (supports trace, observation, session, and dataset run
scores)
operationId: scores_create
tags:
- Scores
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreRequest'
/api/public/v2/scores:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. Use `GET
/api/public/v3/scores` instead. Self-hosted deployments are unaffected
by this date; the endpoint becomes unavailable when they upgrade to
Langfuse v4. See the [Langfuse v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
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, is set, is not set. Use is set / is not set to
filter on metadata key presence. An empty value for contains, starts
with, or ends with is treated as is set (key presence).
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetScoresResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/v2/scores/{scoreId}:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. Use `GET
/api/public/v3/scores` with the `id` filter instead. Self-hosted
deployments are unaffected by this date; the endpoint becomes
unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4
upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get a score (supports both trace and session scores)
operationId: scores_get-by-id
tags:
- Scores
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Score'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/sessions:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, read
session data via `GET /api/public/v2/observations?filter=<urlencoded
sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted
deployments are unaffected by this date; the endpoint becomes
unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4
upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get sessions.
This legacy endpoint is not recommended for new data extraction
workflows.
Use the v2 observations endpoint with a bounded time range and group
rows by
`sessionId` instead:
`GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
operationId: sessions_list
tags:
- Sessions
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include sessions created on or after a
certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include sessions created before a certain
datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: environment
in: query
description: >-
Optional filter for sessions where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSessions'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/sessions/{sessionId}:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, read
session data via `GET /api/public/v2/observations?filter=<urlencoded
sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted
deployments are unaffected by this date; the endpoint becomes
unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4
upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get a session.
Please note that `traces` on this endpoint are not paginated. For large
sessions or new data extraction workflows, use the v2 observations
endpoint
with a URL-encoded `sessionId` filter and a bounded time range:
`GET /api/public/v2/observations?filter=<sessionId
filter>&fromStartTime=<from>&toStartTime=<to>`.
operationId: sessions_get
tags:
- Sessions
parameters:
- name: sessionId
in: path
description: The unique id of a session
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SessionWithTraces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
/api/public/traces/{traceId}:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, read span
and trace data via `GET
/api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
Self-hosted deployments are unaffected by this date; the endpoint
becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse
v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get a specific trace
operationId: trace_get
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of a trace
required: true
schema:
type: string
- name: fields
in: query
description: >-
Comma-separated list of fields to include in the response. Available
field groups: 'core' (always included), 'io' (input, output,
metadata), 'scores', 'observations', 'metrics'. If not specified,
all fields are returned. Example: 'core,scores,metrics'. Note:
Excluded 'observations' or 'scores' fields return empty arrays;
excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWithFullDetails'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
delete:
description: Delete a specific trace
operationId: trace_delete
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of the trace to delete
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/traces:
get:
description: >-
**Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this
endpoint will be removed on November 16, 2026. In Langfuse v4, read span
and trace data via `GET
/api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.
Self-hosted deployments are unaffected by this date; the endpoint
becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse
v3 to v4 upgrade
guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).
Get list of traces
operationId: trace_list
tags:
- Trace
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp on or
after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp before
a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: orderBy
in: query
description: >-
Format of the string [field].[asc/desc]. Fields: id, timestamp,
name, userId, release, version, public, bookmarked, sessionId.
Example: timestamp.asc
required: false
schema:
type: string
nullable: true
- name: tags
in: query
description: Only traces that include all of these tags will be returned.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: version
in: query
description: Optional filter to only include traces with a certain version.
required: false
schema:
type: string
nullable: true
- name: release
in: query
description: Optional filter to only include traces with a certain release.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for traces where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated list of fields to include in the response. Available
field groups: 'core' (always included), 'io' (input, output,
metadata), 'scores', 'observations', 'metrics'. If not specified,
all fields are returned. Example: 'core,scores,metrics'. Note:
Excluded 'observations' or 'scores' fields return empty arrays;
excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
sessionId, tags, version, release, environment, fromTimestamp,
toTimestamp).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "booleanObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
// - numberObject: "=", ">", "<", ">=", "<="
// - booleanObject: "=", "<>"
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, booleanObject, and categoryOptions types when filtering on nested fields like metadata or score names
}
]
```
## Available Columns
### Core Trace Fields
- `id` (string) - Trace ID
- `name` (string) - Trace name
- `timestamp` (datetime) - Trace timestamp
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
- `environment` (string) - Environment tag
- `version` (string) - Version tag
- `release` (string) - Release tag
- `tags` (arrayOptions) - Array of tags
- `bookmarked` (boolean) - Bookmark status
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Aggregated Metrics (from observations)
These metrics are aggregated from all observations within the trace:
- `latency` (number) - Latency in seconds (time from first
observation start to last observation end)
- `inputTokens` (number) - Total input tokens across all
observations
- `outputTokens` (number) - Total output tokens across all
observations
- `totalTokens` (number) - Total tokens (alias: `tokens`)
- `inputCost` (number) - Total input cost in USD
- `outputCost` (number) - Total output cost in USD
- `totalCost` (number) - Total cost in USD
### Observation Level Aggregations
These fields aggregate observation levels within the trace:
- `level` (string) - Highest severity level (ERROR > WARNING >
DEFAULT > DEBUG)
- `warningCount` (number) - Count of WARNING level observations
- `errorCount` (number) - Count of ERROR level observations
- `defaultCount` (number) - Count of DEFAULT level observations
- `debugCount` (number) - Count of DEBUG level observations
### Scores (requires join with scores table)
- `scores_avg` (number) - Average of numeric scores (alias:
`scores`)
- `score_categories` (categoryOptions) - Categorical score values
- `score_booleans` (booleanObject) - Boolean score values. Use `key`
for the score name and a boolean `value`, e.g. `{"type":
"booleanObject", "column": "score_booleans", "key": "is_correct",
"operator": "=", "value": true}`. The `<>` operator also matches
traces without a score of that name.
## Filter Examples
```json
[
{
"type": "datetime",
"column": "timestamp",
"operator": ">=",
"value": "2024-01-01T00:00:00Z"
},
{
"type": "string",
"column": "userId",
"operator": "=",
"value": "user-123"
},
{
"type": "number",
"column": "totalCost",
"operator": ">=",
"value": 0.01
},
{
"type": "arrayOptions",
"column": "tags",
"operator": "all of",
"value": ["production", "critical"]
},
{
"type": "stringObject",
"column": "metadata",
"key": "customer_tier",
"operator": "=",
"value": "enterprise"
}
]
```
## Performance Notes
- Filtering on `userId`, `sessionId`, or `metadata` may enable skip
indexes for better query performance
- Score filters require a join with the scores table and may impact
query performance
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Traces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
deprecated: true
delete:
description: Delete multiple traces
operationId: trace_deleteMultiple
tags:
- Trace
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
traceIds:
type: array
items:
type: string
description: List of trace IDs to delete
required:
- traceIds
/api/public/unstable/dashboard-widgets:
get:
description: |-
List dashboard widgets in the project, ordered by most recently
updated first.
Responses may include legacy `traces` widgets created before this
API existed. New widgets cannot be created with `view: traces`.
operationId: unstable_dashboardWidgets_list
tags:
- UnstableDashboardWidgets
parameters:
- name: page
in: query
description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidgetList'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
post:
description: >-
Create a dashboard widget (a standalone chart definition you place on
any dashboard).
This endpoint creates the widget only; place it on a dashboard via
`POST /dashboards/{dashboardId}/placements`.
Supported views are `observations`, `scores-numeric`, `scores-boolean`,
and `scores-categorical`.
The legacy `traces` view is not supported by this unstable API.
Widgets are created as v2 internally.
`chartConfig` is optional and defaults to the plain config for
`chartType`; when `chartConfig.type` is given it must match
`chartType`.
Unstable API note:
- This surface may evolve while dashboard/widget APIs are being
finalized.
operationId: unstable_dashboardWidgets_create
tags:
- UnstableDashboardWidgets
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'
/api/public/unstable/dashboard-widgets/{widgetId}:
get:
description: |-
Get a dashboard widget by id.
The response may use `view: traces` for legacy widgets.
operationId: unstable_dashboardWidgets_get
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
patch:
description: |-
Update a dashboard widget.
All fields are optional; at least one field is required.
Changing `chartType` without sending `chartConfig` resets the config
to the new chart type's defaults. When `chartConfig.type` is given
it must match the widget's (possibly updated) `chartType`.
`view` cannot be changed to the legacy `traces` value. Existing
`traces` widgets may be updated on other fields.
operationId: unstable_dashboardWidgets_update
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardWidget'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest'
delete:
description: |-
Delete a dashboard widget.
The API returns `409` while the widget is still placed on a dashboard.
Remove those placements first.
operationId: unstable_dashboardWidgets_delete
tags:
- UnstableDashboardWidgets
parameters:
- name: widgetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
/api/public/unstable/dashboards:
get:
description: |-
List dashboards in the project, ordered by most recently updated
first.
operationId: unstable_dashboards_list
tags:
- UnstableDashboards
parameters:
- name: page
in: query
description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardList'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
post:
description: Create a dashboard.
operationId: unstable_dashboards_create
tags:
- UnstableDashboards
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardRequest'
/api/public/unstable/dashboards/{dashboardId}:
get:
description: Get a dashboard by id.
operationId: unstable_dashboards_get
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
patch:
description: Update a dashboard's name, description, definition, or filters.
operationId: unstable_dashboards_update
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboard'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardRequest'
delete:
description: Delete a dashboard.
operationId: unstable_dashboards_delete
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
/api/public/unstable/dashboards/{dashboardId}/placements:
post:
description: |-
Add a placement to a dashboard grid (see `DashboardPlacement` for
grid semantics).
`id` and the position fields are optional: when omitted, the
placement gets a server-generated id and is appended below all
existing tiles as a 6x6 tile. Returns the created placement.
The referenced widget must exist in the same project or be a
Langfuse-managed widget. The API returns `409` if a placement with
the same `id` already exists on the dashboard.
operationId: unstable_dashboards_addPlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardPlacement'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateDashboardPlacementRequest'
/api/public/unstable/dashboards/{dashboardId}/placements/{placementId}:
patch:
description: |-
Move or resize a placement. All fields are optional; at least one is
required. Omitted fields keep their current value. The placement's
content (widget/preset reference) and id cannot change — delete and
re-add the placement to swap content. Returns the updated placement.
operationId: unstable_dashboards_updatePlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
- name: placementId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDashboardPlacement'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'
delete:
description: >-
Remove a placement from a dashboard grid without deleting the referenced
widget.
operationId: unstable_dashboards_deletePlacement
tags:
- UnstableDashboards
parameters:
- name: dashboardId
in: path
required: true
schema:
type: string
- name: placementId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'429':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstablePublicApiError'
security: *ref_0
/api/public/unstable/skills:
get:
description: >-
List skills with metadata and timestamps from their latest version,
shared tags, and the version assigned to production when present.
operationId: unstable_skills_list
tags:
- UnstableSkills
parameters:
- name: name
in: query
description: Filter by exact skill name.
required: false
schema:
type: string
nullable: true
- name: search
in: query
description: >-
Case-insensitive search across skill names and latest-version
descriptions.
required: false
schema:
type: string
nullable: true
- name: tag
in: query
description: Filter by a shared skill tag.
required: false
schema:
type: string
nullable: true
- name: page
in: query
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
required: false
schema:
type: integer
nullable: true
- name: fromUpdatedAt
in: query
description: >-
Include skills whose latest version was updated at or after this
timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
- name: toUpdatedAt
in: query
description: >-
Include skills whose latest version was updated before this
timestamp.
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillMetaListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
post:
description: Create skill version
operationId: unstable_skills_createVersion
tags:
- UnstableSkills
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableCreateSkillVersionRequest'
/api/public/unstable/skills/{skillName}:
get:
description: >-
Resolve a skill's metadata and file manifest by version or label.
Defaults to the production label. Use each file's sha256Hash with
getFileContents, individually or in batches across manifests.
operationId: unstable_skills_get
tags:
- UnstableSkills
parameters:
- name: skillName
in: path
required: true
schema:
type: string
- name: version
in: query
required: false
schema:
type: integer
nullable: true
- name: label
in: query
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
patch:
description: >-
Replace the shared tags across all versions of a skill. An empty tags
list clears all tags. Returns the latest skill version with the updated
tags.
operationId: unstable_skills_update
tags:
- UnstableSkills
parameters:
- name: skillName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateSkillRequest'
/api/public/unstable/skills/files/content:
get:
description: >-
Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
operationId: unstable_skills_getFileContents
tags:
- UnstableSkills
parameters:
- name: sha256Hashes
in: query
description: >-
Comma-separated list of one to 50 canonical base64-encoded SHA-256
hashes from skill file manifests. URL-encode the value, including +,
/, and = characters.
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillFileContentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/unstable/skills/{skillName}/versions/{skillVersion}:
patch:
description: >-
Replace the labels on a skill version and atomically move them from
other versions.
operationId: unstable_skills_setLabels
tags:
- UnstableSkills
parameters:
- name: skillName
in: path
required: true
schema:
type: string
- name: skillVersion
in: path
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableSkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/unstableUpdateSkillLabelsRequest'
delete:
description: >-
Delete one immutable skill version. Unreferenced blobs are retained for
asynchronous cleanup.
operationId: unstable_skills_deleteVersion
tags:
- UnstableSkills
parameters:
- name: skillName
in: path
required: true
schema:
type: string
- name: skillVersion
in: path
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableDeleteSkillVersionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
components:
schemas:
AnnotationQueueStatus:
title: AnnotationQueueStatus
type: string
enum:
- PENDING
- COMPLETED
AnnotationQueueObjectType:
title: AnnotationQueueObjectType
type: string
enum:
- TRACE
- OBSERVATION
- SESSION
AnnotationQueue:
title: AnnotationQueue
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- description
- scoreConfigIds
- createdAt
- updatedAt
AnnotationQueueItem:
title: AnnotationQueueItem
type: object
properties:
id:
type: string
queueId:
type: string
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
completedAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- queueId
- objectId
- objectType
- status
- createdAt
- updatedAt
PaginatedAnnotationQueues:
title: PaginatedAnnotationQueues
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueue'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PaginatedAnnotationQueueItems:
title: PaginatedAnnotationQueueItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueueItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateAnnotationQueueRequest:
title: CreateAnnotationQueueRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
required:
- name
- scoreConfigIds
CreateAnnotationQueueItemRequest:
title: CreateAnnotationQueueItemRequest
type: object
properties:
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
description: Defaults to PENDING for new queue items
required:
- objectId
- objectType
UpdateAnnotationQueueItemRequest:
title: UpdateAnnotationQueueItemRequest
type: object
properties:
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
DeleteAnnotationQueueItemResponse:
title: DeleteAnnotationQueueItemResponse
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
AnnotationQueueAssignmentRequest:
title: AnnotationQueueAssignmentRequest
type: object
properties:
userId:
type: string
required:
- userId
DeleteAnnotationQueueAssignmentResponse:
title: DeleteAnnotationQueueAssignmentResponse
type: object
properties:
success:
type: boolean
required:
- success
CreateAnnotationQueueAssignmentResponse:
title: CreateAnnotationQueueAssignmentResponse
type: object
properties:
userId:
type: string
queueId:
type: string
projectId:
type: string
required:
- userId
- queueId
- projectId
BlobStorageIntegrationType:
title: BlobStorageIntegrationType
type: string
enum:
- S3
- S3_COMPATIBLE
- AZURE_BLOB_STORAGE
BlobStorageIntegrationFileType:
title: BlobStorageIntegrationFileType
type: string
enum:
- JSON
- CSV
- JSONL
- PARQUET
description: >-
File format for exported data. `PARQUET` is a columnar binary format
encoded and compressed by the storage engine; gzip compression does not
apply to it. Note that the model-price columns (`input_price`,
`output_price`, `total_price`) are not included in Parquet observation
exports.
BlobStorageIntegrationFileTypeResponse:
title: BlobStorageIntegrationFileTypeResponse
type: string
enum:
- JSON
- CSV
- JSONL
- PARQUET
description: File type reported for an existing integration.
BlobStorageExportMode:
title: BlobStorageExportMode
type: string
enum:
- FULL_HISTORY
- FROM_TODAY
- FROM_CUSTOM_DATE
BlobStorageExportFrequency:
title: BlobStorageExportFrequency
type: string
enum:
- every_20_minutes
- hourly
- daily
- weekly
BlobStorageExportSource:
title: BlobStorageExportSource
type: string
enum:
- LEGACY_TRACES_OBSERVATIONS
- OBSERVATIONS_V2
- LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS
description: >-
What data the integration exports.
- `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables.
Observation columns are controlled by `exportFieldGroups`; field groups
without a counterpart in this data model (e.g. `trace_context`) are
omitted.
- `OBSERVATIONS_V2`: same data model as the
`/api/public/v2/observations` endpoint, plus scores. Columns are
controlled by `exportFieldGroups`.
- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation
columns of both portions are controlled by `exportFieldGroups`.
**Note:** which sources a deployment accepts depends on how far it has
moved to the v4 data model. `OBSERVATIONS_V2` and the
enriched-observations portion of
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations
table, so they require a deployment that already populates it.
`LEGACY_TRACES_OBSERVATIONS` and the legacy portion of
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and
observations tables, so they require a deployment that still populates
those. A deployment part-way through the migration populates both and
accepts every source. Selecting a source the deployment cannot serve is
rejected with `400`, rather than exporting an empty result. See
https://langfuse.com/docs/v4.
BlobStorageExportFieldGroup:
title: BlobStorageExportFieldGroup
type: string
enum:
- core
- basic
- time
- io
- metadata
- model
- usage
- prompt
- metrics
- tools
- trace_context
description: >-
Field group selecting which observation columns are included in the
export. Applies to all export sources; groups without a counterpart in
the legacy data model (e.g. `trace_context`) are omitted from the legacy
observations export.
CreateBlobStorageIntegrationRequest:
title: CreateBlobStorageIntegrationRequest
type: object
properties:
projectId:
type: string
description: ID of the project in which to configure the blob storage integration
type:
$ref: '#/components/schemas/BlobStorageIntegrationType'
bucketName:
type: string
description: >-
Name of the storage bucket. For AZURE_BLOB_STORAGE, must be a valid
Azure container name (3-63 chars, lowercase letters, numbers, and
hyphens only, must start and end with a letter or number, no
consecutive hyphens).
endpoint:
type: string
nullable: true
description: Custom endpoint URL (required for S3_COMPATIBLE type)
region:
type: string
description: >-
Storage region used by S3-compatible clients (AWS, GCS, Cloudflare
R2, MinIO, Azure location IDs such as eastus, OCI). Leading and
trailing whitespace is removed. The remaining value must be 1-63
letters, numbers, or hyphens, and cannot start or end with a hyphen.
Examples: us-east-1, europe-west1, eastus, auto.
accessKeyId:
type: string
nullable: true
description: Access key ID for authentication
secretAccessKey:
type: string
nullable: true
description: Secret access key for authentication (will be encrypted when stored)
prefix:
type: string
nullable: true
description: >-
Path prefix for exported files (must end with forward slash if
provided)
exportFrequency:
$ref: '#/components/schemas/BlobStorageExportFrequency'
enabled:
type: boolean
description: Whether the integration is active
forcePathStyle:
type: boolean
description: Use path-style URLs for S3 requests
fileType:
$ref: '#/components/schemas/BlobStorageIntegrationFileType'
exportMode:
$ref: '#/components/schemas/BlobStorageExportMode'
exportStartDate:
type: string
format: date-time
nullable: true
description: >-
Custom start date for exports (required when exportMode is
FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for
timezone differences).
compressed:
type: boolean
nullable: true
description: >-
Enable gzip compression for exported files (.csv.gz, .json.gz,
.jsonl.gz). Defaults to true.
exportSource:
$ref: '#/components/schemas/BlobStorageExportSource'
nullable: true
description: >-
Data to export. When omitted on update, the existing value is
preserved. When omitted on create, the default is `OBSERVATIONS_V2`
on Langfuse Cloud, and on self-hosted deployments
`LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the
deployment no longer populates the legacy tables. The default is
never a source the deployment cannot serve. Required when
`exportFieldGroups` is provided.
**Cloud-only project deprecation gate (effective 2026-05-20):** For
projects created on or after 2026-05-20 on Langfuse Cloud,
`LEGACY_TRACES_OBSERVATIONS` and
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted
deployments are unaffected.
**Cloud-only integration deprecation gate (effective 2026-06-22):**
On Langfuse Cloud, legacy export sources are only accepted for blob
storage integrations created before 2026-06-22, regardless of
project age. Requests that would create a new integration with
`LEGACY_TRACES_OBSERVATIONS` or
`LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP
400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are
unaffected.
exportFieldGroups:
type: array
items:
$ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
Field groups to include in each exported observation row. Applies to
all export sources; must include `core` if provided. When omitted on
create, the column default (all groups) applies. When omitted on
update, the existing value is preserved.
`exportFieldGroups` requires `exportSource` to be provided in the
same request.
required:
- projectId
- type
- bucketName
- region
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
BlobStorageIntegrationResponse:
title: BlobStorageIntegrationResponse
type: object
properties:
id:
type: string
projectId:
type: string
type:
$ref: '#/components/schemas/BlobStorageIntegrationType'
bucketName:
type: string
endpoint:
type: string
nullable: true
region:
type: string
accessKeyId:
type: string
nullable: true
prefix:
type: string
exportFrequency:
$ref: '#/components/schemas/BlobStorageExportFrequency'
enabled:
type: boolean
forcePathStyle:
type: boolean
fileType:
$ref: '#/components/schemas/BlobStorageIntegrationFileTypeResponse'
exportMode:
$ref: '#/components/schemas/BlobStorageExportMode'
exportStartDate:
type: string
format: date-time
nullable: true
compressed:
type: boolean
exportSource:
$ref: '#/components/schemas/BlobStorageExportSource'
exportFieldGroups:
type: array
items:
$ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
Field groups included in each exported observation row. An empty
list is treated as all groups during export.
nextSyncAt:
type: string
format: date-time
nullable: true
lastSyncAt:
type: string
format: date-time
nullable: true
lastError:
type: string
nullable: true
lastErrorAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- projectId
- type
- bucketName
- endpoint
- region
- accessKeyId
- prefix
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
- exportStartDate
- compressed
- exportSource
- exportFieldGroups
- nextSyncAt
- lastSyncAt
- lastError
- lastErrorAt
- createdAt
- updatedAt
BlobStorageIntegrationsResponse:
title: BlobStorageIntegrationsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
required:
- data
BlobStorageSyncStatus:
title: BlobStorageSyncStatus
type: string
enum:
- idle
- running
- queued
- up_to_date
- disabled
- error
description: >-
Sync status of the blob storage integration:
- `disabled` — integration is not enabled
- `error` — last export failed (see `lastError` for details)
- `running` — an export job is currently being processed
- `queued` — next export is overdue (`nextSyncAt` is in the past) and
waiting to be picked up by the worker
- `idle` — enabled but has never exported yet and no export is queued
- `up_to_date` — all available data has been exported; next export is
scheduled for the future
**ETL usage**: poll this endpoint and check for `up_to_date` status.
Compare `lastSyncAt` against your
ETL bookmark to determine if new data is available. Note that exports
run with a 20-minute lag buffer,
so `lastSyncAt` will always be at least 20 minutes behind real-time.
BlobStorageIntegrationStatusResponse:
title: BlobStorageIntegrationStatusResponse
type: object
properties:
id:
type: string
projectId:
type: string
syncStatus:
$ref: '#/components/schemas/BlobStorageSyncStatus'
enabled:
type: boolean
lastSyncAt:
type: string
format: date-time
nullable: true
description: >-
End of the last successfully exported time window. Compare against
your ETL bookmark to determine if new data is available. Null if the
integration has never synced.
nextSyncAt:
type: string
format: date-time
nullable: true
description: When the next export is scheduled. Null if no sync has occurred yet.
lastError:
type: string
nullable: true
description: >-
Raw error message from the storage provider (S3/Azure/GCS) if the
last export failed. Cleared on successful export.
lastErrorAt:
type: string
format: date-time
nullable: true
description: When the last error occurred. Cleared on successful export.
required:
- id
- projectId
- syncStatus
- enabled
- lastSyncAt
- nextSyncAt
- lastError
- lastErrorAt
BlobStorageIntegrationDeletionResponse:
title: BlobStorageIntegrationDeletionResponse
type: object
properties:
message:
type: string
required:
- message
CreateCommentRequest:
title: CreateCommentRequest
type: object
properties:
projectId:
type: string
description: The id of the project to attach the comment to.
objectType:
type: string
description: >-
The type of the object to attach the comment to (trace, observation,
session, prompt).
objectId:
type: string
description: >-
The id of the object to attach the comment to. If this does not
reference a valid existing object, an error will be thrown.
content:
type: string
description: >-
The content of the comment. May include markdown. Currently limited
to 5000 characters.
authorUserId:
type: string
nullable: true
description: >-
The id of the user who created the comment. Must be a member of the
organization that owns the project, otherwise an error will be
thrown.
objectStartTime:
type: string
format: date-time
nullable: true
description: >-
The start time of the referenced object (for observations, the
observation's start time). Optional performance hint - when
provided, Langfuse narrows the lookup to validate the reference
faster. It only affects speed - an incorrect or omitted value never
changes the result.
required:
- projectId
- objectType
- objectId
- content
CreateCommentResponse:
title: CreateCommentResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
GetCommentsResponse:
title: GetCommentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Deprecation:
title: Deprecation
type: object
description: >-
Migration signal returned by deprecated endpoints. Optional fields are
omitted when they have no value.
properties:
message:
type: string
description: >-
Human- and agent-readable summary of the deprecation and its
replacement.
replacement:
type: string
nullable: true
description: >-
The replacement endpoint, e.g. "GET /api/public/v2/observations".
Omitted when the endpoint is being removed without a direct
replacement.
docsUrl:
type: string
nullable: true
description: Link to the migration documentation (markdown), when available.
sunsetAt:
type: string
nullable: true
description: >-
ISO date after which the endpoint may stop working, when a removal
date is committed.
required:
- message
Trace:
title: Trace
type: object
properties:
id:
type: string
description: The unique identifier of a trace
timestamp:
type: string
format: date-time
description: The timestamp when the trace was created
name:
type: string
nullable: true
description: The name of the trace
input:
nullable: true
description: The input data of the trace. Can be any JSON.
output:
nullable: true
description: The output data of the trace. Can be any JSON.
sessionId:
type: string
nullable: true
description: The session identifier associated with the trace
release:
type: string
nullable: true
description: The release version of the application when the trace was created
version:
type: string
nullable: true
description: The version of the trace
userId:
type: string
nullable: true
description: The user identifier associated with the trace
metadata:
type: object
additionalProperties: true
nullable: true
description: >-
The metadata associated with the trace. Values can be any JSON;
non-object metadata sent at ingestion is returned under the
`metadata` key.
tags:
type: array
items:
type: string
description: The tags associated with the trace.
public:
type: boolean
description: Public traces are accessible via url without login
environment:
type: string
description: >-
The environment from which this trace originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- timestamp
- name
- sessionId
- release
- version
- userId
- tags
- public
- environment
TraceWithDetails:
title: TraceWithDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
type: string
nullable: true
description: List of observation ids
scores:
type: array
items:
type: string
nullable: true
description: List of score ids
required:
- htmlPath
allOf:
- $ref: '#/components/schemas/Trace'
TraceWithFullDetails:
title: TraceWithFullDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
description: List of observations
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV1'
description: List of scores
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- htmlPath
- observations
- scores
allOf:
- $ref: '#/components/schemas/Trace'
Session:
title: Session
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
projectId:
type: string
environment:
type: string
description: The environment from which this session originated.
required:
- id
- createdAt
- projectId
- environment
SessionWithTraces:
title: SessionWithTraces
type: object
properties:
traces:
type: array
items:
$ref: '#/components/schemas/Trace'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- traces
allOf:
- $ref: '#/components/schemas/Session'
Observation:
title: Observation
type: object
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
type:
type: string
description: The type of the observation
name:
type: string
nullable: true
description: The name of the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation.
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
model:
type: string
nullable: true
description: The model used for the observation
modelParameters:
description: The parameters of the model used for the observation
input:
description: The input data of the observation
version:
type: string
nullable: true
description: The version of the observation
metadata:
type: object
additionalProperties: true
description: Additional metadata of the observation
output:
description: The output data of the observation
usage:
$ref: '#/components/schemas/Usage'
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The usage
data of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
parentObservationId:
type: string
nullable: true
description: The parent observation ID
promptId:
type: string
nullable: true
description: The prompt ID associated with the observation
usageDetails:
type: object
additionalProperties:
type: integer
description: >-
The usage details of the observation. Key is the name of the usage
metric, value is the number of units consumed. The total key is the
sum of all (non-total) usage metrics or the total value ingested.
costDetails:
type: object
additionalProperties:
type: number
format: double
description: >-
The cost details of the observation. Key is the name of the cost
metric, value is the cost in USD. The total key is the sum of all
(non-total) cost metrics or the total value ingested.
environment:
type: string
description: >-
The environment from which this observation originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- traceId
- type
- name
- startTime
- endTime
- completionStartTime
- model
- modelParameters
- input
- version
- metadata
- output
- usage
- level
- statusMessage
- parentObservationId
- promptId
- usageDetails
- costDetails
- environment
ObservationsView:
title: ObservationsView
type: object
properties:
promptName:
type: string
nullable: true
description: The name of the prompt associated with the observation
promptVersion:
type: integer
nullable: true
description: The version of the prompt associated with the observation
modelId:
type: string
nullable: true
description: The unique identifier of the model
inputPrice:
type: number
format: double
nullable: true
description: The price of the input in USD
outputPrice:
type: number
format: double
nullable: true
description: The price of the output in USD.
totalPrice:
type: number
format: double
nullable: true
description: The total price in USD.
calculatedInputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the input in USD
calculatedOutputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the output in USD
calculatedTotalCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated total cost in USD
latency:
type: number
format: double
nullable: true
description: The latency in seconds.
timeToFirstToken:
type: number
format: double
nullable: true
description: The time to the first token in seconds
required:
- promptName
- promptVersion
- modelId
- inputPrice
- outputPrice
- totalPrice
- calculatedInputCost
- calculatedOutputCost
- calculatedTotalCost
- latency
- timeToFirstToken
allOf:
- $ref: '#/components/schemas/Observation'
ObservationsViewSingle:
title: ObservationsViewSingle
type: object
properties:
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
allOf:
- $ref: '#/components/schemas/ObservationsView'
ObservationV2:
title: ObservationV2
type: object
description: >-
An observation from the v2 API with field-group-based selection.
Core fields are always present. Other fields are included only when
their field group is requested.
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation
projectId:
type: string
description: The project ID this observation belongs to
parentObservationId:
type: string
nullable: true
description: >-
The physical parent observation ID, if present.
Observations marked as app roots by the SDK may retain a non-null
parent ID.
type:
type: string
description: The type of the observation (e.g. GENERATION, SPAN, EVENT)
isRootObservation:
type: boolean
nullable: true
description: >-
Whether this observation is a logical root.
This is true for observations without a physical parent and
observations marked as app roots by the SDK.
name:
type: string
nullable: true
description: The name of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
version:
type: string
nullable: true
description: The version of the observation
environment:
type: string
nullable: true
description: The environment from which this observation originated
bookmarked:
type: boolean
nullable: true
description: Whether the observation is bookmarked
public:
type: boolean
nullable: true
description: Whether the observation is public
userId:
type: string
nullable: true
description: The user ID associated with the observation
sessionId:
type: string
nullable: true
description: The session ID associated with the observation
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
createdAt:
type: string
format: date-time
nullable: true
description: The creation timestamp of the observation
updatedAt:
type: string
format: date-time
nullable: true
description: The last update timestamp of the observation
input:
nullable: true
description: The input data of the observation
output:
nullable: true
description: The output data of the observation
metadata:
type: object
additionalProperties: true
nullable: true
description: Additional metadata of the observation
model:
type: string
nullable: true
description: The model name as provided by the user
internalModelId:
type: string
nullable: true
description: The internal model ID matched by Langfuse
modelParameters:
nullable: true
description: The parameters of the model used for the observation
usageDetails:
type: object
additionalProperties:
type: integer
nullable: true
description: >-
The usage details of the observation. Key is the usage metric name,
value is the number of units consumed.
costDetails:
type: object
additionalProperties:
type: number
format: double
nullable: true
description: >-
The cost details of the observation. Key is the cost metric name,
value is the cost in USD.
totalCost:
type: number
format: double
nullable: true
description: The total cost of the observation in USD
usagePricingTierName:
type: string
nullable: true
description: >-
The name of the pricing tier applied to this observation's usage
costs
promptId:
type: string
nullable: true
description: The prompt ID associated with the observation
promptName:
type: string
nullable: true
description: The prompt name associated with the observation
promptVersion:
type: integer
nullable: true
description: The prompt version associated with the observation
latency:
type: number
format: double
nullable: true
description: The latency in seconds
timeToFirstToken:
type: number
format: double
nullable: true
description: The time to first token in seconds
modelId:
type: string
nullable: true
description: >-
The matched model ID. Null when the `model` field group is not
requested.
inputPrice:
type: string
nullable: true
description: >-
The input token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
outputPrice:
type: string
nullable: true
description: >-
The output token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
totalPrice:
type: string
nullable: true
description: >-
The total token price (USD per unit) from the matched model,
serialized as a decimal string (e.g. "0.0001"). Null when the
`model` field group is not requested.
traceName:
type: string
nullable: true
description: The name of the parent trace
tags:
type: array
items:
type: string
nullable: true
description: Tags from the parent trace (denormalized onto the observation)
release:
type: string
nullable: true
description: The release version of the parent trace
required:
- id
- traceId
- startTime
- endTime
- projectId
- parentObservationId
- type
- modelId
- inputPrice
- outputPrice
- totalPrice
Usage:
title: Usage
type: object
description: >-
(Deprecated. Use usageDetails and costDetails instead.) Standard
interface for usage and cost
properties:
input:
type: integer
description: Number of input units (e.g. tokens)
output:
type: integer
description: Number of output units (e.g. tokens)
total:
type: integer
description: Defaults to input+output if not set
unit:
type: string
nullable: true
description: Unit of measurement
inputCost:
type: number
format: double
nullable: true
description: USD input cost
outputCost:
type: number
format: double
nullable: true
description: USD output cost
totalCost:
type: number
format: double
nullable: true
description: USD total cost, defaults to input+output
required:
- input
- output
- total
- unit
ScoreConfig:
title: ScoreConfig
type: object
description: Configuration for a score
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
type: string
dataType:
$ref: '#/components/schemas/ScoreConfigDataType'
isArchived:
type: boolean
description: Whether the score config is archived. Defaults to false
minValue:
type: number
format: double
nullable: true
description: >-
Sets minimum value for numerical scores. If not set, the minimum
value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Sets maximum value for numerical scores. If not set, the maximum
value defaults to +∞
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: Configures custom categories for categorical scores
description:
type: string
nullable: true
description: Description of the score config
required:
- id
- name
- createdAt
- updatedAt
- projectId
- dataType
- isArchived
ConfigCategory:
title: ConfigCategory
type: object
properties:
value:
type: number
format: double
label:
type: string
required:
- value
- label
BaseScoreV1:
title: BaseScoreV1
type: object
properties:
id:
type: string
traceId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
observationId:
type: string
nullable: true
description: The observation ID associated with the score
timestamp:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
authorUserId:
type: string
nullable: true
description: The user ID of the author
comment:
type: string
nullable: true
description: Comment on the score
metadata:
type: object
additionalProperties: true
description: Metadata associated with the score
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, config and score name
must be equal and value must comply to optionally defined numerical
range
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
environment:
type: string
description: >-
The environment from which this score originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- traceId
- name
- source
- timestamp
- createdAt
- updatedAt
- authorUserId
- comment
- metadata
- configId
- queueId
- environment
NumericScoreV1:
title: NumericScoreV1
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
BooleanScoreV1:
title: BooleanScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for "False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
CategoricalScoreV1:
title: CategoricalScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
TextScoreV1:
title: TextScoreV1
type: object
properties:
stringValue:
type: string
description: The text content of the score (1-500 characters)
required:
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
ScoreV1:
title: ScoreV1
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV1'
required:
- dataType
title: NumericScoreV1
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV1'
required:
- dataType
title: CategoricalScoreV1
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV1'
required:
- dataType
title: BooleanScoreV1
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScoreV1'
required:
- dataType
title: TextScoreV1
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:
type: object
additionalProperties: true
description: Metadata associated with the score
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, config and score name
must be equal and value must comply to optionally defined numerical
range
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
environment:
type: string
description: >-
The environment from which this score originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- name
- source
- timestamp
- createdAt
- updatedAt
- authorUserId
- comment
- metadata
- configId
- queueId
- environment
NumericScore:
title: NumericScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScore'
BooleanScore:
title: BooleanScore
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for "False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CategoricalScore:
title: CategoricalScore
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CorrectionScore:
title: CorrectionScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score. Always 0 for correction scores.
stringValue:
type: string
description: The string representation of the correction content
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
TextScore:
title: TextScore
type: object
properties:
stringValue:
type: string
description: The text content of the score (1-500 characters)
required:
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
Score:
title: Score
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScore'
required:
- dataType
title: NumericScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScore'
required:
- dataType
title: CategoricalScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScore'
required:
- dataType
title: BooleanScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/CorrectionScore'
required:
- dataType
title: CorrectionScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScore'
required:
- dataType
title: TextScore
properties:
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
CreateScoreValue:
title: CreateScoreValue
oneOf:
- type: number
format: double
title: DoubleNumber
- type: string
title: 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:
type: object
additionalProperties: true
nullable: true
description: JSON Schema for validating dataset item inputs
expectedOutputSchema:
type: object
additionalProperties: true
nullable: true
description: JSON Schema for validating dataset item expected outputs
projectId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- description
- metadata
- inputSchema
- expectedOutputSchema
- projectId
- createdAt
- updatedAt
DatasetItem:
title: DatasetItem
type: object
properties:
id:
type: string
status:
$ref: '#/components/schemas/DatasetStatus'
input:
description: Input data for the dataset item
expectedOutput:
description: Expected output for the dataset item
metadata:
description: Metadata associated with the dataset item
sourceTraceId:
type: string
nullable: true
description: The trace ID that sourced this dataset item
sourceObservationId:
type: string
nullable: true
description: The observation ID that sourced this dataset item
datasetId:
type: string
datasetName:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
mediaReferences:
type: array
items:
$ref: '#/components/schemas/DatasetItemMediaReference'
description: >-
Resolved Langfuse media references found in input, expectedOutput,
and metadata.
required:
- id
- status
- input
- expectedOutput
- metadata
- sourceTraceId
- sourceObservationId
- datasetId
- datasetName
- createdAt
- updatedAt
- mediaReferences
DatasetItemMediaReference:
title: DatasetItemMediaReference
type: object
properties:
field:
$ref: '#/components/schemas/DatasetItemMediaReferenceField'
description: The dataset item field containing the reference
referenceString:
type: string
description: >-
The Langfuse media reference string, e.g.
`@@@langfuseMedia:type=image/png|id=...|source=bytes@@@`
jsonPath:
type: string
description: >-
JSONPath of the string holding the reference within the field, e.g.
`$['image']`
media:
$ref: '#/components/schemas/DatasetItemMediaReferenceMedia'
description: The resolved media record.
required:
- field
- referenceString
- jsonPath
- media
DatasetItemMediaReferenceField:
title: DatasetItemMediaReferenceField
type: string
enum:
- input
- expectedOutput
- metadata
DatasetItemMediaReferenceMedia:
title: DatasetItemMediaReferenceMedia
type: object
properties:
mediaId:
type: string
description: The unique langfuse identifier of the media record
contentType:
type: string
description: The MIME type of the media record
contentLength:
type: integer
description: The size of the media record in bytes
url:
type: string
description: The signed download URL of the media record
urlExpiry:
type: string
description: The expiry date and time of the download URL
required:
- mediaId
- contentType
- contentLength
- url
- urlExpiry
DatasetRunItem:
title: DatasetRunItem
type: object
properties:
id:
type: string
datasetRunId:
type: string
datasetRunName:
type: string
datasetItemId:
type: string
traceId:
type: string
observationId:
type: string
nullable: true
description: The observation ID associated with this run item
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- datasetRunId
- datasetRunName
- datasetItemId
- traceId
- observationId
- createdAt
- updatedAt
DatasetRun:
title: DatasetRun
type: object
properties:
id:
type: string
description: Unique identifier of the dataset run
name:
type: string
description: Name of the dataset run
description:
type: string
nullable: true
description: Description of the run
metadata:
description: Metadata of the dataset run
datasetId:
type: string
description: Id of the associated dataset
datasetName:
type: string
description: Name of the associated dataset
createdAt:
type: string
format: date-time
description: The date and time when the dataset run was created
updatedAt:
type: string
format: date-time
description: The date and time when the dataset run was last updated
required:
- id
- name
- description
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunWithItems:
title: DatasetRunWithItems
type: object
properties:
datasetRunItems:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- datasetRunItems
allOf:
- $ref: '#/components/schemas/DatasetRun'
Model:
title: Model
type: object
description: >-
Model definition used for transforming usage into USD cost and/or
tokenization.
Models can have either simple flat pricing or tiered pricing:
- Flat pricing: Single price per usage type (legacy, but still
supported)
- Tiered pricing: Multiple pricing tiers with conditional matching based
on usage patterns or observation attributes
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 or observation attributes.
Pricing tiers enable accurate cost tracking for models that charge
different rates based on usage patterns
or request attributes (e.g., high-volume usage, large context
windows, cached tokens, or service tiers).
Each model must have exactly one default tier (isDefault=true,
priority=0) that serves as a fallback.
Additional conditional tiers can be defined with specific matching
criteria.
If this array is empty, the model uses legacy flat pricing from the
inputPrice/outputPrice/totalPrice fields.
required:
- id
- modelName
- matchPattern
- startDate
- inputPrice
- outputPrice
- totalPrice
- tokenizerId
- tokenizerConfig
- isLangfuseManaged
- createdAt
- prices
- pricingTiers
ModelPrice:
title: ModelPrice
type: object
properties:
price:
type: number
format: double
required:
- price
PricingTierCondition:
title: PricingTierCondition
oneOf:
- $ref: '#/components/schemas/PricingTierUsageCondition'
- $ref: '#/components/schemas/PricingTierAttributeCondition'
description: >-
Condition for matching a pricing tier against usage details or
observation attributes.
Usage-detail conditions treat usageDetailPattern as a regex, sum all
matching usage values, and compare the sum to the numeric value.
Model-parameter and metadata conditions match an exact top-level key
against one or more string values.
PricingTierUsageCondition:
title: PricingTierUsageCondition
type: object
description: Condition that sums usage details whose keys match a regex.
properties:
usageDetailPattern:
type: string
description: Regex pattern matched against usage detail keys.
operator:
$ref: '#/components/schemas/PricingTierOperator'
value:
type: number
format: double
description: Numeric threshold for the summed matching usage values.
caseSensitive:
type: boolean
description: Whether the usage-detail regex is case-sensitive.
required:
- usageDetailPattern
- operator
- value
- caseSensitive
PricingTierAttributeCondition:
title: PricingTierAttributeCondition
type: object
description: >-
Condition that matches any configured value for a top-level observation
attribute.
properties:
source:
$ref: '#/components/schemas/PricingTierAttributeSource'
description: Observation attribute object evaluated by this condition.
key:
type: string
description: Exact top-level attribute key.
operator:
type: string
description: Membership operator.
values:
type: array
items:
type: string
description: Accepted string attribute values. At least one value is required.
required:
- source
- key
- operator
- values
PricingTierAttributeSource:
title: PricingTierAttributeSource
type: string
enum:
- model_parameters
- metadata
PricingTierConditionInput:
title: PricingTierConditionInput
oneOf:
- $ref: '#/components/schemas/PricingTierUsageConditionInput'
- $ref: '#/components/schemas/PricingTierAttributeCondition'
description: Condition input for matching a pricing tier.
PricingTierUsageConditionInput:
title: PricingTierUsageConditionInput
type: object
description: Input condition that sums usage details whose keys match a regex.
properties:
usageDetailPattern:
type: string
description: Regex pattern matched against usage detail keys.
operator:
$ref: '#/components/schemas/PricingTierOperator'
value:
type: number
format: double
description: Numeric threshold for the summed matching usage values.
caseSensitive:
type: boolean
nullable: true
description: Whether the usage-detail regex is case-sensitive. Defaults to false.
required:
- usageDetailPattern
- operator
- value
PricingTier:
title: PricingTier
type: object
description: >-
Pricing tier definition with conditional pricing based on usage
thresholds or observation attributes.
Pricing tiers enable accurate cost tracking for LLM providers that
charge different rates based on usage patterns or request attributes.
For example, some providers charge higher rates when context size
exceeds certain thresholds or when an accelerated service tier is
selected.
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
nullable: true
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.
Defaults to false when omitted.
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/PricingTierConditionInput'
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.
Conditions can compare summed matching usage details to a numeric
threshold, or exactly match a top-level model parameter or metadata
value.
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
- 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
title: String
- type: integer
nullable: true
title: Integer
- type: number
format: float
nullable: true
title: FloatNumber
- type: boolean
nullable: true
title: Boolean
- type: array
items:
type: string
nullable: true
title: Array
CommentObjectType:
title: CommentObjectType
type: string
enum:
- TRACE
- OBSERVATION
- SESSION
- PROMPT
DatasetStatus:
title: DatasetStatus
type: string
enum:
- ACTIVE
- ARCHIVED
ScoreSource:
title: ScoreSource
type: string
enum:
- ANNOTATION
- API
- EVAL
ScoreConfigDataType:
title: ScoreConfigDataType
type: string
enum:
- NUMERIC
- BOOLEAN
- CATEGORICAL
- TEXT
ScoreDataType:
title: ScoreDataType
type: string
enum:
- NUMERIC
- BOOLEAN
- CATEGORICAL
- CORRECTION
- TEXT
DeleteDatasetItemResponse:
title: DeleteDatasetItemResponse
type: object
properties:
message:
type: string
description: Success message after deletion
required:
- message
CreateDatasetItemRequest:
title: CreateDatasetItemRequest
type: object
properties:
datasetName:
type: string
input:
nullable: true
expectedOutput:
nullable: true
metadata:
nullable: true
sourceTraceId:
type: string
nullable: true
sourceObservationId:
type: string
nullable: true
id:
type: string
nullable: true
description: >-
Dataset items are upserted on their id. Id needs to be unique
(project-level), cannot be reused across datasets, and must be at
most 255 characters.
status:
$ref: '#/components/schemas/DatasetStatus'
nullable: true
description: Defaults to ACTIVE for newly created items
required:
- datasetName
PaginatedDatasetItems:
title: PaginatedDatasetItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRunItemRequest:
title: CreateDatasetRunItemRequest
type: object
properties:
runName:
type: string
runDescription:
type: string
nullable: true
description: Description of the run. If run exists, description will be updated.
metadata:
nullable: true
description: Metadata of the dataset run, updates run if run already exists
datasetItemId:
type: string
observationId:
type: string
nullable: true
traceId:
type: string
nullable: true
description: >-
traceId should always be provided. For compatibility with older SDK
versions it can also be inferred from the provided observationId.
datasetVersion:
type: string
format: date-time
nullable: true
description: >-
ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,
"2026-01-21T14:35:42Z").
Specifies the dataset version to use for this experiment run.
If provided, the experiment will use dataset items as they existed
at or before this timestamp.
If not provided, uses the latest version of dataset items.
createdAt:
type: string
format: date-time
nullable: true
description: >-
Optional timestamp to set the createdAt field of the dataset run
item. If not provided or null, defaults to current timestamp.
required:
- runName
- datasetItemId
PaginatedDatasetRunItems:
title: PaginatedDatasetRunItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
PaginatedDatasets:
title: PaginatedDatasets
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Dataset'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRequest:
title: CreateDatasetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
metadata:
nullable: true
inputSchema:
type: object
additionalProperties: true
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:
type: object
additionalProperties: true
nullable: true
description: >-
JSON Schema for validating dataset item expected outputs. When set,
all new and existing dataset items will be validated against this
schema.
required:
- name
PaginatedDatasetRuns:
title: PaginatedDatasetRuns
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRun'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
DeleteDatasetRunResponse:
title: DeleteDatasetRunResponse
type: object
properties:
message:
type: string
required:
- message
EvaluatorType:
title: EvaluatorType
type: string
enum:
- llm_as_judge
- code
description: |-
The evaluator type.
The public API supports LLM-as-a-judge and code evaluators.
CodeEvaluatorSourceCodeLanguage:
title: CodeEvaluatorSourceCodeLanguage
type: string
enum:
- PYTHON
- TYPESCRIPT
description: Code evaluator runtime language.
PromptVariableMappingSource:
title: PromptVariableMappingSource
type: string
enum:
- input
- output
- metadata
- tool_calls
- expected_output
- experiment_item_metadata
description: >-
Source field used to populate a prompt variable.
Use these values when mapping evaluator prompt variables to live data.
Source semantics:
- `input`: the observation input payload
- `output`: the observation output payload
- `metadata`: the observation metadata object. Combine with `jsonPath`
when you need one nested field instead of the whole object.
- `tool_calls`: the tool calls recorded on the observation, as an array
of `{id, name, arguments, type, index}` objects in the order the model
emitted them. Combine with `jsonPath` (for example `$[*].name`) to
select parts of each call.
- `expected_output`: the experiment item's expected output when the
observation belongs to an experiment.
- `experiment_item_metadata`: the experiment item's metadata when the
observation belongs to an experiment.
EvaluatorOutputScoreType:
title: EvaluatorOutputScoreType
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
EvaluatorOutputDefinition:
title: EvaluatorOutputDefinition
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/PublicEvaluatorNumericScore'
required:
- dataType
title: PublicEvaluatorNumericScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
required:
- dataType
title: PublicEvaluatorBooleanScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
required:
- dataType
title: PublicEvaluatorCategoricalScore
description: >-
Flat structured output definition used when creating or updating an
evaluator.
- `dataType` is required.
- `scoreReasoningInstructions` and `scoreValueInstructions` are optional
instructions.
- `minValue` and `maxValue` apply only to `NUMERIC` outputs. If both are
set, `minValue` must not exceed `maxValue`.
- `categories` and `shouldAllowMultipleMatches` apply only to
`CATEGORICAL` outputs.
- Do not send `version`; that is an internal storage detail.
EvaluatorOutputDefinitionBase:
title: EvaluatorOutputDefinitionBase
type: object
properties:
scoreReasoningInstructions:
type: string
nullable: true
description: >-
Optional instructions for deriving the reasoning returned with the
score.
scoreValueInstructions:
type: string
nullable: true
description: Optional instructions for deriving the score value.
PublicEvaluatorNumericScore:
title: PublicEvaluatorNumericScore
type: object
properties:
dataType:
type: string
description: Numeric score output.
minValue:
type: number
format: double
nullable: true
description: Optional inclusive minimum value.
maxValue:
type: number
format: double
nullable: true
description: Optional inclusive maximum value.
required:
- dataType
allOf:
- $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
PublicEvaluatorBooleanScore:
title: PublicEvaluatorBooleanScore
type: object
properties:
dataType:
type: string
description: Boolean score output.
required:
- dataType
allOf:
- $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
PublicEvaluatorCategoricalScore:
title: PublicEvaluatorCategoricalScore
type: object
properties:
dataType:
type: string
description: Categorical score output.
categories:
type: array
items:
type: string
description: Allowed category values. At least two unique values are required.
shouldAllowMultipleMatches:
type: boolean
description: Whether the evaluator may return more than one category.
required:
- dataType
- categories
- shouldAllowMultipleMatches
allOf:
- $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
PublicEvaluatorOutputDefinition:
title: PublicEvaluatorOutputDefinition
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/PublicEvaluatorNumericScore'
required:
- dataType
title: PublicEvaluatorNumericScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
required:
- dataType
title: PublicEvaluatorBooleanScore
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
required:
- dataType
title: PublicEvaluatorCategoricalScore
description: >-
Flat evaluator output definition returned by the public API.
This response always includes `dataType` and never includes an internal
output-definition `version`.
Optional empty descriptions from legacy definitions are omitted.
EvaluationRuleStringFilterOperator:
title: EvaluationRuleStringFilterOperator
type: string
enum:
- '='
- contains
- does not contain
- starts with
- ends with
EvaluationRuleNumberFilterOperator:
title: EvaluationRuleNumberFilterOperator
type: string
enum:
- '='
- '>'
- <
- '>='
- <=
EvaluationRuleOptionsFilterOperator:
title: EvaluationRuleOptionsFilterOperator
type: string
enum:
- any of
- none of
EvaluationRuleArrayOptionsFilterOperator:
title: EvaluationRuleArrayOptionsFilterOperator
type: string
enum:
- any of
- none of
- all of
EvaluationRuleBooleanFilterOperator:
title: EvaluationRuleBooleanFilterOperator
type: string
enum:
- '='
- <>
EvaluationRuleNullFilterOperator:
title: EvaluationRuleNullFilterOperator
type: string
enum:
- is null
- is not null
DateTimeEvaluationRuleFilter:
title: DateTimeEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
description: Comparison operator for datetime values.
value:
type: string
format: date-time
description: Datetime value to compare against.
required:
- column
- operator
- value
StringEvaluationRuleFilter:
title: StringEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleStringFilterOperator'
value:
type: string
required:
- column
- operator
- value
NumberEvaluationRuleFilter:
title: NumberEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
value:
type: number
format: double
required:
- column
- operator
- value
StringOptionsEvaluationRuleFilter:
title: StringOptionsEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator'
value:
type: array
items:
type: string
description: One or more allowed string values.
required:
- column
- operator
- value
ArrayOptionsEvaluationRuleFilter:
title: ArrayOptionsEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleArrayOptionsFilterOperator'
value:
type: array
items:
type: string
description: One or more array elements to match.
required:
- column
- operator
- value
StringObjectEvaluationRuleFilter:
title: StringObjectEvaluationRuleFilter
type: object
properties:
column:
type: string
description: >-
Object-valued column to filter on. Currently only `metadata` is
supported.
key:
type: string
description: Top-level key inside the object-valued column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleStringFilterOperator'
value:
type: string
required:
- column
- key
- operator
- value
NumberObjectEvaluationRuleFilter:
title: NumberObjectEvaluationRuleFilter
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/EvaluationRuleNumberFilterOperator'
value:
type: number
format: double
required:
- column
- key
- operator
- value
CategoryOptionsEvaluationRuleFilter:
title: CategoryOptionsEvaluationRuleFilter
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/EvaluationRuleOptionsFilterOperator'
value:
type: array
items:
type: string
required:
- column
- key
- operator
- value
BooleanEvaluationRuleFilter:
title: BooleanEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on.
operator:
$ref: '#/components/schemas/EvaluationRuleBooleanFilterOperator'
value:
type: boolean
required:
- column
- operator
- value
NullEvaluationRuleFilter:
title: NullEvaluationRuleFilter
type: object
properties:
column:
type: string
description: Column to filter on, for example `parentObservationId`.
operator:
$ref: '#/components/schemas/EvaluationRuleNullFilterOperator'
value:
type: string
description: >-
Required empty-string placeholder used by the runtime filter
contract.
required:
- column
- operator
- value
PromptVariableMappingInput:
title: PromptVariableMappingInput
type: object
description: >-
Connects one prompt variable to data from an observation or experiment.
Manual mappings are used for `llm_as_judge` evaluators. `code`
evaluators use a fixed runtime mapping managed by Langfuse.
How to build a valid mapping list:
1. Create the evaluator or fetch it with `GET /evaluators/{id}`.
2. Read the evaluator `variables` array.
3. Add exactly one mapping object for each variable in that array.
4. Use the variable name exactly as returned, without braces such as
`{{` or `}}`.
5. Choose the source field that should populate the variable.
`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.
Invalid, missing, or duplicate mappings return a validation error.
Malformed JSONPath expressions are also rejected.
properties:
variable:
type: string
description: >-
Prompt variable name without braces.
Example: for the prompt `Judge {{input}} against {{output}}`, use
`input` and `output`.
source:
$ref: '#/components/schemas/PromptVariableMappingSource'
description: >-
Source field that should populate the prompt variable.
Available sources are `input`, `output`, `metadata`, `tool_calls`,
`expected_output`, and `experiment_item_metadata`.
jsonPath:
type: string
nullable: true
description: >-
Optional JSONPath selector applied to the selected source before it
is passed to the evaluator prompt.
Requirements:
- Must start with `$`
- Must be a syntactically valid JSONPath expression
- Most useful with `source=metadata`
required:
- variable
- source
PromptVariableMappingRead:
title: PromptVariableMappingRead
type: object
description: |-
Connects one prompt variable to source data.
`source` is `null` when the mapping is incomplete.
properties:
variable:
type: string
description: Prompt variable name without braces.
source:
type: string
nullable: true
description: >-
Stored source field populating the variable, or `null` when the
mapping is incomplete.
jsonPath:
type: string
nullable: true
description: Optional JSONPath selector applied to the selected source.
required:
- variable
- source
PromptVariableMapping:
title: PromptVariableMapping
oneOf:
- $ref: '#/components/schemas/PromptVariableMappingRead'
- $ref: '#/components/schemas/LegacyPromptVariableMapping'
description: Connects one prompt variable to source data.
LegacyPromptVariableMapping:
title: LegacyPromptVariableMapping
type: object
description: >-
**Deprecated:** Connects one prompt variable to data from a legacy trace
or dataset evaluation rule.
`langfuseObject` selects the object kind. `objectName` separately
selects a named observation and is `null` for trace and dataset-item
mappings.
properties:
mappingType:
type: string
description: Explicitly marks this as a legacy mapping.
variable:
type: string
description: Prompt variable name without braces.
langfuseObject:
$ref: '#/components/schemas/LegacyEvaluationObject'
description: Legacy object kind selected as the mapping source.
objectName:
type: string
nullable: true
description: >-
Observation name to match, or `null` when `langfuseObject` is
`trace` or `dataset_item`.
source:
type: string
description: Field selected from the legacy object.
jsonPath:
type: string
nullable: true
description: Optional JSONPath selector applied to the selected field.
required:
- mappingType
- variable
- langfuseObject
- objectName
- source
LegacyEvaluationObject:
title: LegacyEvaluationObject
type: string
enum:
- trace
- span
- generation
- event
- agent
- tool
- chain
- retriever
- evaluator
- embedding
- guardrail
- dataset_item
description: >-
**Deprecated:** Legacy Langfuse object kind used by trace and dataset
evaluation rules.
EvaluationRuleFilter:
title: EvaluationRuleFilter
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- datetime
- $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'
required:
- type
title: DateTimeEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- string
- $ref: '#/components/schemas/StringEvaluationRuleFilter'
required:
- type
title: StringEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- number
- $ref: '#/components/schemas/NumberEvaluationRuleFilter'
required:
- type
title: NumberEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- stringOptions
- $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter'
required:
- type
title: StringOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- categoryOptions
- $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter'
required:
- type
title: CategoryOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- arrayOptions
- $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'
required:
- type
title: ArrayOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- stringObject
- $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'
required:
- type
title: StringObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- numberObject
- $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'
required:
- type
title: NumberObjectEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- boolean
- $ref: '#/components/schemas/BooleanEvaluationRuleFilter'
required:
- type
title: BooleanEvaluationRuleFilter
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- 'null'
- $ref: '#/components/schemas/NullEvaluationRuleFilter'
required:
- type
title: NullEvaluationRuleFilter
description: >-
One filter condition used to decide whether a live-ingested observation
should be evaluated.
All filters must be satisfied for the rule to run. Experiment scope is
expressed with filters rather than a separate target field:
- `isExperimentItemRootSpan = true` limits execution to experiment item
roots.
- `datasetId` limits execution to experiments for the selected datasets.
Use dataset IDs from `GET /api/public/v2/datasets`.
Pick the filter `type` first, as it determines the required fields and
value shape. Use `key` only for object filters such as `metadata`.
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`: `"="`, `contains`, `does not contain`, `starts with`,
`ends with`, `is set`, `is not set` (use `is set` / `is not set` for key
presence; an empty value for `contains`, `starts with`, or `ends with`
is treated as `is set`)
- `boolean`: `"="`, `"<>"`
- `null`: `is null`, `is not null`
Supported columns. Each column accepts exactly one filter `type`;
sending a column with a different `type` is rejected with `400`.
- `type`: `stringOptions`, values `SPAN`, `EVENT`, `GENERATION`,
`AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`,
`GUARDRAIL`
- `name`: `stringOptions`
- `environment`: `stringOptions`
- `level`: `stringOptions`, values `DEBUG`, `DEFAULT`, `WARNING`,
`ERROR`
- `version`: `string`
- `traceName`: `stringOptions`
- `userId`: `string`
- `sessionId`: `string`
- `tags`: `arrayOptions`
- `metadata`: `stringObject`, requires `key`
- `isRootObservation`: `boolean`; true when the observation has no
parent or is explicitly marked as an application root
- `parentObservationId`: `null`
- `experimentId`: `stringOptions`
- `isExperimentItemRootSpan`: `boolean`
- `calledToolNames`: `arrayOptions`
- `toolCalls`: `number`, the number of tool calls on the observation
- `datasetId`: `stringOptions`. Use dataset `id` values from `GET
/api/public/v2/datasets`, not dataset names.
EvaluationRuleReadFilterBase:
title: EvaluationRuleReadFilterBase
type: object
description: Stored filter returned verbatim by evaluation-rule read endpoints.
properties:
type:
type: string
description: >-
Stored filter type. This is not broken down into separate public
response types.
column:
type: string
operator:
type: string
value:
nullable: true
description: Stored filter value. Its shape depends on the filter type.
required:
- type
- column
- operator
EvaluationRuleReadFilterWithKey:
title: EvaluationRuleReadFilterWithKey
type: object
properties:
key:
type: string
description: Stored object or legacy filter key.
required:
- key
allOf:
- $ref: '#/components/schemas/EvaluationRuleReadFilterBase'
EvaluationRuleReadFilter:
title: EvaluationRuleReadFilter
oneOf:
- $ref: '#/components/schemas/EvaluationRuleReadFilterWithKey'
- $ref: '#/components/schemas/EvaluationRuleReadFilterBase'
description: >-
Filter returned verbatim by evaluation-rule read endpoints.
Filters with a stored `key` use the keyed shape. All other filters use
the base shape. Response filters are intentionally not broken down by
their internal `type` value.
PublicApiErrorCode:
title: PublicApiErrorCode
type: string
enum:
- authentication_failed
- access_denied
- invalid_request
- invalid_query
- invalid_body
- resource_not_found
- conflict
- rate_limited
- method_not_allowed
- internal_error
description: >-
Stable machine-readable error code returned by the evaluators and
evaluation-rules API.
PublicApiValidationIssue:
title: PublicApiValidationIssue
type: object
description: One request validation issue.
properties:
code:
type: string
description: Validator issue code.
message:
type: string
description: Human-readable explanation.
path:
type: array
items: {}
description: Path to the invalid request field.
required:
- code
- message
- path
PublicApiErrorDetails:
title: PublicApiErrorDetails
type: object
description: Optional structured context for validation and rate-limit errors.
properties:
issues:
type: array
items:
$ref: '#/components/schemas/PublicApiValidationIssue'
nullable: true
description: Validation issues for an invalid request body or query.
retryAfterSeconds:
type: integer
nullable: true
description: Number of seconds to wait before retrying a rate-limited request.
limit:
type: integer
nullable: true
description: Rate-limit request allowance.
remaining:
type: integer
nullable: true
description: Remaining requests in the current rate-limit window.
resetAt:
type: string
format: date-time
nullable: true
description: Time when the current rate-limit window resets.
PublicApiError:
title: PublicApiError
type: object
description: >-
Standard error response for the stable evaluators and evaluation-rules
API.
Use the HTTP status for the broad failure class and `code` for
programmatic handling. `details` is included when field-level validation
or retry information is available.
properties:
message:
type: string
description: Human-readable description of the failure.
code:
$ref: '#/components/schemas/PublicApiErrorCode'
description: Stable machine-readable error code.
details:
$ref: '#/components/schemas/PublicApiErrorDetails'
nullable: true
description: Optional structured validation or rate-limit context.
required:
- message
- code
EvaluationRuleEvaluatorAssignmentInput:
title: EvaluationRuleEvaluatorAssignmentInput
type: object
properties:
evaluatorId:
type: string
description: >-
Stable evaluator identifier. The rule automatically uses that
evaluator's latest version.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMappingInput'
nullable: true
description: >-
Rule-specific prompt-variable mapping.
Set to `null` or omit to inherit the evaluator's latest default
mapping. Code evaluators use the fixed runtime mapping and should
use `null`.
required:
- evaluatorId
EvaluatorAssignment:
title: EvaluatorAssignment
type: object
properties:
evaluatorId:
type: string
description: Stable identifier of the evaluator associated with this rule.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMapping'
nullable: true
description: >-
Stored rule-specific override, or `null` when the evaluator's latest
default mapping is inherited. Legacy mappings are returned as an
explicit `legacy` variant.
required:
- evaluatorId
- variableMapping
EvaluationRule:
title: EvaluationRule
type: object
description: >-
Live evaluation rule for incoming observations.
A rule determines which evaluators should be used, which observations
should trigger scoring, how often scoring should run, and which
observation fields should populate prompt variables.
properties:
id:
type: string
description: Stable evaluation-rule identifier.
name:
type: string
description: >-
Human-readable rule name. This is independent from evaluator names
and does not need to be unique.
createdBy:
$ref: '#/components/schemas/Creator'
nullable: true
description: User who created this rule, or `null` when no user can be resolved.
enabled:
type: boolean
description: Whether live execution is enabled for this rule.
sampling:
type: number
format: double
description: |-
Fraction of matching observations that should be evaluated.
Must be between `0` and `1`.
- `1` evaluates every matching observation.
- `0.25` evaluates approximately 25% of matching observations.
filter:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleReadFilter'
description: >-
List of stored filter conditions returned verbatim. Filters with a
`key` use the keyed response shape; all others use the base shape.
These response shapes are not broken down by internal filter type.
An empty list matches every incoming object.
evaluatorAssignments:
type: array
items:
$ref: '#/components/schemas/EvaluatorAssignment'
description: Evaluators attached to this rule in deterministic assignment order.
createdAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the evaluation rule was last updated.
required:
- id
- name
- createdBy
- enabled
- sampling
- filter
- evaluatorAssignments
- createdAt
- updatedAt
CreateEvaluationRuleRequest:
title: CreateEvaluationRuleRequest
type: object
properties:
name:
type: string
description: >-
Human-readable rule name. Names are not identifiers and do not need
to be unique.
enabled:
type: boolean
description: >-
Whether live execution should start immediately. Enabled rules
require at least one evaluator assignment.
sampling:
type: number
format: double
nullable: true
description: >-
Fraction of matching observations to evaluate. Omit this field to
use the default of `1`, which evaluates every match. `null` is not
accepted.
filter:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleFilter'
nullable: true
description: >-
Conditions used to select observations. Defaults to an empty list,
which matches every incoming observation.
evaluatorAssignments:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'
description: >-
Evaluators to attach to this rule. Disabled rules may use an empty
list as a draft.
required:
- name
- enabled
- evaluatorAssignments
UpdateEvaluationRuleRequest:
title: UpdateEvaluationRuleRequest
type: object
description: At least one field must be provided.
properties:
name:
type: string
nullable: true
description: New human-readable rule name.
enabled:
type: boolean
nullable: true
description: New desired live-execution state.
sampling:
type: number
format: double
nullable: true
description: >-
New fraction of matching observations to evaluate. Omit to keep the
current value.
filter:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleFilter'
nullable: true
description: >-
Complete replacement filter list. An empty list matches every
incoming observation.
evaluatorAssignments:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'
nullable: true
description: >-
Complete replacement assignment list. An empty list disables the
rule.
EvaluationRulesPage:
title: EvaluationRulesPage
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EvaluationRule'
description: Evaluation rules for this page.
meta:
$ref: '#/components/schemas/CursorMeta'
description: Cursor pagination metadata.
required:
- data
- meta
DeletedEvaluationRule:
title: DeletedEvaluationRule
type: object
description: Confirmation returned after successful evaluation-rule deletion.
properties:
id:
type: string
description: Identifier of the deleted evaluation rule.
required:
- id
Creator:
title: Creator
type: object
description: User who created the resource, or `null` when no user can be resolved.
properties:
id:
type: string
description: User identifier.
name:
type: string
nullable: true
description: User name, or `null` when unavailable.
required:
- id
- name
EvaluatorModelConfig:
title: EvaluatorModelConfig
type: object
description: >-
Explicit model configuration for an evaluator.
If the complete `modelConfig` is `null`, 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.
properties:
provider:
type: string
description: >-
Provider identifier, for example `openai` or `anthropic`.
To discover valid values for the current project, call `GET
/api/public/llm-connections` and use one of the returned `provider`
values.
model:
type: string
description: >-
Model identifier exposed by the provider, for example `gpt-4.1-mini`.
required:
- provider
- model
EvaluatorChatMessageRole:
title: EvaluatorChatMessageRole
type: string
enum:
- system
- user
- assistant
description: Role of an evaluator prompt message.
EvaluatorChatMessage:
title: EvaluatorChatMessage
type: object
description: One chat message in an evaluator prompt.
properties:
role:
$ref: '#/components/schemas/EvaluatorChatMessageRole'
content:
type: string
description: Message content. Evaluator variables use `{{variable}}` syntax.
required:
- role
- content
EvaluatorChatPrompt:
title: EvaluatorChatPrompt
type: array
items:
$ref: '#/components/schemas/EvaluatorChatMessage'
description: >-
An ordered list of chat messages. A system message is only allowed as
the first message.
EvaluatorChatPromptInput:
title: EvaluatorChatPromptInput
oneOf:
- type: string
title: String
- $ref: '#/components/schemas/EvaluatorChatPrompt'
description: A user prompt string shortcut, or an ordered list of chat messages.
EvaluatorVersionBase:
title: EvaluatorVersionBase
type: object
properties:
id:
type: string
description: Stable identifier of this evaluator version.
version:
type: integer
description: Monotonically increasing evaluator version number.
createdAt:
type: string
format: date-time
description: Timestamp when this evaluator version was created.
createdBy:
$ref: '#/components/schemas/Creator'
nullable: true
description: >-
User who created this version, or `null` when no user can be
resolved.
required:
- id
- version
- createdAt
- createdBy
LlmAsJudgeEvaluatorVersion:
title: LlmAsJudgeEvaluatorVersion
type: object
properties:
type:
type: string
description: Evaluator type.
prompt:
$ref: '#/components/schemas/EvaluatorChatPrompt'
description: Ordered chat messages used during evaluation.
variables:
type: array
items:
type: string
description: >-
Variables extracted from the prompt and available for
evaluation-rule mappings.
Every variable must be mapped exactly once when a rule provides an
explicit mapping.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMappingRead'
nullable: true
description: >-
Default variable mapping for this evaluator version, or `null` when
no default is configured.
modelConfig:
$ref: '#/components/schemas/EvaluatorModelConfig'
nullable: true
description: >-
Explicit model configuration, or `null` when the project's default
evaluation model is used.
outputDefinition:
$ref: '#/components/schemas/PublicEvaluatorOutputDefinition'
description: >-
Structured output schema returned by this evaluator.
Responses include `dataType` and omit the internal output-definition
persistence version.
required:
- type
- prompt
- variables
- variableMapping
- modelConfig
- outputDefinition
allOf:
- $ref: '#/components/schemas/EvaluatorVersionBase'
CodeEvaluatorVersion:
title: CodeEvaluatorVersion
type: object
properties:
type:
type: string
description: Evaluator type.
sourceCode:
type: string
description: Source code executed for each matched observation.
sourceCodeLanguage:
$ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
description: Runtime language used to execute the source code.
required:
- type
- sourceCode
- sourceCodeLanguage
allOf:
- $ref: '#/components/schemas/EvaluatorVersionBase'
EvaluatorVersion:
title: EvaluatorVersion
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- llm_as_judge
- $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'
required:
- type
title: LlmAsJudgeEvaluatorVersion
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- code
- $ref: '#/components/schemas/CodeEvaluatorVersion'
required:
- type
title: CodeEvaluatorVersion
EvaluationRuleAssignment:
title: EvaluationRuleAssignment
type: object
description: Evaluation-rule assignment associated with this evaluator.
properties:
evaluationRuleId:
type: string
description: Stable identifier of the assigned evaluation rule.
variableMappingOverride:
type: array
items:
$ref: '#/components/schemas/PromptVariableMapping'
nullable: true
description: >-
Rule-specific variable mapping override. Omitted when the
evaluator's latest default mapping is inherited. Legacy mappings use
the explicit `legacy` variant.
required:
- evaluationRuleId
EvaluatorBase:
title: EvaluatorBase
type: object
properties:
id:
type: string
description: Stable identifier of this evaluator across all versions.
name:
type: string
description: >-
Human-readable evaluator name. Names are not identifiers and do not
need to be unique.
description:
type: string
nullable: true
description: Optional human-readable evaluator description.
createdBy:
$ref: '#/components/schemas/Creator'
nullable: true
description: >-
User who created this evaluator, or `null` when no user can be
resolved.
status:
$ref: '#/components/schemas/EvaluatorStatus'
description: >-
Effective evaluator status after Langfuse validates its runtime
configuration.
pausedAt:
type: string
format: date-time
nullable: true
description: Timestamp when the evaluator was paused, otherwise `null`.
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`.
evaluationRuleAssignments:
type: array
items:
$ref: '#/components/schemas/EvaluationRuleAssignment'
description: >-
All modern and legacy evaluation-rule assignments in
newest-assignment-first order. Rule-specific mappings are exposed as
`variableMappingOverride`; inherited defaults are omitted.
createdAt:
type: string
format: date-time
description: Timestamp when the evaluator was created.
updatedAt:
type: string
format: date-time
description: Timestamp when the evaluator was last updated.
versionId:
type: string
description: Stable identifier of the latest evaluator version.
version:
type: integer
description: Monotonically increasing latest evaluator version number.
versionCreatedAt:
type: string
format: date-time
description: Timestamp when the latest evaluator version was created.
versionCreatedBy:
$ref: '#/components/schemas/Creator'
nullable: true
description: >-
User who created the latest evaluator version, or `null` when no
user can be resolved.
required:
- id
- name
- description
- createdBy
- status
- pausedAt
- pausedReason
- pausedMessage
- evaluationRuleAssignments
- createdAt
- updatedAt
- versionId
- version
- versionCreatedAt
- versionCreatedBy
LlmAsJudgeEvaluator:
title: LlmAsJudgeEvaluator
type: object
properties:
type:
type: string
description: Evaluator type.
prompt:
$ref: '#/components/schemas/EvaluatorChatPrompt'
description: Ordered chat messages used by the latest evaluator version.
variables:
type: array
items:
type: string
description: >-
Variables extracted from the latest prompt and available for
evaluation-rule mappings.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMappingRead'
nullable: true
description: >-
Default variable mapping for the latest version, or `null` when no
default is configured.
modelConfig:
$ref: '#/components/schemas/EvaluatorModelConfig'
nullable: true
description: >-
Explicit model configuration for the latest version, or `null` when
the project's default evaluation model is used.
outputDefinition:
$ref: '#/components/schemas/PublicEvaluatorOutputDefinition'
description: Structured output schema returned by the latest evaluator version.
required:
- type
- prompt
- variables
- variableMapping
- modelConfig
- outputDefinition
allOf:
- $ref: '#/components/schemas/EvaluatorBase'
CodeEvaluator:
title: CodeEvaluator
type: object
properties:
type:
type: string
description: Evaluator type.
sourceCode:
type: string
description: Source code executed by the latest evaluator version.
sourceCodeLanguage:
$ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
description: Runtime language used to execute the latest source code.
required:
- type
- sourceCode
- sourceCodeLanguage
allOf:
- $ref: '#/components/schemas/EvaluatorBase'
Evaluator:
title: Evaluator
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- llm_as_judge
- $ref: '#/components/schemas/LlmAsJudgeEvaluator'
required:
- type
title: LlmAsJudgeEvaluator
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- code
- $ref: '#/components/schemas/CodeEvaluator'
required:
- type
title: CodeEvaluator
description: >-
One evaluator that can be used for scoring.
An evaluator describes **how** to score data. Associated evaluation
rules describe **which** live objects should be evaluated.
EvaluatorStatus:
title: EvaluatorStatus
type: string
enum:
- active
- paused
description: >-
Effective evaluator runtime status.
- `active`: the evaluator can run.
- `paused`: Langfuse paused execution until the underlying issue is
resolved.
CreateLlmAsJudgeEvaluatorRequest:
title: CreateLlmAsJudgeEvaluatorRequest
type: object
properties:
name:
type: string
description: >-
Human-readable evaluator name. Names are not identifiers and do not
need to be unique.
description:
type: string
nullable: true
description: Optional human-readable evaluator description.
type:
type: string
description: Evaluator type.
prompt:
$ref: '#/components/schemas/EvaluatorChatPromptInput'
description: User prompt string shortcut or an ordered list of chat messages.
modelConfig:
$ref: '#/components/schemas/EvaluatorModelConfig'
nullable: true
description: >-
Explicit model configuration. Set to `null` or omit to use the
project's default evaluation model.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMappingInput'
nullable: true
description: >-
Default prompt-variable mapping, or `null` when no default is
configured.
outputDefinition:
$ref: '#/components/schemas/EvaluatorOutputDefinition'
description: >-
Structured output schema returned by this evaluator. Do not include
an internal persistence version.
required:
- name
- type
- prompt
- outputDefinition
CreateCodeEvaluatorRequest:
title: CreateCodeEvaluatorRequest
type: object
properties:
name:
type: string
description: >-
Human-readable evaluator name. Names are not identifiers and do not
need to be unique.
description:
type: string
nullable: true
description: Optional human-readable evaluator description.
type:
type: string
description: Evaluator type.
sourceCode:
type: string
description: Source code executed for each matched observation.
sourceCodeLanguage:
$ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
description: Runtime language used to execute the source code.
required:
- name
- type
- sourceCode
- sourceCodeLanguage
CreateEvaluatorRequest:
title: CreateEvaluatorRequest
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- llm_as_judge
- $ref: '#/components/schemas/CreateLlmAsJudgeEvaluatorRequest'
required:
- type
title: CreateLlmAsJudgeEvaluatorRequest
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- code
- $ref: '#/components/schemas/CreateCodeEvaluatorRequest'
required:
- type
title: CreateCodeEvaluatorRequest
description: >-
Initial evaluator definition with metadata and definition fields at the
same level. The returned evaluator starts at version `1`.
UpdateEvaluatorMetadataRequest:
title: UpdateEvaluatorMetadataRequest
type: object
description: Metadata-only update. At least one field must be provided.
properties:
name:
type: string
nullable: true
description: New human-readable evaluator name.
description:
type: string
nullable: true
description: New description. Set to `null` to clear it.
UpdateLlmAsJudgeEvaluatorRequest:
title: UpdateLlmAsJudgeEvaluatorRequest
type: object
properties:
name:
type: string
nullable: true
description: New human-readable evaluator name.
description:
type: string
nullable: true
description: New description. Set to `null` to clear it.
type:
type: string
description: Evaluator type. The type of an existing evaluator cannot change.
prompt:
$ref: '#/components/schemas/EvaluatorChatPromptInput'
description: >-
Complete replacement user prompt string or an ordered list of chat
messages.
modelConfig:
$ref: '#/components/schemas/EvaluatorModelConfig'
nullable: true
description: >-
Explicit model configuration. Set to `null` or omit to use the
project's default evaluation model.
variableMapping:
type: array
items:
$ref: '#/components/schemas/PromptVariableMappingInput'
nullable: true
description: >-
Complete replacement default variable mapping, or `null` when no
default is configured.
outputDefinition:
$ref: '#/components/schemas/EvaluatorOutputDefinition'
description: >-
Complete replacement output schema. Do not include an internal
persistence version.
required:
- type
- prompt
- outputDefinition
UpdateCodeEvaluatorRequest:
title: UpdateCodeEvaluatorRequest
type: object
properties:
name:
type: string
nullable: true
description: New human-readable evaluator name.
description:
type: string
nullable: true
description: New description. Set to `null` to clear it.
type:
type: string
description: Evaluator type. The type of an existing evaluator cannot change.
sourceCode:
type: string
description: Complete replacement source code.
sourceCodeLanguage:
$ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
description: Runtime language used to execute the source code.
required:
- type
- sourceCode
- sourceCodeLanguage
UpdateEvaluatorRequest:
title: UpdateEvaluatorRequest
oneOf:
- $ref: '#/components/schemas/UpdateEvaluatorMetadataRequest'
- $ref: '#/components/schemas/UpdateLlmAsJudgeEvaluatorRequest'
- $ref: '#/components/schemas/UpdateCodeEvaluatorRequest'
description: >-
Metadata-only update or complete flattened definition replacement. At
least one field must be provided.
EvaluatorsPage:
title: EvaluatorsPage
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Evaluator'
description: Evaluators for this page.
meta:
$ref: '#/components/schemas/CursorMeta'
description: Cursor pagination metadata.
required:
- data
- meta
EvaluatorVersionsPage:
title: EvaluatorVersionsPage
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/EvaluatorVersion'
description: Evaluator versions for this page in newest-first order.
meta:
$ref: '#/components/schemas/CursorMeta'
description: Cursor pagination metadata.
required:
- data
- meta
CursorMeta:
title: CursorMeta
type: object
description: Cursor pagination metadata.
properties: {}
allOf:
- $ref: '#/components/schemas/utilsCursorMetaResponse'
DeletedEvaluator:
title: DeletedEvaluator
type: object
description: Confirmation returned after successful evaluator deletion.
properties:
id:
type: string
description: Identifier of the deleted evaluator.
required:
- id
ExperimentsResponse:
title: ExperimentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Experiment'
meta:
$ref: '#/components/schemas/ExperimentsResponseMeta'
required:
- data
- meta
ExperimentsResponseMeta:
title: ExperimentsResponseMeta
type: object
description: Metadata for cursor-based pagination.
properties: {}
allOf:
- $ref: '#/components/schemas/utilsCursorMetaResponse'
Experiment:
title: Experiment
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
startTime:
type: string
format: date-time
description: |-
Start of the experiment, i.e. the earliest event within the
requested time range. Clipped to `fromStartTime` when the
experiment started before the requested range.
endTime:
type: string
format: date-time
description: |-
End of the experiment, i.e. the latest event end within the
requested time range.
itemCount:
type: integer
description: Number of experiment items within the requested time range.
datasetId:
type: string
nullable: true
description: Null when the experiment is not associated with a dataset.
metadata:
type: object
additionalProperties: true
nullable: true
description: Included only when `fields=metadata` is requested.
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
nullable: true
description: >-
Included only when `fields=scores` is requested. Contains scores
directly attached to the experiment.
required:
- id
- name
- description
- startTime
- endTime
- itemCount
- datasetId
ExperimentItemsResponse:
title: ExperimentItemsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ExperimentItem'
meta:
$ref: '#/components/schemas/ExperimentsResponseMeta'
required:
- data
- meta
ExperimentItem:
title: ExperimentItem
type: object
properties:
id:
type: string
traceId:
type: string
startTime:
type: string
format: date-time
endTime:
type: string
format: date-time
nullable: true
level:
$ref: '#/components/schemas/ObservationLevel'
environment:
type: string
experimentId:
type: string
experimentName:
type: string
experimentItemId:
type: string
experimentDatasetId:
type: string
nullable: true
description: Included when `fields=dataset` is requested.
experimentItemVersion:
type: string
format: date-time
nullable: true
description: Included when `fields=dataset` is requested.
input:
nullable: true
description: Included when `fields=io` is requested.
output:
nullable: true
description: Included when `fields=io` is requested.
expectedOutput:
nullable: true
description: Included when `fields=io` is requested.
metadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=metadata` is requested.
experimentItemMetadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=itemMetadata` is requested.
experimentMetadata:
type: object
additionalProperties: true
nullable: true
description: Included when `fields=experimentMetadata` is requested.
experimentDescription:
type: string
nullable: true
description: Included when `fields=experimentMetadata` is requested.
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
nullable: true
description: >-
Included only when `fields=scores` is requested. Contains item and
trace scores only; experiment-level scores are returned by the
experiments endpoint.
required:
- id
- traceId
- startTime
- endTime
- level
- environment
- experimentId
- experimentName
- experimentItemId
FeedbackTargetType:
title: FeedbackTargetType
type: string
enum:
- skill
- mcp-tool
- cli
- docs
- public-api
- other
SubmitFeedbackRequest:
title: SubmitFeedbackRequest
type: object
properties:
targetType:
$ref: '#/components/schemas/FeedbackTargetType'
description: Category of the thing the feedback is about.
target:
type: string
description: >-
The specific instance within targetType: the skill name, MCP tool
name, CLI command, API endpoint path, or docs page path (e.g.
'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be
between 1 and 200 characters.
feedback:
type: string
description: >-
Concise feedback text approved by the user. Must be between 1 and
3000 characters.
goal:
type: string
nullable: true
description: >-
Optional user-approved goal or use case they were trying to achieve.
Must be between 1 and 1500 characters when provided. Do not include
secrets, customer data, trace payloads, or broad unrelated context.
referenceUrl:
type: string
nullable: true
description: >-
Optional HTTP(S) reference URL. Langfuse stores it as text for
triage and does not fetch it.
required:
- targetType
- target
- feedback
SubmitFeedbackResponse:
title: SubmitFeedbackResponse
type: object
properties:
id:
type: string
description: Correlation ID for the submitted feedback.
required:
- id
HealthResponse:
title: HealthResponse
type: object
properties:
version:
type: string
description: Langfuse server version
status:
type: string
required:
- version
- status
IngestionEvent:
title: IngestionEvent
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- trace-create
- $ref: '#/components/schemas/TraceEvent'
required:
- type
title: TraceEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- score-create
- $ref: '#/components/schemas/ScoreEvent'
required:
- type
title: ScoreEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-create
- $ref: '#/components/schemas/CreateSpanEvent'
required:
- type
title: CreateSpanEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-update
- $ref: '#/components/schemas/UpdateSpanEvent'
required:
- type
title: UpdateSpanEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-create
- $ref: '#/components/schemas/CreateGenerationEvent'
required:
- type
title: CreateGenerationEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-update
- $ref: '#/components/schemas/UpdateGenerationEvent'
required:
- type
title: UpdateGenerationEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- event-create
- $ref: '#/components/schemas/CreateEventEvent'
required:
- type
title: CreateEventEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-create
- $ref: '#/components/schemas/CreateObservationEvent'
required:
- type
title: CreateObservationEvent
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-update
- $ref: '#/components/schemas/UpdateObservationEvent'
required:
- type
title: UpdateObservationEvent
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
ScoreBody:
title: ScoreBody
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
sessionId:
type: string
nullable: true
observationId:
type: string
nullable: true
datasetRunId:
type: string
nullable: true
name:
type: string
description: >-
The name of the score. Always overrides "output" for correction
scores.
environment:
type: string
nullable: true
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores. Boolean
score values must equal either 1 or 0 (true or false). Text score
values must be between 1 and 500 characters.
comment:
type: string
nullable: true
metadata:
nullable: true
dataType:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
description: >-
When set, must match the score value's type. If not set, will be
inferred from the score value or config
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, the score name must
equal the config name and scores must comply with the config's range
and data type. For categorical scores, the value must map to a
config category. Numeric scores might be constrained by the score
config's max and min values
required:
- name
- value
BaseEvent:
title: BaseEvent
type: object
properties:
id:
type: string
description: UUID v4 that identifies the event
timestamp:
type: string
description: >-
Datetime (ISO 8601) of event creation in client. Should be as close
to actual event creation in client as possible, this timestamp will
be used for ordering of events in future release. Resolution:
milliseconds (required), microseconds (optimal).
metadata:
nullable: true
description: Optional. Metadata field used by the Langfuse SDKs for debugging.
required:
- id
- timestamp
TraceEvent:
title: TraceEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/TraceBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateObservationEvent:
title: CreateObservationEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/ObservationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateObservationEvent:
title: UpdateObservationEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
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'
CreateGenerationEvent:
title: CreateGenerationEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateGenerationEvent:
title: UpdateGenerationEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/UpdateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateSpanEvent:
title: CreateSpanEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/CreateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateSpanEvent:
title: UpdateSpanEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
properties:
body:
$ref: '#/components/schemas/UpdateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateEventEvent:
title: CreateEventEvent
type: object
description: >-
Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
shut down on November 16, 2026, except for score events: from that date
it accepts only `score-create` events and rejects all other event types,
including this one. To write scores, prefer `POST /api/public/scores`;
see the [Scores API
docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
To write traces and observations, always prefer upgrading to the current
Python and JS SDKs. If you use custom auto-instrumentation, send them to
the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
example with curl; see the [OpenTelemetry integration
docs](https://langfuse.com/integrations/native/opentelemetry). To read
data back, use the v4 read APIs; see the [Observations API
docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
and the [Metrics API
docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
path to live data is OpenTelemetry ingestion combined with `GET
/api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
public APIs may have data delays of several minutes.
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'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
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
title: Object
- $ref: '#/components/schemas/OpenAICompletionUsageSchema'
- $ref: '#/components/schemas/OpenAIResponseUsageSchema'
legacyMetricsResponse:
title: legacyMetricsResponse
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
legacyObservations:
title: legacyObservations
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Observation'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
legacyObservationsViews:
title: legacyObservationsViews
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
LlmConnection:
title: LlmConnection
type: object
description: LLM API connection configuration (secrets excluded)
properties:
id:
type: string
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
type: string
description: The adapter used to interface with the LLM
displaySecretKey:
type: string
description: Masked version of the secret key for display purposes
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
description: List of custom model names available for this connection
withDefaultModels:
type: boolean
description: Whether to include default models for this adapter
extraHeaderKeys:
type: array
items:
type: string
description: >-
Keys of extra headers sent with requests (values excluded for
security)
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Required for Bedrock
(`{"region":"us-east-1"}`), optional for OpenAI
(`{"useResponsesApi":true}`), optional for VertexAI
(`{"location":"us-central1"}`), not used by other adapters.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- provider
- adapter
- displaySecretKey
- customModels
- withDefaultModels
- extraHeaderKeys
- createdAt
- updatedAt
PaginatedLlmConnections:
title: PaginatedLlmConnections
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LlmConnection'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
UpsertLlmConnectionRequest:
title: UpsertLlmConnectionRequest
type: object
description: Request to create or update an LLM connection (upsert)
properties:
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
$ref: '#/components/schemas/LlmAdapter'
description: The adapter used to interface with the LLM
secretKey:
type: string
description: Secret key for the LLM API.
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
nullable: true
description: List of custom model names
withDefaultModels:
type: boolean
nullable: true
description: Whether to include default models. Default is true.
extraHeaders:
type: object
additionalProperties:
type: string
nullable: true
description: Extra headers to send with requests
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Validation rules: - **Bedrock**:
Required. Must be `{"region": "<aws-region>"}` (e.g.,
`{"region":"us-east-1"}`) - **OpenAI**: Optional. If provided, must
be `{"useResponsesApi": <boolean>}` to control whether Langfuse
routes calls through OpenAI's Responses API. - **VertexAI**:
Optional. If provided, must be `{"location": "<gcp-location>"}`
(e.g., `{"location":"us-central1"}`) - **Other adapters**: Not
supported. Omit this field or set to null.
required:
- provider
- adapter
- secretKey
DeleteLlmConnectionResponse:
title: DeleteLlmConnectionResponse
type: object
properties:
message:
type: string
required:
- message
LlmAdapter:
title: LlmAdapter
type: string
enum:
- anthropic
- openai
- azure
- bedrock
- google-vertex-ai
- google-ai-studio
GetMediaResponse:
title: GetMediaResponse
type: object
properties:
mediaId:
type: string
description: The unique langfuse identifier of a media record
contentType:
type: string
description: The MIME type of the media record
contentLength:
type: integer
description: The size of the media record in bytes
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
url:
type: string
description: The download URL of the media record
urlExpiry:
type: string
description: The expiry date and time of the media record download URL
required:
- mediaId
- contentType
- contentLength
- uploadedAt
- url
- urlExpiry
PatchMediaBody:
title: PatchMediaBody
type: object
properties:
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
uploadHttpStatus:
type: integer
description: The HTTP status code of the upload
uploadHttpError:
type: string
nullable: true
description: The HTTP error message of the upload
uploadTimeMs:
type: integer
nullable: true
description: The time in milliseconds it took to upload the media record
required:
- uploadedAt
- uploadHttpStatus
GetMediaUploadUrlRequest:
title: GetMediaUploadUrlRequest
type: object
description: >-
Request a presigned media upload URL. Provide exactly one context: a
trace (traceId, optionally observationId) or a dataset item (datasetId +
datasetItemId). field is required and must match the chosen context.
properties:
traceId:
type: string
nullable: true
description: >-
The trace the media is associated with. Null for dataset item media
uploads.
observationId:
type: string
nullable: true
description: >-
The observation ID associated with the media record. If the media
record is associated directly with a trace, this will be null.
datasetId:
type: string
nullable: true
description: >-
The dataset the media belongs to. Null for trace/observation media
uploads.
datasetItemId:
type: string
nullable: true
description: >-
The dataset item the media is associated with (need not exist yet).
Null for trace/observation media uploads.
contentType:
$ref: '#/components/schemas/MediaContentType'
contentLength:
type: integer
description: The size of the media record in bytes
sha256Hash:
type: string
description: The SHA-256 hash of the media record
field:
type: string
description: >-
The item field the media is in: `input`/`output`/`metadata` (trace)
or `input`/`expectedOutput`/`metadata` (dataset item).
required:
- contentType
- contentLength
- sha256Hash
- field
GetMediaUploadUrlResponse:
title: GetMediaUploadUrlResponse
type: object
properties:
uploadUrl:
type: string
nullable: true
description: >-
The presigned upload URL. If the asset is already uploaded, this
will be null
mediaId:
type: string
description: The unique langfuse identifier of a media record
required:
- mediaId
MediaContentType:
title: MediaContentType
type: string
enum:
- image/png
- image/jpeg
- image/jpg
- image/webp
- image/gif
- image/svg+xml
- image/tiff
- image/bmp
- image/avif
- image/heic
- audio/mpeg
- audio/mp3
- audio/wav
- audio/ogg
- audio/oga
- audio/aac
- audio/mp4
- audio/flac
- audio/opus
- audio/webm
- video/mp4
- video/webm
- video/ogg
- video/mpeg
- video/quicktime
- video/x-msvideo
- video/x-matroska
- text/plain
- text/html
- text/css
- text/csv
- text/markdown
- text/x-python
- application/javascript
- text/x-typescript
- application/x-yaml
- application/pdf
- application/msword
- application/vnd.ms-excel
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/zip
- application/json
- application/xml
- application/octet-stream
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/rtf
- application/x-ndjson
- application/vnd.apache.parquet
- application/gzip
- application/x-tar
- application/x-7z-compressed
description: The MIME type of the media record
MetricsV2Response:
title: MetricsV2Response
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
required:
- data
ModelTokenizerId:
title: ModelTokenizerId
type: string
enum:
- openai
- claude
description: Tokenizer supported by Langfuse for model usage inference.
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'
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:
$ref: '#/components/schemas/ModelTokenizerId'
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
- unit
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: {}
allOf:
- $ref: '#/components/schemas/utilsCursorMetaResponse'
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:
type: object
additionalProperties: true
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
title: ChatPrompt
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- text
- $ref: '#/components/schemas/TextPrompt'
required:
- type
title: TextPrompt
PromptType:
title: PromptType
type: string
enum:
- chat
- text
BasePrompt:
title: BasePrompt
type: object
properties:
name:
type: string
version:
type: integer
config: {}
labels:
type: array
items:
type: string
description: List of deployment labels of this prompt version.
tags:
type: array
items:
type: string
description: >-
List of tags. Used to filter via UI and API. The same across
versions of a prompt.
commitMessage:
type: string
nullable: true
description: Commit message for this prompt version.
resolutionGraph:
type: object
additionalProperties: true
nullable: true
description: >-
The dependency resolution graph for the current prompt. Null if the
prompt has no dependencies or if `resolve=false` was used.
required:
- name
- version
- config
- labels
- tags
ChatMessageWithPlaceholders:
title: ChatMessageWithPlaceholders
oneOf:
- $ref: '#/components/schemas/ChatMessage'
- $ref: '#/components/schemas/PlaceholderMessage'
ChatMessage:
title: ChatMessage
type: object
properties:
role:
type: string
content:
type: string
type:
$ref: '#/components/schemas/ChatMessageType'
nullable: true
required:
- role
- content
ChatMessageType:
title: ChatMessageType
type: string
enum:
- chatmessage
PlaceholderMessage:
title: PlaceholderMessage
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/PlaceholderMessageType'
nullable: true
required:
- name
PlaceholderMessageType:
title: PlaceholderMessageType
type: string
enum:
- placeholder
TextPrompt:
title: TextPrompt
type: object
properties:
prompt:
type: string
required:
- prompt
allOf:
- $ref: '#/components/schemas/BasePrompt'
ChatPrompt:
title: ChatPrompt
type: object
properties:
prompt:
type: array
items:
$ref: '#/components/schemas/ChatMessageWithPlaceholders'
required:
- prompt
allOf:
- $ref: '#/components/schemas/BasePrompt'
CreateChatPromptType:
title: CreateChatPromptType
type: string
enum:
- chat
CreateTextPromptType:
title: CreateTextPromptType
type: string
enum:
- text
ServiceProviderConfig:
title: ServiceProviderConfig
type: object
properties:
schemas:
type: array
items:
type: string
documentationUri:
type: string
patch:
$ref: '#/components/schemas/ScimFeatureSupport'
bulk:
$ref: '#/components/schemas/BulkConfig'
filter:
$ref: '#/components/schemas/FilterConfig'
changePassword:
$ref: '#/components/schemas/ScimFeatureSupport'
sort:
$ref: '#/components/schemas/ScimFeatureSupport'
etag:
$ref: '#/components/schemas/ScimFeatureSupport'
authenticationSchemes:
type: array
items:
$ref: '#/components/schemas/AuthenticationScheme'
meta:
$ref: '#/components/schemas/ResourceMeta'
required:
- schemas
- documentationUri
- patch
- bulk
- filter
- changePassword
- sort
- etag
- authenticationSchemes
- meta
ScimFeatureSupport:
title: ScimFeatureSupport
type: object
properties:
supported:
type: boolean
required:
- supported
BulkConfig:
title: BulkConfig
type: object
properties:
supported:
type: boolean
maxOperations:
type: integer
maxPayloadSize:
type: integer
required:
- supported
- maxOperations
- maxPayloadSize
FilterConfig:
title: FilterConfig
type: object
properties:
supported:
type: boolean
maxResults:
type: integer
required:
- supported
- maxResults
ResourceMeta:
title: ResourceMeta
type: object
properties:
resourceType:
type: string
location:
type: string
required:
- resourceType
- location
AuthenticationScheme:
title: AuthenticationScheme
type: object
properties:
name:
type: string
description:
type: string
specUri:
type: string
type:
type: string
primary:
type: boolean
required:
- name
- description
- specUri
- type
- primary
ResourceTypesResponse:
title: ResourceTypesResponse
type: object
properties:
schemas:
type: array
items:
type: string
totalResults:
type: integer
Resources:
type: array
items:
$ref: '#/components/schemas/ResourceType'
required:
- schemas
- totalResults
- Resources
ResourceType:
title: ResourceType
type: object
properties:
schemas:
type: array
items:
type: string
nullable: true
id:
type: string
name:
type: string
endpoint:
type: string
description:
type: string
schema:
type: string
schemaExtensions:
type: array
items:
$ref: '#/components/schemas/SchemaExtension'
meta:
$ref: '#/components/schemas/ResourceMeta'
required:
- id
- name
- endpoint
- description
- schema
- schemaExtensions
- meta
SchemaExtension:
title: SchemaExtension
type: object
properties:
schema:
type: string
required:
type: boolean
required:
- schema
- required
SchemasResponse:
title: SchemasResponse
type: object
properties:
schemas:
type: array
items:
type: string
totalResults:
type: integer
Resources:
type: array
items:
$ref: '#/components/schemas/SchemaResource'
required:
- schemas
- totalResults
- Resources
SchemaResource:
title: SchemaResource
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
attributes:
type: array
items: {}
meta:
$ref: '#/components/schemas/ResourceMeta'
required:
- id
- name
- description
- attributes
- meta
ScimUsersListResponse:
title: ScimUsersListResponse
type: object
properties:
schemas:
type: array
items:
type: string
totalResults:
type: integer
startIndex:
type: integer
itemsPerPage:
type: integer
Resources:
type: array
items:
$ref: '#/components/schemas/ScimUser'
required:
- schemas
- totalResults
- startIndex
- itemsPerPage
- Resources
ScimUser:
title: ScimUser
type: object
properties:
schemas:
type: array
items:
type: string
id:
type: string
userName:
type: string
name:
$ref: '#/components/schemas/ScimName'
emails:
type: array
items:
$ref: '#/components/schemas/ScimEmail'
meta:
$ref: '#/components/schemas/UserMeta'
required:
- schemas
- id
- userName
- name
- emails
- meta
UserMeta:
title: UserMeta
type: object
properties:
resourceType:
type: string
created:
type: string
nullable: true
lastModified:
type: string
nullable: true
required:
- resourceType
ScimName:
title: ScimName
type: object
properties:
formatted:
type: string
nullable: true
ScimEmail:
title: ScimEmail
type: object
properties:
primary:
type: boolean
value:
type: string
type:
type: string
required:
- primary
- value
- type
EmptyResponse:
title: EmptyResponse
type: object
description: Empty response for 204 No Content responses
properties: {}
ScoreConfigs:
title: ScoreConfigs
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ScoreConfig'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateScoreConfigRequest:
title: CreateScoreConfigRequest
type: object
properties:
name:
type: string
description: >-
Name of the score config. Max 35 characters. Only letters, numbers,
underscores, spaces, periods, parentheses, and hyphens are allowed.
dataType:
$ref: '#/components/schemas/ScoreConfigDataType'
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: >-
Configure custom categories for categorical scores. Pass a list of
objects with `label` and `value` properties. Categories are
autogenerated for boolean configs and cannot be passed
minValue:
type: number
format: double
nullable: true
description: >-
Configure a minimum value for numerical scores. If not set, the
minimum value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Configure a maximum value for numerical scores. If not set, the
maximum value defaults to +∞
description:
type: string
nullable: true
description: >-
Description is shown across the Langfuse UI and can be used to e.g.
explain the config categories in detail, why a numeric range was
set, or provide additional context on config name or usage
required:
- name
- dataType
UpdateScoreConfigRequest:
title: UpdateScoreConfigRequest
type: object
properties:
isArchived:
type: boolean
nullable: true
description: The status of the score config showing if it is archived or not
name:
type: string
nullable: true
description: >-
Name of the score config. Max 35 characters. Only letters, numbers,
underscores, spaces, periods, parentheses, and hyphens are allowed.
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: >-
Configure custom categories for categorical scores. Pass a list of
objects with `label` and `value` properties. Categories are
autogenerated for boolean configs and cannot be passed
minValue:
type: number
format: double
nullable: true
description: >-
Configure a minimum value for numerical scores. If not set, the
minimum value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Configure a maximum value for numerical scores. If not set, the
maximum value defaults to +∞
description:
type: string
nullable: true
description: >-
Description is shown across the Langfuse UI and can be used to e.g.
explain the config categories in detail, why a numeric range was
set, or provide additional context on config name or usage
ScoreSubjectTraceV3:
title: ScoreSubjectTraceV3
type: object
properties:
id:
type: string
description: The trace ID.
required:
- id
ScoreSubjectObservationV3:
title: ScoreSubjectObservationV3
type: object
properties:
id:
type: string
description: The observation ID.
traceId:
type: string
nullable: true
description: The parent trace ID, if available.
required:
- id
ScoreSubjectSessionV3:
title: ScoreSubjectSessionV3
type: object
properties:
id:
type: string
description: The session ID.
required:
- id
ScoreSubjectExperimentV3:
title: ScoreSubjectExperimentV3
type: object
properties:
id:
type: string
description: The dataset run ID (experiment ID).
required:
- id
ScoreSubjectV3:
title: ScoreSubjectV3
oneOf:
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- trace
- $ref: '#/components/schemas/ScoreSubjectTraceV3'
required:
- kind
title: ScoreSubjectTraceV3
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- observation
- $ref: '#/components/schemas/ScoreSubjectObservationV3'
required:
- kind
title: ScoreSubjectObservationV3
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- session
- $ref: '#/components/schemas/ScoreSubjectSessionV3'
required:
- kind
title: ScoreSubjectSessionV3
- type: object
allOf:
- type: object
properties:
kind:
type: string
enum:
- experiment
- $ref: '#/components/schemas/ScoreSubjectExperimentV3'
required:
- kind
title: ScoreSubjectExperimentV3
description: >-
A reference to the entity this score is attached to. Discriminated by
"kind" — one of trace, observation, session, or experiment.
BaseScoreV3:
title: BaseScoreV3
type: object
properties:
id:
type: string
projectId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
timestamp:
type: string
format: date-time
environment:
type: string
description: The environment from which this score originated.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
comment:
type: string
nullable: true
description: >-
Optional comment attached to the score. Present when "details" is
included in the fields parameter.
configId:
type: string
nullable: true
description: >-
The score config ID, if this score was created from a config.
Present when "details" is included in the fields parameter.
metadata:
type: object
additionalProperties: true
nullable: true
description: >-
Arbitrary metadata attached to the score. Present when "details" is
included in the fields parameter.
authorUserId:
type: string
nullable: true
description: >-
The user who created this score, if available. Present when
"annotation" is included in the fields parameter.
queueId:
type: string
nullable: true
description: >-
The annotation queue this score belongs to, if any. Present when
"annotation" is included in the fields parameter.
subject:
$ref: '#/components/schemas/ScoreSubjectV3'
nullable: true
description: >-
The entity this score is attached to (trace, observation, session,
or experiment). Present when "subject" is included in the fields
parameter.
required:
- id
- projectId
- name
- source
- timestamp
- environment
- createdAt
- updatedAt
NumericScoreV3:
title: NumericScoreV3
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
BooleanScoreV3:
title: BooleanScoreV3
type: object
properties:
value:
type: boolean
description: The boolean value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
CategoricalScoreV3:
title: CategoricalScoreV3
type: object
properties:
value:
type: string
description: The string category value of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
TextScoreV3:
title: TextScoreV3
type: object
properties:
value:
type: string
description: The text content of the score.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
CorrectionScoreV3:
title: CorrectionScoreV3
type: object
properties:
value:
type: string
description: The correction content of the score. Empty string if not set.
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV3'
ScoreV3:
title: ScoreV3
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV3'
required:
- dataType
title: NumericScoreV3
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV3'
required:
- dataType
title: BooleanScoreV3
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV3'
required:
- dataType
title: CategoricalScoreV3
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/TextScoreV3'
required:
- dataType
title: TextScoreV3
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/CorrectionScoreV3'
required:
- dataType
title: CorrectionScoreV3
GetScoresV3Meta:
title: GetScoresV3Meta
type: object
properties:
limit:
type: integer
required:
- limit
allOf:
- $ref: '#/components/schemas/utilsCursorMetaResponse'
GetScoresV3Response:
title: GetScoresV3Response
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ScoreV3'
meta:
$ref: '#/components/schemas/GetScoresV3Meta'
required:
- data
- meta
CreateScoreRequest:
title: CreateScoreRequest
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
sessionId:
type: string
nullable: true
observationId:
type: string
nullable: true
datasetRunId:
type: string
nullable: true
name:
type: string
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical and
text scores, and numeric for boolean and numeric scores. Boolean
score values must equal either 1 or 0 (true or false). Text score
values must be between 1 and 500 characters.
comment:
type: string
nullable: true
metadata:
type: object
additionalProperties: true
nullable: true
environment:
type: string
nullable: true
description: >-
The environment of the score. Can be any lowercase alphanumeric
string with hyphens and underscores that does not start with
'langfuse'.
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
dataType:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
description: >-
The data type of the score. When passing a configId this field is
inferred. Otherwise, this field must be passed or will default to
numeric.
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. The unique langfuse identifier
of a score config. When passing this field, the dataType and
stringValue fields are automatically populated.
source:
$ref: '#/components/schemas/CreateScoreSource'
nullable: true
description: >-
The source of the score. Defaults to API. Set to ANNOTATION to
prefill scores (e.g. from an LLM) for a human reviewer to verify in
an annotation queue. When source is ANNOTATION, a configId is
required unless dataType is CORRECTION. EVAL is reserved for
internal evaluator outputs and is not accepted on this endpoint.
required:
- name
- value
CreateScoreSource:
title: CreateScoreSource
type: string
enum:
- API
- ANNOTATION
description: |-
Source values accepted when creating a score via the public REST API.
EVAL is reserved for internal evaluator outputs and is intentionally not
exposed here — use commons.ScoreSource when reading scores.
CreateScoreResponse:
title: CreateScoreResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
GetScoresResponseTraceData:
title: GetScoresResponseTraceData
type: object
properties:
userId:
type: string
nullable: true
description: The user ID associated with the trace referenced by score
tags:
type: array
items:
type: string
nullable: true
description: A list of tags associated with the trace referenced by score
environment:
type: string
nullable: true
description: The environment of the trace referenced by score
sessionId:
type: string
nullable: true
description: The session ID associated with the trace referenced by score
GetScoresResponseDataNumeric:
title: GetScoresResponseDataNumeric
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/NumericScore'
GetScoresResponseDataCategorical:
title: GetScoresResponseDataCategorical
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/CategoricalScore'
GetScoresResponseDataBoolean:
title: GetScoresResponseDataBoolean
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/BooleanScore'
GetScoresResponseDataCorrection:
title: GetScoresResponseDataCorrection
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/CorrectionScore'
GetScoresResponseDataText:
title: GetScoresResponseDataText
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/TextScore'
GetScoresResponseData:
title: GetScoresResponseData
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/GetScoresResponseDataNumeric'
required:
- dataType
title: GetScoresResponseDataNumeric
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/GetScoresResponseDataCategorical'
required:
- dataType
title: GetScoresResponseDataCategorical
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/GetScoresResponseDataBoolean'
required:
- dataType
title: GetScoresResponseDataBoolean
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/GetScoresResponseDataCorrection'
required:
- dataType
title: GetScoresResponseDataCorrection
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- TEXT
- $ref: '#/components/schemas/GetScoresResponseDataText'
required:
- dataType
title: GetScoresResponseDataText
GetScoresResponse:
title: GetScoresResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GetScoresResponseData'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
PaginatedSessions:
title: PaginatedSessions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Session'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
Traces:
title: Traces
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TraceWithDetails'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
_deprecation:
$ref: '#/components/schemas/Deprecation'
nullable: true
required:
- data
- meta
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
properties:
message:
type: string
required:
- message
Sort:
title: Sort
type: object
properties:
id:
type: string
required:
- id
unstableDashboardWidgetView:
title: unstableDashboardWidgetView
type: string
enum:
- observations
- scores-numeric
- scores-boolean
- scores-categorical
unstableDashboardWidgetViewWithLegacy:
title: unstableDashboardWidgetViewWithLegacy
type: string
enum:
- observations
- scores-numeric
- scores-boolean
- scores-categorical
- traces
description: |-
Widget data view. Responses may include the legacy `traces` value for
widgets created before this API existed.
unstableDashboardWidgetChartType:
title: unstableDashboardWidgetChartType
type: string
enum:
- LINE_TIME_SERIES
- AREA_TIME_SERIES
- BAR_TIME_SERIES
- HORIZONTAL_BAR
- VERTICAL_BAR
- PIE
- NUMBER
- HISTOGRAM
- PIVOT_TABLE
unstableDashboardWidgetMetricAggregation:
title: unstableDashboardWidgetMetricAggregation
type: string
enum:
- sum
- avg
- count
- max
- min
- p50
- p75
- p90
- p95
- p99
- histogram
- uniq
unstableDashboardWidgetDimension:
title: unstableDashboardWidgetDimension
type: object
properties:
field:
type: string
required:
- field
unstableDashboardWidgetMetric:
title: unstableDashboardWidgetMetric
type: object
properties:
measure:
type: string
agg:
$ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation'
required:
- measure
- agg
unstableDashboardWidgetFilter:
title: unstableDashboardWidgetFilter
type: object
description: >-
A filter in Langfuse filter-state shape. The `value` shape and the
allowed operators depend on `type`:
| `type` | `value` | operators |
|---|---|---|
| `string` | string | `=`, `contains`, `does not contain`, `starts
with`, `ends with` |
| `number` | number | `=`, `>`, `<`, `>=`, `<=` |
| `datetime` | ISO datetime string | `>`, `<`, `>=`, `<=` |
| `boolean` | boolean | `=`, `<>` |
| `null` | `""` | `is null`, `is not null` |
| `stringOptions` | list of strings | `any of`, `none of` |
| `arrayOptions` | list of strings | `any of`, `none of`, `all of` |
| `categoryOptions` | list of strings (requires `key`) | `any of`, `none
of` |
| `stringObject` | string (requires `key`, e.g. a metadata key) | same
as `string` |
| `numberObject` | number (requires `key`, e.g. a score name) | same as
`number` |
| `booleanObject` | boolean (requires `key`) | `=`, `<>` |
properties:
column:
type: string
operator:
type: string
type:
type: string
value:
nullable: true
key:
type: string
nullable: true
required:
- column
- operator
- type
unstableDashboardWidgetChartConfig:
title: unstableDashboardWidgetChartConfig
type: object
description: |-
Chart-specific widget configuration.
`type` must match the top-level `chartType`.
`row_limit` applies to total-value charts and pivot tables.
`bins` applies to histograms.
`defaultSort` applies to pivot tables.
properties:
type:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
row_limit:
type: integer
nullable: true
show_value_labels:
type: boolean
nullable: true
bins:
type: integer
nullable: true
defaultSort:
$ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
nullable: true
required:
- type
unstableDashboardWidgetDefaultSort:
title: unstableDashboardWidgetDefaultSort
type: object
properties:
column:
type: string
order:
$ref: '#/components/schemas/unstableDashboardWidgetSortOrder'
required:
- column
- order
unstableDashboardWidgetSortOrder:
title: unstableDashboardWidgetSortOrder
type: string
enum:
- ASC
- DESC
unstableDashboardWidgetChartConfigInput:
title: unstableDashboardWidgetChartConfigInput
type: object
description: |-
Input-side chart config. `type` is optional and defaults to the
widget's `chartType`; when given it must match.
properties:
type:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
nullable: true
row_limit:
type: integer
nullable: true
show_value_labels:
type: boolean
nullable: true
bins:
type: integer
nullable: true
defaultSort:
$ref: '#/components/schemas/unstableDashboardWidgetDefaultSort'
nullable: true
unstableCreateDashboardWidgetRequest:
title: unstableCreateDashboardWidgetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
description: Defaults to an empty string.
view:
$ref: '#/components/schemas/unstableDashboardWidgetView'
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
nullable: true
description: Defaults to the plain config for `chartType`.
required:
- name
- view
- dimensions
- metrics
- filters
- chartType
unstableUpdateDashboardWidgetRequest:
title: unstableUpdateDashboardWidgetRequest
type: object
properties:
name:
type: string
nullable: true
description:
type: string
nullable: true
view:
$ref: '#/components/schemas/unstableDashboardWidgetView'
nullable: true
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
nullable: true
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
nullable: true
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput'
nullable: true
unstableDashboardWidgetList:
title: unstableDashboardWidgetList
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidget'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableDeleteDashboardWidgetResponse:
title: unstableDeleteDashboardWidgetResponse
type: object
properties:
message:
type: string
required:
- message
unstableDashboardWidget:
title: unstableDashboardWidget
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
description:
type: string
view:
$ref: '#/components/schemas/unstableDashboardWidgetViewWithLegacy'
dimensions:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetDimension'
metrics:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetMetric'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
chartType:
$ref: '#/components/schemas/unstableDashboardWidgetChartType'
chartConfig:
$ref: '#/components/schemas/unstableDashboardWidgetChartConfig'
required:
- id
- createdAt
- updatedAt
- name
- description
- view
- dimensions
- metrics
- filters
- chartType
- chartConfig
unstableDashboardPlacement:
title: unstableDashboardPlacement
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- widget
- $ref: '#/components/schemas/unstableWidgetPlacement'
required:
- type
title: UnstableWidgetPlacement
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- preset
- $ref: '#/components/schemas/unstablePresetPlacement'
required:
- type
title: UnstablePresetPlacement
description: |-
A tile on the dashboard's 12-column grid. `x`/`y` are the tile's
top-left cell (0-based; `y` grows downward), `width`/`height` its size
in cells. The UI default tile is 6x6 (half width). Overlapping tiles
are not rejected; prefer appending below existing tiles (or omit the
position on create to let the server do it).
unstableWidgetPlacement:
title: unstableWidgetPlacement
type: object
properties:
id:
type: string
widgetId:
type: string
x:
type: integer
'y':
type: integer
width:
type: integer
height:
type: integer
required:
- id
- widgetId
- x
- 'y'
- width
- height
unstablePresetPlacement:
title: unstablePresetPlacement
type: object
properties:
id:
type: string
presetId:
type: string
x:
type: integer
'y':
type: integer
width:
type: integer
height:
type: integer
required:
- id
- presetId
- x
- 'y'
- width
- height
unstableCreateDashboardPlacementRequest:
title: unstableCreateDashboardPlacementRequest
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- widget
- $ref: '#/components/schemas/unstableCreateWidgetPlacement'
required:
- type
title: UnstableCreateWidgetPlacement
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- preset
- $ref: '#/components/schemas/unstableCreatePresetPlacement'
required:
- type
title: UnstableCreatePresetPlacement
unstableCreateWidgetPlacement:
title: unstableCreateWidgetPlacement
type: object
properties:
id:
type: string
nullable: true
description: Server-generated when omitted.
widgetId:
type: string
x:
type: integer
nullable: true
description: Grid column (12-column grid). Defaults to `0`.
'y':
type: integer
nullable: true
description: Grid row. Defaults to the first row below all existing tiles.
width:
type: integer
nullable: true
description: Width in grid columns. Defaults to `6`.
height:
type: integer
nullable: true
description: Height in grid rows. Defaults to `6`.
required:
- widgetId
unstableCreatePresetPlacement:
title: unstableCreatePresetPlacement
type: object
properties:
id:
type: string
nullable: true
description: Server-generated when omitted.
presetId:
type: string
x:
type: integer
nullable: true
description: Grid column (12-column grid). Defaults to `0`.
'y':
type: integer
nullable: true
description: Grid row. Defaults to the first row below all existing tiles.
width:
type: integer
nullable: true
description: Width in grid columns. Defaults to `6`.
height:
type: integer
nullable: true
description: Height in grid rows. Defaults to `6`.
required:
- presetId
unstableUpdateDashboardPlacementRequest:
title: unstableUpdateDashboardPlacementRequest
type: object
properties:
x:
type: integer
nullable: true
description: Grid column (12-column grid).
'y':
type: integer
nullable: true
description: Grid row.
width:
type: integer
nullable: true
description: Width in grid columns.
height:
type: integer
nullable: true
description: Height in grid rows.
unstableDeleteDashboardPlacementResponse:
title: unstableDeleteDashboardPlacementResponse
type: object
properties:
message:
type: string
required:
- message
unstableDashboardDefinition:
title: unstableDashboardDefinition
type: object
properties:
widgets:
type: array
items:
$ref: '#/components/schemas/unstableDashboardPlacement'
required:
- widgets
unstableDashboard:
title: unstableDashboard
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
name:
type: string
description:
type: string
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
description: Dashboard-level filters applied to all widgets on the dashboard.
required:
- id
- createdAt
- updatedAt
- name
- description
- definition
- filters
unstableDashboardList:
title: unstableDashboardList
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableDashboard'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableCreateDashboardRequest:
title: unstableCreateDashboardRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
required:
- name
unstableUpdateDashboardRequest:
title: unstableUpdateDashboardRequest
type: object
properties:
name:
type: string
nullable: true
description:
type: string
nullable: true
definition:
$ref: '#/components/schemas/unstableDashboardDefinition'
nullable: true
filters:
type: array
items:
$ref: '#/components/schemas/unstableDashboardWidgetFilter'
nullable: true
unstableDeleteDashboardResponse:
title: unstableDeleteDashboardResponse
type: object
properties:
message:
type: string
required:
- message
unstablePublicApiErrorCode:
title: unstablePublicApiErrorCode
type: string
enum:
- authentication_failed
- access_denied
- invalid_request
- invalid_query
- invalid_body
- resource_not_found
- conflict
- rate_limited
- method_not_allowed
- internal_error
description: Machine-readable error code returned by unstable public API endpoints.
unstablePublicApiValidationIssue:
title: unstablePublicApiValidationIssue
type: object
description: >-
A validation issue returned for malformed request bodies or query
parameters.
properties:
code:
type: string
message:
type: string
path:
type: array
items: {}
required:
- code
- message
- path
unstablePublicApiErrorDetails:
title: unstablePublicApiErrorDetails
type: object
description: Optional structured context attached to an error.
properties:
issues:
type: array
items:
$ref: '#/components/schemas/unstablePublicApiValidationIssue'
nullable: true
field:
type: string
nullable: true
column:
type: string
nullable: true
invalidValues:
type: array
items:
type: string
nullable: true
allowedValues:
type: array
items:
type: string
nullable: true
value:
type: string
nullable: true
retryAfterSeconds:
type: integer
nullable: true
limit:
type: integer
nullable: true
remaining:
type: integer
nullable: true
resetAt:
type: string
nullable: true
unstablePublicApiError:
title: unstablePublicApiError
type: object
description: Standard error envelope for unstable public API endpoints.
properties:
message:
type: string
description: Human-readable description of the failure.
code:
$ref: '#/components/schemas/unstablePublicApiErrorCode'
description: Machine-readable error code.
details:
$ref: '#/components/schemas/unstablePublicApiErrorDetails'
nullable: true
description: Optional structured error context.
required:
- message
- code
unstableSkillMetaListResponse:
title: unstableSkillMetaListResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableSkillMeta'
meta:
$ref: '#/components/schemas/unstableSkillListPagination'
required:
- data
- meta
unstableSkillListPagination:
title: unstableSkillListPagination
type: object
properties:
hasNextPage:
type: boolean
required:
- hasNextPage
allOf:
- $ref: '#/components/schemas/utilsMetaResponse'
unstableSkillMeta:
title: unstableSkillMeta
type: object
properties:
name:
type: string
description:
type: string
tags:
type: array
items:
type: string
latestVersion:
type: integer
latestVersionCreatedAt:
type: string
format: date-time
latestVersionLastUpdatedAt:
type: string
format: date-time
productionVersion:
type: integer
nullable: true
description: >-
Version assigned the production label, or null when no version is
assigned.
required:
- name
- description
- tags
- latestVersion
- latestVersionCreatedAt
- latestVersionLastUpdatedAt
- productionVersion
unstableSkillVersionFileInput:
title: unstableSkillVersionFileInput
type: object
properties:
path:
type: string
content:
type: string
description: UTF-8 text content. The server computes the hash and byte length.
required:
- path
- content
unstableSkillVersionFileReference:
title: unstableSkillVersionFileReference
type: object
properties:
path:
type: string
sha256Hash:
type: string
description: >-
Canonical base64-encoded SHA-256 from a skill file manifest. The
content must already exist in this project.
required:
- path
- sha256Hash
unstableSkillVersionFileCreateInput:
title: unstableSkillVersionFileCreateInput
oneOf:
- $ref: '#/components/schemas/unstableSkillVersionFileInput'
- $ref: '#/components/schemas/unstableSkillVersionFileReference'
description: Provide exactly one of content or sha256Hash for each path.
unstableCreateSkillVersionRequest:
title: unstableCreateSkillVersionRequest
type: object
properties:
files:
type: array
items:
$ref: '#/components/schemas/unstableSkillVersionFileCreateInput'
commitMessage:
type: string
nullable: true
required:
- files
unstableSkillFile:
title: unstableSkillFile
type: object
properties:
id:
type: string
path:
type: string
blobId:
type: string
sha256Hash:
type: string
contentType:
type: string
contentLength:
type: integer
format: int64
required:
- id
- path
- blobId
- sha256Hash
- contentType
- contentLength
unstableSkillFileContentsResponse:
title: unstableSkillFileContentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableSkillFileContent'
required:
- data
unstableSkillFileContent:
title: unstableSkillFileContent
type: object
properties:
sha256Hash:
type: string
content:
type: string
required:
- sha256Hash
- content
unstableSkillVersion:
title: unstableSkillVersion
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
type: string
createdBy:
type: string
name:
type: string
description:
type: string
frontmatter: {}
version:
type: integer
tags:
type: array
items:
type: string
labels:
type: array
items:
type: string
commitMessage:
type: string
nullable: true
files:
type: array
items:
$ref: '#/components/schemas/unstableSkillFile'
required:
- id
- createdAt
- updatedAt
- projectId
- createdBy
- name
- description
- frontmatter
- version
- tags
- labels
- commitMessage
- files
unstableUpdateSkillRequest:
title: unstableUpdateSkillRequest
type: object
properties:
tags:
type: array
items:
type: string
description: >-
The complete set of tags to apply to every version of the skill.
Pass an empty list to clear all tags.
required:
- tags
unstableUpdateSkillLabelsRequest:
title: unstableUpdateSkillLabelsRequest
type: object
properties:
labels:
type: array
items:
type: string
required:
- labels
unstableDeleteSkillVersionResponse:
title: unstableDeleteSkillVersionResponse
type: object
properties:
deleted:
type: boolean
required:
- deleted
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
utilsCursorMetaResponse:
title: utilsCursorMetaResponse
type: object
description: Metadata for cursor-based pagination.
properties:
cursor:
type: string
nullable: true
description: Opaque cursor for the next page. Omitted when there is no next page.
securitySchemes:
BasicAuth:
type: http
scheme: basic