🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
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/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/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 an upper bound 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 an upper bound 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/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/organizations/llm-connections:
get:
description: >-
Get all organization-level LLM connections. Requires an
organization-scoped API key.
operationId: llmConnections_listOrganization
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 organization-level LLM connection. The connection is
upserted on provider and inherited by projects without a provider
override. Requires an organization-scoped API key.
operationId: llmConnections_upsertOrganization
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/organizations/llm-connections/{id}:
delete:
description: >-
Delete an organization-level LLM connection by id. Evaluators in
projects without an override for the provider are automatically paused.
Requires an organization-scoped API key.
operationId: llmConnections_deleteOrganization
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. The `limit` parameter is a
maximum: a page may contain
fewer items than the requested limit, including zero items, while
`meta.cursor` is present.
Continue requesting pages until `meta.cursor` is absent.
Requests without a lower start-time bound may search only from January
1, 2020.
## 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: >-
Maximum number of items to return per page. A page may contain fewer
items, including zero items, while meta.cursor is present. 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. Deleting the AI Gateway ingestion
project turns off the AI Gateway for the organization until another
ingestion project is selected.
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:
name:
type: string
nullable: true
description: >-
Optional name for the API key. Cannot be provided together
with note, even if either value is an empty string.
note:
type: string
nullable: true
description: >-
Deprecated alias for name. Cannot be provided together with
name, even if either value is an empty string.
deprecated: true
expiresAt:
type: string
format: date-time
nullable: true
description: >-
Optional expiration timestamp in ISO 8601 format. Must be in
the future. Omit or set to null for a key that does not
expire.
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.
deprecated: true
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/scores:
post:
description: >-
Create scores asynchronously from a list of scores. Returns 202 if all
scores are accepted, or 207 with accepted/rejected counts and error
messages. Do not automatically retry a 207 batch. The generated
reference shows only 200; the endpoint returns 202 or 207.
operationId: scores_create
tags:
- Scores
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoresResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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/CreateScoresRequest'
/api/public/scores/{scoreId}:
delete:
description: Delete a score (supports both trace and session scores)
operationId: scores_delete
tags:
- Scores
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/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: scores_getMany
tags:
- Scores
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/skills:
get:
description: >-
List skills with metadata and timestamps from their latest version,
shared tags, and the version assigned to production when present.
operationId: skills_list
tags:
- Skills
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/SkillMetaListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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: skills_createVersion
tags:
- Skills
parameters: []
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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/CreateSkillVersionRequest'
/api/public/skills/{skillName}:
get:
description: >-
Resolve a skill's metadata and file manifest by version or label.
Defaults to the production label. Set includeContent to return file
contents inline, or use each file's sha256Hash with getFileContents.
operationId: skills_get
tags:
- Skills
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
- name: includeContent
in: query
description: Include UTF-8 text content in each file. Defaults to false.
required: false
schema:
type: boolean
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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: skills_update
tags:
- Skills
parameters:
- name: skillName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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/UpdateSkillRequest'
/api/public/skills/files/content:
get:
description: >-
Read a batch of text contents by canonical base64-encoded SHA-256 hashes.
operationId: skills_getFileContents
tags:
- Skills
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/SkillFileContentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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/skills/{skillName}/versions/{skillVersion}:
patch:
description: >-
Replace the labels on a skill version and atomically move them from
other versions.
operationId: skills_setLabels
tags:
- Skills
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/SkillVersion'
'400':
description: ''
content:
application/json:
schema: {}
'401':
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/UpdateSkillLabelsRequest'
delete:
description: >-
Delete one immutable skill version. Unreferenced blobs are retained for
asynchronous cleanup.
operationId: skills_deleteVersion
tags:
- Skills
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/DeleteSkillVersionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security: *ref_0
/api/public/traces/{traceId}:
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:
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/topic-facets:
get:
description: |-
Unstable: Topics is in closed beta. The shape may change without notice.
List the project's Topics facets. Only active facets (attached to the
project's Topics rule, or all facets if the project has no rule) are
returned unless `filter` contains an `active` condition.
`filter` is a JSON array of filter conditions combined with AND.
String matching is case-insensitive. Columns: `id` (stringOptions),
`name` (string, stringOptions), `description` (string), `isBuiltIn`
(boolean), `active` (boolean).
operationId: unstable_topics_listFacets
tags:
- UnstableTopics
parameters:
- name: filter
in: query
description: >-
JSON array of filter conditions, for example
`[{"type":"string","column":"name","operator":"contains","value":"issue"}]`.
required: false
schema:
type: string
nullable: true
- 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`, at most `100`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableTopicFacetList'
'400':
description: ''
content:
application/json:
schema: {}
'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/topic-facets/{facetId}:
get:
description: |-
Unstable: Topics is in closed beta. The shape may change without notice.
Get one Topics facet by id, including inactive facets.
operationId: unstable_topics_getFacet
tags:
- UnstableTopics
parameters:
- name: facetId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableTopicFacet'
'400':
description: ''
content:
application/json:
schema: {}
'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/topics:
get:
description: |-
Unstable: Topics is in closed beta. The shape may change without notice.
List the topics of each active facet's current published map, with
the number of traces currently assigned to each topic in the window.
Retired topics are not listed. `facets` holds per-facet trace counts
by topic status.
The window applies to the trace start time. It defaults to the last
7 days and can span at most 93 days.
`filter` is a JSON array of filter conditions combined with AND.
String matching is case-insensitive. Columns: `facetId`
(stringOptions), `facetName` (string, stringOptions), `id`
(stringOptions), `name` (string, stringOptions). Facet conditions also
restrict `facets`.
operationId: unstable_topics_list
tags:
- UnstableTopics
parameters:
- name: fromTimestamp
in: query
description: >-
Start of the window (trace start time, inclusive). Defaults to 7
days before `toTimestamp`.
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: End of the window (trace start time, exclusive). Defaults to now.
required: false
schema:
type: string
format: date-time
nullable: true
- name: filter
in: query
description: >-
JSON array of filter conditions, for example
`[{"type":"stringOptions","column":"facetName","operator":"any
of","value":["Issues"]}]`.
required: false
schema:
type: string
nullable: true
- name: orderBy
in: query
description: Defaults to `traceCount.desc`.
required: false
schema:
$ref: '#/components/schemas/unstableTopicsOrderBy'
nullable: true
- 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`, at most `100`.
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableTopicList'
'400':
description: ''
content:
application/json:
schema: {}
'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/topics/{topicId}:
get:
description: |-
Unstable: Topics is in closed beta. The shape may change without notice.
Get one topic by its stable id. Topics on the current map are always
found. A retired topic is found while traces in the window are still
assigned to it, with `inCurrentMap: false`.
operationId: unstable_topics_get
tags:
- UnstableTopics
parameters:
- name: topicId
in: path
required: true
schema:
type: string
- name: fromTimestamp
in: query
description: >-
Start of the window used for `traceCount`. Defaults to 7 days before
`toTimestamp`.
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: End of the window used for `traceCount`. Defaults to now.
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/unstableTopicWithStatus'
'400':
description: ''
content:
application/json:
schema: {}
'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
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
- GOOGLE_CLOUD_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
- score_metadata
- score_provenance
description: >-
Field group selecting which columns are included in the export. Applies
to all export sources.
- Observation groups (`core` through `trace_context`) select observation
columns; groups without a counterpart in the legacy data model (e.g.
`trace_context`) are omitted from the legacy observations export.
- Score groups (`score_` prefix) add optional columns to the scores
export. The core score columns (`id`, `timestamp`, `trace_id`, `name`,
`value`, …) are always exported and are not a selectable group; score
groups add columns on top of them. `score_metadata` adds the score
`metadata` column. `score_provenance` adds the references to where a
score came from: `author_user_id`, `config_id`, `queue_id`,
`evaluator_id`, `evaluation_rule_id`, `execution_trace_id`. Score groups
are never selected by default.
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). For GOOGLE_CLOUD_STORAGE with default
credentials, the bucket must be listed in
`LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.
endpoint:
type: string
nullable: true
description: >-
Custom endpoint URL (required for S3_COMPATIBLE type). Ignored for
GOOGLE_CLOUD_STORAGE.
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. Not used by
GOOGLE_CLOUD_STORAGE; pass auto.
accessKeyId:
type: string
nullable: true
description: Access key ID for authentication. Not used for GOOGLE_CLOUD_STORAGE.
secretAccessKey:
type: string
nullable: true
description: >-
Secret access key for authentication (will be encrypted when
stored). When omitted on update, the stored secret is kept, unless
the type changes between GOOGLE_CLOUD_STORAGE and another type.
For GOOGLE_CLOUD_STORAGE, a GCP service account JSON key. On
self-hosted deployments, pass `__GCS_DEFAULT_CREDENTIALS__` instead
to use the deployment's Application Default Credentials; the bucket
must then be listed in `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.
Default credentials are not available on Langfuse Cloud.
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 and score row.
Applies to all export sources; must include the observation `core`
group if provided. Core score columns are always exported; score
groups add columns on top. When omitted on create, all observation
groups are selected and no score groups. 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 and score row. An
empty list is treated as all observation groups and no score groups
during export. Core score columns are always exported.
nextSyncAt:
type: string
format: date-time
nullable: true
lastSyncAt:
type: string
format: date-time
nullable: true
lastError:
type: string
nullable: true
lastErrorAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- projectId
- type
- bucketName
- endpoint
- region
- accessKeyId
- prefix
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
- exportStartDate
- compressed
- exportSource
- exportFieldGroups
- nextSyncAt
- lastSyncAt
- lastError
- lastErrorAt
- createdAt
- updatedAt
BlobStorageIntegrationsResponse:
title: BlobStorageIntegrationsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
required:
- data
BlobStorageSyncStatus:
title: BlobStorageSyncStatus
type: string
enum:
- idle
- running
- queued
- up_to_date
- disabled
- error
description: >-
Sync status of the blob storage integration:
- `disabled` — integration is not enabled
- `error` — last export failed (see `lastError` for details)
- `running` — an export job is currently being processed
- `queued` — next export is overdue (`nextSyncAt` is in the past) and
waiting to be picked up by the worker
- `idle` — enabled but has never exported yet and no export is queued
- `up_to_date` — all available data has been exported; next export is
scheduled for the future
**ETL usage**: poll this endpoint and check for `up_to_date` status.
Compare `lastSyncAt` against your
ETL bookmark to determine if new data is available. Note that exports
run with a 20-minute lag buffer,
so `lastSyncAt` will always be at least 20 minutes behind real-time.
BlobStorageIntegrationStatusResponse:
title: BlobStorageIntegrationStatusResponse
type: object
properties:
id:
type: string
projectId:
type: string
syncStatus:
$ref: '#/components/schemas/BlobStorageSyncStatus'
enabled:
type: boolean
lastSyncAt:
type: string
format: date-time
nullable: true
description: >-
End of the last successfully exported time window. Compare against
your ETL bookmark to determine if new data is available. Null if the
integration has never synced.
nextSyncAt:
type: string
format: date-time
nullable: true
description: When the next export is scheduled. Null if no sync has occurred yet.
lastError:
type: string
nullable: true
description: >-
Raw error message from the storage provider (S3/Azure/GCS) if the
last export failed. Cleared on successful export.
lastErrorAt:
type: string
format: date-time
nullable: true
description: When the last error occurred. Cleared on successful export.
required:
- id
- projectId
- syncStatus
- enabled
- lastSyncAt
- nextSyncAt
- lastError
- lastErrorAt
BlobStorageIntegrationDeletionResponse:
title: BlobStorageIntegrationDeletionResponse
type: object
properties:
message:
type: string
required:
- message
CreateCommentRequest:
title: CreateCommentRequest
type: object
properties:
projectId:
type: string
description: The id of the project to attach the comment to.
objectType:
type: string
description: >-
The type of the object to attach the comment to (trace, observation,
session, prompt).
objectId:
type: string
description: >-
The id of the object to attach the comment to. If this does not
reference a valid existing object, an error will be thrown.
content:
type: string
description: >-
The content of the comment. May include markdown. Currently limited
to 5000 characters.
authorUserId:
type: string
nullable: true
description: >-
The id of the user who created the comment. Must be a member of the
organization that owns the project, otherwise an error will be
thrown.
required:
- projectId
- objectType
- objectId
- content
CreateCommentResponse:
title: CreateCommentResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
GetCommentsResponse:
title: GetCommentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Deprecation:
title: Deprecation
type: object
description: >-
Migration signal returned by deprecated endpoints. Optional fields are
omitted when they have no value.
properties:
message:
type: string
description: >-
Human- and agent-readable summary of the deprecation and its
replacement.
replacement:
type: string
nullable: true
description: >-
The replacement endpoint, e.g. "GET /api/public/v2/observations".
Omitted when the endpoint is being removed without a direct
replacement.
docsUrl:
type: string
nullable: true
description: Link to the migration documentation (markdown), when available.
sunsetAt:
type: string
nullable: true
description: >-
ISO date after which the endpoint may stop working, when a removal
date is committed.
required:
- message
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
description: Score config name. Maximum 80 characters.
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
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
nullable: 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
- 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
version:
type: string
format: date-time
nullable: true
description: >-
When this version of the dataset item became current. Listing
dataset items with a `version` at or after this timestamp returns
this item version, until the item is changed again. Self-hosted
deployments that set
`LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION=false`
update items in place, so there it stays at the item's first write.
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
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
const: in
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
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
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
PaginatedDatasets:
title: PaginatedDatasets
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Dataset'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRequest:
title: CreateDatasetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
metadata:
nullable: true
inputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item inputs. When set, all new
and existing dataset items will be validated against this schema.
expectedOutputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item expected outputs. When set,
all new and existing dataset items will be validated against this
schema.
required:
- name
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
const: NUMERIC
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
const: BOOLEAN
description: Boolean score output.
required:
- dataType
allOf:
- $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
PublicEvaluatorCategoricalScore:
title: PublicEvaluatorCategoricalScore
type: object
properties:
dataType:
type: string
const: CATEGORICAL
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
EvaluationRuleStringObjectFilterOperator:
title: EvaluationRuleStringObjectFilterOperator
type: string
enum:
- '='
- contains
- does not contain
- starts with
- ends with
- is set
- is not set
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/EvaluationRuleStringObjectFilterOperator'
description: Use `is set` / `is not set` to filter on key presence.
value:
type: string
description: >-
Value to compare against. Ignored for `is set` / `is not set`; send
`""`.
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
const: ''
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
const: legacy
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
const: llm_as_judge
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
const: code
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
const: llm_as_judge
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
const: code
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
const: llm_as_judge
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
const: code
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
const: llm_as_judge
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
const: code
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
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. The
array may contain fewer
than the requested `limit` items, or be empty, while a cursor is
present. Continue until the
cursor is absent.
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:
comment:
type: string
nullable: true
description: >-
Present when an empty page has a cursor; continue requesting pages
until the cursor is absent.
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:
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
description: Expiration timestamp. Null if the key does not expire.
lastUsedAt:
type: string
format: date-time
nullable: true
name:
type: string
nullable: true
description: >-
Name of the API key. Contains the same value as note; null if no
name was provided.
note:
type: string
nullable: true
description: Deprecated alias for name. Contains the same value as name.
deprecated: 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
description: Expiration timestamp. Null if the key does not expire.
lastUsedAt:
type: string
format: date-time
nullable: true
name:
type: string
nullable: true
description: >-
Name of the API key. Contains the same value as note; null if no
name was provided.
note:
type: string
nullable: true
description: Deprecated alias for name. Contains the same value as name.
deprecated: 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
expiresAt:
type: string
format: date-time
nullable: true
description: Expiration timestamp. Null if the key does not expire.
publicKey:
type: string
secretKey:
type: string
displaySecretKey:
type: string
name:
type: string
nullable: true
description: >-
Name of the API key. Contains the same value as note; null if no
name was provided.
note:
type: string
nullable: true
description: Deprecated alias for name. Contains the same value as name.
deprecated: 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
description: >-
The full prompt name, including any folder path, with at most 255
characters.
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
description: >-
The full prompt name, including any folder path, with at most 255
characters.
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 80 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 80 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
CreateScoresRequest:
title: CreateScoresRequest
type: array
items:
$ref: '#/components/schemas/CreateScoreRequest'
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.
timestamp:
type: string
format: date-time
nullable: true
description: >-
The timestamp of the score, as an ISO 8601 datetime with a timezone
offset. Defaults to the time the request is received. To update an
existing score, send it again with the same id and timestamp.
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.
CreateScoresResponse:
title: CreateScoresResponse
oneOf:
- $ref: '#/components/schemas/CreateScoreBatchResults'
- $ref: '#/components/schemas/CreateScoreBatchResponse'
CreateScoreBatchResponse:
title: CreateScoreBatchResponse
type: object
description: Batch accepted (HTTP 202).
properties:
message:
type: string
const: Accepted
required:
- message
CreateScoreBatchResults:
title: CreateScoreBatchResults
type: object
description: Acceptance counts and errors (HTTP 207).
properties:
accepted:
type: integer
rejected:
type: integer
errors:
type: array
items:
$ref: '#/components/schemas/CreateScoreBatchError'
required:
- accepted
- rejected
- errors
CreateScoreBatchError:
title: CreateScoreBatchError
type: object
properties:
message:
type: string
required:
- message
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
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
SkillMetaListResponse:
title: SkillMetaListResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SkillMeta'
meta:
$ref: '#/components/schemas/SkillListPagination'
required:
- data
- meta
SkillListPagination:
title: SkillListPagination
type: object
properties:
hasNextPage:
type: boolean
required:
- hasNextPage
allOf:
- $ref: '#/components/schemas/utilsMetaResponse'
SkillMeta:
title: SkillMeta
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
SkillVersionFileInput:
title: SkillVersionFileInput
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
SkillVersionFileReference:
title: SkillVersionFileReference
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
SkillVersionFileCreateInput:
title: SkillVersionFileCreateInput
oneOf:
- $ref: '#/components/schemas/SkillVersionFileInput'
- $ref: '#/components/schemas/SkillVersionFileReference'
description: Provide exactly one of content or sha256Hash for each path.
CreateSkillVersionRequest:
title: CreateSkillVersionRequest
type: object
properties:
files:
type: array
items:
$ref: '#/components/schemas/SkillVersionFileCreateInput'
commitMessage:
type: string
nullable: true
required:
- files
SkillFile:
title: SkillFile
type: object
properties:
id:
type: string
path:
type: string
blobId:
type: string
sha256Hash:
type: string
contentType:
type: string
contentLength:
type: integer
format: int64
content:
type: string
nullable: true
description: >-
UTF-8 text content, included when fetching a skill with
includeContent enabled.
required:
- id
- path
- blobId
- sha256Hash
- contentType
- contentLength
SkillFileContentsResponse:
title: SkillFileContentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/SkillFileContent'
required:
- data
SkillFileContent:
title: SkillFileContent
type: object
properties:
sha256Hash:
type: string
content:
type: string
required:
- sha256Hash
- content
SkillVersion:
title: SkillVersion
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/SkillFile'
required:
- id
- createdAt
- updatedAt
- projectId
- createdBy
- name
- description
- frontmatter
- version
- tags
- labels
- commitMessage
- files
UpdateSkillRequest:
title: UpdateSkillRequest
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
UpdateSkillLabelsRequest:
title: UpdateSkillLabelsRequest
type: object
properties:
labels:
type: array
items:
type: string
required:
- labels
DeleteSkillVersionResponse:
title: DeleteSkillVersionResponse
type: object
properties:
deleted:
type: boolean
required:
- deleted
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
properties:
message:
type: string
required:
- message
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
unstableTopicsOrderBy:
title: unstableTopicsOrderBy
type: string
enum:
- traceCount.desc
- traceCount.asc
- name.asc
- name.desc
unstableTopicFacetPublishedRun:
title: unstableTopicFacetPublishedRun
type: object
properties:
id:
type: string
completedAt:
type: string
format: date-time
nullable: true
topicCount:
type: integer
required:
- id
- topicCount
unstableTopicFacet:
title: unstableTopicFacet
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
isBuiltIn:
type: boolean
active:
type: boolean
description: >-
Whether the facet is attached to the project's Topics rule. True for
all facets if the project has no rule.
version:
type: integer
description: Latest facet version.
prompt:
type: string
description: Prompt of the latest facet version.
publishedRun:
$ref: '#/components/schemas/unstableTopicFacetPublishedRun'
nullable: true
description: >-
The run that produced the facet's current map. Null before the first
map.
required:
- id
- name
- description
- isBuiltIn
- active
- version
- prompt
unstableTopicFacetList:
title: unstableTopicFacetList
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/unstableTopicFacet'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
unstableTopicFacetRef:
title: unstableTopicFacetRef
type: object
properties:
id:
type: string
name:
type: string
version:
type: integer
required:
- id
- name
- version
unstableTopicWindow:
title: unstableTopicWindow
type: object
properties:
from:
type: string
format: date-time
to:
type: string
format: date-time
required:
- from
- to
unstableTopic:
title: unstableTopic
type: object
properties:
id:
type: string
description: Stable topic id, kept across map updates.
versionId:
type: string
description: Id of this topic version.
name:
type: string
description:
type: string
facet:
$ref: '#/components/schemas/unstableTopicFacetRef'
runId:
type: string
description: The run that produced this topic version.
traceCount:
type: integer
description: >-
Traces in the window whose current result for the facet is this
topic.
required:
- id
- versionId
- name
- description
- facet
- runId
- traceCount
unstableTopicWithStatus:
title: unstableTopicWithStatus
type: object
properties:
inCurrentMap:
type: boolean
description: >-
False for retired topics that still have assigned traces in the
window.
window:
$ref: '#/components/schemas/unstableTopicWindow'
required:
- inCurrentMap
- window
allOf:
- $ref: '#/components/schemas/unstableTopic'
unstableTopicStatusCounts:
title: unstableTopicStatusCounts
type: object
description: Traces in the window by their current result for one facet.
properties:
assigned:
type: integer
outlier:
type: integer
awaitingMap:
type: integer
notApplicable:
type: integer
insufficientInput:
type: integer
required:
- assigned
- outlier
- awaitingMap
- notApplicable
- insufficientInput
unstableTopicFacetCounts:
title: unstableTopicFacetCounts
type: object
properties:
facet:
$ref: '#/components/schemas/unstableTopicFacetRef'
publishedRunId:
type: string
nullable: true
counts:
$ref: '#/components/schemas/unstableTopicStatusCounts'
required:
- facet
- counts
unstableTopicList:
title: unstableTopicList
type: object
properties:
window:
$ref: '#/components/schemas/unstableTopicWindow'
data:
type: array
items:
$ref: '#/components/schemas/unstableTopic'
facets:
type: array
items:
$ref: '#/components/schemas/unstableTopicFacetCounts'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- window
- data
- facets
- meta
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