pentagi
GitHubFully autonomous AI Agents system capable of performing complex penetration testing tasks
pentagi Specification
Located in backend/fern/langfuse/openapi.yml on branch HEAD
3.x (YAML)
YAML
289.0 KB
Raw YAML Specification
openapi: 3.0.1
info:
title: langfuse
version: ''
description: >-
## Authentication
Authenticate with the API using [Basic
Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API
keys in the project settings:
- username: Langfuse Public Key
- password: Langfuse Secret Key
## Exports
- OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml
- Postman collection:
https://cloud.langfuse.com/generated/postman/collection.json
paths:
/api/public/annotation-queues:
get:
description: Get all annotation queues
operationId: annotationQueues_listQueues
tags:
- AnnotationQueues
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueues'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create an annotation queue
operationId: annotationQueues_createQueue
tags:
- AnnotationQueues
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueRequest'
/api/public/annotation-queues/{queueId}:
get:
description: Get an annotation queue by ID
operationId: annotationQueues_getQueue
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueue'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/annotation-queues/{queueId}/items:
get:
description: Get items for a specific annotation queue
operationId: annotationQueues_listQueueItems
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: status
in: query
description: Filter by status
required: false
schema:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedAnnotationQueueItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Add an item to an annotation queue
operationId: annotationQueues_createQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueItemRequest'
/api/public/annotation-queues/{queueId}/items/{itemId}:
get:
description: Get a specific item from an annotation queue
operationId: annotationQueues_getQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Update an annotation queue item
operationId: annotationQueues_updateQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAnnotationQueueItemRequest'
delete:
description: Remove an item from an annotation queue
operationId: annotationQueues_deleteQueueItem
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
- name: itemId
in: path
description: The unique identifier of the annotation queue item
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/annotation-queues/{queueId}/assignments:
post:
description: Create an assignment for a user to an annotation queue
operationId: annotationQueues_createQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
delete:
description: Delete an assignment for a user to an annotation queue
operationId: annotationQueues_deleteQueueAssignment
tags:
- AnnotationQueues
parameters:
- name: queueId
in: path
description: The unique identifier of the annotation queue
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AnnotationQueueAssignmentRequest'
/api/public/integrations/blob-storage:
get:
description: >-
Get all blob storage integrations for the organization (requires
organization-scoped API key)
operationId: blobStorageIntegrations_getBlobStorageIntegrations
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a blob storage integration for a specific project
(requires organization-scoped API key). The configuration is validated
by performing a test upload to the bucket.
operationId: blobStorageIntegrations_upsertBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBlobStorageIntegrationRequest'
/api/public/integrations/blob-storage/{id}:
delete:
description: >-
Delete a blob storage integration by ID (requires organization-scoped
API key)
operationId: blobStorageIntegrations_deleteBlobStorageIntegration
tags:
- BlobStorageIntegrations
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/comments:
post:
description: >-
Create a comment. Comments may be attached to different object types
(trace, observation, session, prompt).
operationId: comments_create
tags:
- Comments
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCommentRequest'
get:
description: Get all comments
operationId: comments_get
tags:
- Comments
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
- name: objectType
in: query
description: >-
Filter comments by object type (trace, observation, session,
prompt).
required: false
schema:
type: string
nullable: true
- name: objectId
in: query
description: >-
Filter comments by object id. If objectType is not provided, an
error will be thrown.
required: false
schema:
type: string
nullable: true
- name: authorUserId
in: query
description: Filter comments by author user id.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetCommentsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/comments/{commentId}:
get:
description: Get a comment by id
operationId: comments_get-by-id
tags:
- Comments
parameters:
- name: commentId
in: path
description: The unique langfuse identifier of a comment
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-items:
post:
description: Create a dataset item
operationId: datasetItems_create
tags:
- DatasetItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetItemRequest'
get:
description: Get dataset items
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: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-items/{id}:
get:
description: Get a dataset item
operationId: datasetItems_get
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete a dataset item and all its run items. This action is
irreversible.
operationId: datasetItems_delete
tags:
- DatasetItems
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetItemResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/dataset-run-items:
post:
description: Create a dataset run item
operationId: datasetRunItems_create
tags:
- DatasetRunItems
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunItem'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRunItemRequest'
get:
description: List dataset run items
operationId: datasetRunItems_list
tags:
- DatasetRunItems
parameters:
- name: datasetId
in: query
required: true
schema:
type: string
- name: runName
in: query
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRunItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/datasets:
get:
description: Get all datasets
operationId: datasets_list
tags:
- Datasets
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasets'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a dataset
operationId: datasets_create
tags:
- Datasets
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDatasetRequest'
/api/public/v2/datasets/{datasetName}:
get:
description: Get a dataset
operationId: datasets_get
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Dataset'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/datasets/{datasetName}/runs/{runName}:
get:
description: Get a dataset run and its items
operationId: datasets_getRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DatasetRunWithItems'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete a dataset run and all its run items. This action is irreversible.
operationId: datasets_deleteRun
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: runName
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDatasetRunResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/datasets/{datasetName}/runs:
get:
description: Get dataset runs
operationId: datasets_getRuns
tags:
- Datasets
parameters:
- name: datasetName
in: path
required: true
schema:
type: string
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedDatasetRuns'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/health:
get:
description: Check health of API and database
operationId: health_health
tags:
- Health
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/HealthResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
'503':
description: ''
/api/public/ingestion:
post:
description: >-
**Legacy endpoint for batch ingestion for Langfuse Observability.**
-> Please use the OpenTelemetry endpoint (`/api/public/otel/v1/traces`).
Learn more: https://langfuse.com/integrations/native/opentelemetry
Within each batch, there can be multiple events.
Each event has a type, an id, a timestamp, metadata and a body.
Internally, we refer to this as the "event envelope" as it tells us
something about the event but not the trace.
We use the event id within this envelope to deduplicate messages to
avoid processing the same event twice, i.e. the event id should be
unique per request.
The event.body.id is the ID of the actual trace and will be used for
updates and will be visible within the Langfuse App.
I.e. if you want to update a trace, you'd use the same body id, but
separate event IDs.
Notes:
- Introduction to data model:
https://langfuse.com/docs/observability/data-model
- Batch sizes are limited to 3.5 MB in total. You need to adjust the
number of events per batch accordingly.
- The API does not return a 4xx status code for input errors. Instead,
it responds with a 207 status code, which includes a list of the
encountered errors.
operationId: ingestion_batch
tags:
- Ingestion
parameters: []
responses:
default:
description: 'Batch ingestion response with status information for each event'
content:
application/json:
schema:
$ref: '#/components/schemas/IngestionResponse'
examples:
Example1:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
Example2:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
Example3:
value:
successes:
- id: abcdef-1234-5678-90ab
status: 201
errors: []
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
batch:
type: array
items:
$ref: '#/components/schemas/IngestionEvent'
description: >-
Batch of tracing events to be ingested. Discriminated by
attribute `type`.
metadata:
nullable: true
description: >-
Optional. Metadata field used by the Langfuse SDKs for
debugging.
required:
- batch
examples:
Example1:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: trace-create
body:
id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
environment: production
name: My Trace
userId: 1234-5678-90ab-cdef
input: My input
output: My output
sessionId: 1234-5678-90ab-cdef
release: 1.0.0
version: 1.0.0
metadata: My metadata
tags:
- tag1
- tag2
public: true
Example2:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: span-create
body:
id: abcdef-1234-5678-90ab
traceId: 1234-5678-90ab-cdef
startTime: '2022-01-01T00:00:00.000Z'
environment: test
Example3:
value:
batch:
- id: abcdef-1234-5678-90ab
timestamp: '2022-01-01T00:00:00.000Z'
type: score-create
body:
id: abcdef-1234-5678-90ab
traceId: 1234-5678-90ab-cdef
name: My Score
value: 0.9
environment: default
/api/public/llm-connections:
get:
description: Get all LLM connections in a project
operationId: llmConnections_list
tags:
- LlmConnections
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedLlmConnections'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update an LLM connection. The connection is upserted on
provider.
operationId: llmConnections_upsert
tags:
- LlmConnections
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/LlmConnection'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertLlmConnectionRequest'
/api/public/media/{mediaId}:
get:
description: Get a media record
operationId: media_get
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Patch a media record
operationId: media_patch
tags:
- Media
parameters:
- name: mediaId
in: path
description: The unique langfuse identifier of a media record
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchMediaBody'
/api/public/media:
post:
description: Get a presigned upload URL for a media record
operationId: media_getUploadUrl
tags:
- Media
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetMediaUploadUrlRequest'
/api/public/v2/metrics:
get:
description: >-
Get metrics from the Langfuse project using a query object. V2 endpoint
with optimized performance.
## V2 Differences
- Supports `observations`, `scores-numeric`, and `scores-categorical`
views only (traces view not supported)
- Direct access to tags and release fields on observations
- Backwards-compatible: traceName, traceRelease, traceVersion dimensions
are still available on observations view
- High cardinality dimensions are not supported and will return a 400
error (see below)
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
## Available Views
### observations
Query observation-level data (spans, generations, events).
**Dimensions:**
- `environment` - Deployment environment (e.g., production, staging)
- `type` - Type of observation (SPAN, GENERATION, EVENT)
- `name` - Name of the observation
- `level` - Logging level of the observation
- `version` - Version of the observation
- `tags` - User-defined tags
- `release` - Release version
- `traceName` - Name of the parent trace (backwards-compatible)
- `traceRelease` - Release version of the parent trace
(backwards-compatible, maps to release)
- `traceVersion` - Version of the parent trace (backwards-compatible,
maps to version)
- `providedModelName` - Name of the model used
- `promptName` - Name of the prompt used
- `promptVersion` - Version of the prompt used
- `startTimeMonth` - Month of start_time in YYYY-MM format
**Measures:**
- `count` - Total number of observations
- `latency` - Observation latency (milliseconds)
- `streamingLatency` - Generation latency from completion start to end
(milliseconds)
- `inputTokens` - Sum of input tokens consumed
- `outputTokens` - Sum of output tokens produced
- `totalTokens` - Sum of all tokens consumed
- `outputTokensPerSecond` - Output tokens per second
- `tokensPerSecond` - Total tokens per second
- `inputCost` - Input cost (USD)
- `outputCost` - Output cost (USD)
- `totalCost` - Total cost (USD)
- `timeToFirstToken` - Time to first token (milliseconds)
- `countScores` - Number of scores attached to the observation
### scores-numeric
Query numeric and boolean score data.
**Dimensions:**
- `environment` - Deployment environment
- `name` - Name of the score (e.g., accuracy, toxicity)
- `source` - Origin of the score (API, ANNOTATION, EVAL)
- `dataType` - Data type (NUMERIC, BOOLEAN)
- `configId` - Identifier of the score config
- `timestampMonth` - Month in YYYY-MM format
- `timestampDay` - Day in YYYY-MM-DD format
- `value` - Numeric value of the score
- `traceName` - Name of the parent trace
- `tags` - Tags
- `traceRelease` - Release version
- `traceVersion` - Version
- `observationName` - Name of the associated observation
- `observationModelName` - Model name of the associated observation
- `observationPromptName` - Prompt name of the associated observation
- `observationPromptVersion` - Prompt version of the associated
observation
**Measures:**
- `count` - Total number of scores
- `value` - Score value (for aggregations)
### scores-categorical
Query categorical score data. Same dimensions as scores-numeric except
uses `stringValue` instead of `value`.
**Measures:**
- `count` - Total number of scores
## High Cardinality Dimensions
The following dimensions cannot be used as grouping dimensions in v2
metrics API as they can cause performance issues.
Use them in filters instead.
**observations view:**
- `id` - Use traceId filter to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `parentObservationId` - Use parentObservationId filter instead
**scores-numeric / scores-categorical views:**
- `id` - Use specific filters to narrow down results
- `traceId` - Use traceId filter instead
- `userId` - Use userId filter instead
- `sessionId` - Use sessionId filter instead
- `observationId` - Use observationId filter instead
## Aggregations
Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,
`p50`, `p75`, `p90`, `p95`, `p99`, `histogram`
## Time Granularities
Available granularities for timeDimension: `auto`, `minute`, `hour`,
`day`, `week`, `month`
- `auto` bins the data into approximately 50 buckets based on the time
range
operationId: metricsV2_metrics
tags:
- MetricsV2
parameters:
- name: query
in: query
description: >-
JSON string containing the query parameters with the following
structure:
```json
{
"view": string, // Required. One of "observations", "scores-numeric", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by (see available dimensions above)
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure (see available measures above)
"aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on (any dimension field)
"operator": string, // Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject/numberObject: same as string/number with required "key"
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Value to compare against
"type": string, // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"key": string // Required only for stringObject/numberObject types (e.g., metadata filtering)
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "auto", "minute", "hour", "day", "week", "month"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range (must be after fromTimestamp)
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by (dimension or metric alias)
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram aggregation (1-100), default: 10
"row_limit": number // Optional. Maximum number of rows to return (1-1000), default: 100
}
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/metrics:
get:
description: >-
Get metrics from the Langfuse project using a query object.
Consider using the [v2 metrics
endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for
better performance.
For more details, see the [Metrics API
documentation](https://langfuse.com/docs/metrics/features/metrics-api).
operationId: 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 "traces", "observations", "scores-numeric", "scores-categorical"
"dimensions": [ // Optional. Default: []
{
"field": string // Field to group by, e.g. "name", "userId", "sessionId"
}
],
"metrics": [ // Required. At least one metric must be provided
{
"measure": string, // What to measure, e.g. "count", "latency", "value"
"aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram"
}
],
"filters": [ // Optional. Default: []
{
"column": string, // Column to filter on
"operator": string, // Operator, e.g. "=", ">", "<", "contains"
"value": any, // Value to compare against
"type": string, // Data type, e.g. "string", "number", "stringObject"
"key": string // Required only when filtering on metadata
}
],
"timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
"granularity": string // One of "minute", "hour", "day", "week", "month", "auto"
},
"fromTimestamp": string, // Required. ISO datetime string for start of time range
"toTimestamp": string, // Required. ISO datetime string for end of time range
"orderBy": [ // Optional. Default: null
{
"field": string, // Field to order by
"direction": string // "asc" or "desc"
}
],
"config": { // Optional. Query-specific configuration
"bins": number, // Optional. Number of bins for histogram (1-100), default: 10
"row_limit": number // Optional. Row limit for results (1-1000)
}
}
```
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/models:
post:
description: Create a model
operationId: models_create
tags:
- Models
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateModelRequest'
get:
description: Get all models
operationId: models_list
tags:
- Models
parameters:
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedModels'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/models/{id}:
get:
description: Get a model
operationId: models_get
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Model'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete a model. Cannot delete models managed by Langfuse. You can create
your own definition with the same modelName to override the definition
though.
operationId: models_delete
tags:
- Models
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/observations:
get:
description: >-
Get a list of observations with cursor-based pagination and flexible
field selection.
## Cursor-based Pagination
This endpoint uses cursor-based pagination for efficient traversal of
large datasets.
The cursor is returned in the response metadata and should be passed in
subsequent requests
to retrieve the next page of results.
## Field Selection
Use the `fields` parameter to control which observation fields are
returned:
- `core` - Always included: id, traceId, startTime, endTime, projectId,
parentObservationId, type
- `basic` - name, level, statusMessage, version, environment,
bookmarked, public, userId, sessionId
- `time` - completionStartTime, createdAt, updatedAt
- `io` - input, output
- `metadata` - metadata (truncated to 200 chars by default, use
`expandMetadata` to get full values)
- `model` - providedModelName, internalModelId, modelParameters
- `usage` - usageDetails, costDetails, totalCost
- `prompt` - promptId, promptName, promptVersion
- `metrics` - latency, timeToFirstToken
If not specified, `core` and `basic` field groups are returned.
## Filters
Multiple filtering options are available via query parameters or the
structured `filter` parameter.
When using the `filter` parameter, it takes precedence over individual
query parameter filters.
operationId: observationsV2_getMany
tags:
- ObservationsV2
parameters:
- name: fields
in: query
description: >-
Comma-separated list of field groups to include in the response.
Available groups: core, basic, time, io, metadata, model, usage,
prompt, metrics.
If not specified, `core` and `basic` field groups are returned.
Example: "basic,usage,model"
required: false
schema:
type: string
nullable: true
- name: expandMetadata
in: query
description: |-
Comma-separated list of metadata keys to return non-truncated.
By default, metadata values over 200 characters are truncated.
Use this parameter to retrieve full values for specific keys.
Example: "key1,key2"
required: false
schema:
type: string
nullable: true
- name: limit
in: query
description: Number of items to return per page. Maximum 1000, default 50.
required: false
schema:
type: integer
nullable: true
- name: cursor
in: query
description: >-
Base64-encoded cursor for pagination. Use the cursor from the
previous response to get the next page.
required: false
schema:
type: string
nullable: true
- name: parseIoAsJson
in: query
description: >-
Set to `true` to parse input/output fields as JSON, or `false` to
return raw strings.
Defaults to `false` if not provided.
required: false
schema:
type: boolean
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: type
in: query
description: >-
Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
"AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
"GUARDRAIL")
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
required: false
schema:
type: string
nullable: true
- name: level
in: query
description: >-
Optional filter for observations with a specific level (e.g.
"DEBUG", "DEFAULT", "WARNING", "ERROR").
required: false
schema:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
- name: parentObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for observations where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fromStartTime
in: query
description: >-
Retrieve only observations with a start_time on or after this
datetime (ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: toStartTime
in: query
description: >-
Retrieve only observations with a start_time before this datetime
(ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: version
in: query
description: Optional filter to only include observations with a certain version.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
type, level, environment, fromStartTime, ...).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
### Trace-Related Fields
- `traceName` (string) - Name of the parent trace
- `traceTags` (arrayOptions) - Tags from the parent trace
- `tags` (arrayOptions) - Alias for traceTags
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name (alias:
`providedModelName`)
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsV2Response'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/observations/{observationId}:
get:
description: Get a observation
operationId: observations_get
tags:
- Observations
parameters:
- name: observationId
in: path
description: >-
The unique langfuse identifier of an observation, can be an event,
span or generation
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsView'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/observations:
get:
description: >-
Get a list of observations.
Consider using the [v2 observations
endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations)
for cursor-based pagination and field selection.
operationId: observations_getMany
tags:
- Observations
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: type
in: query
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
required: false
schema:
type: string
nullable: true
- name: level
in: query
description: >-
Optional filter for observations with a specific level (e.g.
"DEBUG", "DEFAULT", "WARNING", "ERROR").
required: false
schema:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
- name: parentObservationId
in: query
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for observations where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fromStartTime
in: query
description: >-
Retrieve only observations with a start_time on or after this
datetime (ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: toStartTime
in: query
description: >-
Retrieve only observations with a start_time before this datetime
(ISO 8601).
required: false
schema:
type: string
format: date-time
nullable: true
- name: version
in: query
description: Optional filter to only include observations with a certain version.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
type, level, environment, fromStartTime, ...).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Observation Fields
- `id` (string) - Observation ID
- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
- `name` (string) - Observation name
- `traceId` (string) - Associated trace ID
- `startTime` (datetime) - Observation start time
- `endTime` (datetime) - Observation end time
- `environment` (string) - Environment tag
- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
- `statusMessage` (string) - Status message
- `version` (string) - Version tag
### Performance Metrics
- `latency` (number) - Latency in seconds (calculated: end_time -
start_time)
- `timeToFirstToken` (number) - Time to first token in seconds
- `tokensPerSecond` (number) - Output tokens per second
### Token Usage
- `inputTokens` (number) - Number of input tokens
- `outputTokens` (number) - Number of output tokens
- `totalTokens` (number) - Total tokens (alias: `tokens`)
### Cost Metrics
- `inputCost` (number) - Input cost in USD
- `outputCost` (number) - Output cost in USD
- `totalCost` (number) - Total cost in USD
### Model Information
- `model` (string) - Provided model name
- `promptName` (string) - Associated prompt name
- `promptVersion` (number) - Associated prompt version
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Associated Trace Fields (requires join with traces table)
- `userId` (string) - User ID from associated trace
- `traceName` (string) - Name from associated trace
- `traceEnvironment` (string) - Environment from associated trace
- `traceTags` (arrayOptions) - Tags from associated trace
## Filter Examples
```json
[
{
"type": "string",
"column": "type",
"operator": "=",
"value": "GENERATION"
},
{
"type": "number",
"column": "latency",
"operator": ">=",
"value": 2.5
},
{
"type": "stringObject",
"column": "metadata",
"key": "environment",
"operator": "=",
"value": "production"
}
]
```
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ObservationsViews'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/otel/v1/traces:
post:
description: >-
**OpenTelemetry Traces Ingestion Endpoint**
This endpoint implements the OTLP/HTTP specification for trace
ingestion, providing native OpenTelemetry integration for Langfuse
Observability.
**Supported Formats:**
- Binary Protobuf: `Content-Type: application/x-protobuf`
- JSON Protobuf: `Content-Type: application/json`
- Supports gzip compression via `Content-Encoding: gzip` header
**Specification Compliance:**
- Conforms to [OTLP/HTTP Trace
Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp)
- Implements `ExportTraceServiceRequest` message format
**Documentation:**
- Integration guide:
https://langfuse.com/integrations/native/opentelemetry
- Data model: https://langfuse.com/docs/observability/data-model
operationId: opentelemetry_exportTraces
tags:
- Opentelemetry
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OtelTraceResponse'
examples:
BasicTraceExport:
value: {}
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
resourceSpans:
type: array
items:
$ref: '#/components/schemas/OtelResourceSpan'
description: >-
Array of resource spans containing trace data as defined in
the OTLP specification
required:
- resourceSpans
examples:
BasicTraceExport:
value:
resourceSpans:
- resource:
attributes:
- key: service.name
value:
stringValue: my-service
- key: service.version
value:
stringValue: 1.0.0
scopeSpans:
- scope:
name: langfuse-sdk
version: 2.60.3
spans:
- traceId: 0123456789abcdef0123456789abcdef
spanId: 0123456789abcdef
name: my-operation
kind: 1
startTimeUnixNano: '1747872000000000000'
endTimeUnixNano: '1747872001000000000'
attributes:
- key: langfuse.observation.type
value:
stringValue: generation
status: {}
/api/public/organizations/memberships:
get:
description: >-
Get all memberships for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationMemberships
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a membership for the organization associated with the
API key (requires organization-scoped API key)
operationId: organizations_updateOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_deleteOrganizationMembership
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/projects/{projectId}/memberships:
get:
description: >-
Get all memberships for a specific project (requires organization-scoped
API key)
operationId: organizations_getProjectMemberships
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
put:
description: >-
Create or update a membership for a specific project (requires
organization-scoped API key). The user must already be a member of the
organization.
operationId: organizations_updateProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipRequest'
delete:
description: >-
Delete a membership from a specific project (requires
organization-scoped API key). The user must be a member of the
organization.
operationId: organizations_deleteProjectMembership
tags:
- Organizations
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MembershipDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMembershipRequest'
/api/public/organizations/projects:
get:
description: >-
Get all projects for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationProjects
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationProjectsResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/organizations/apiKeys:
get:
description: >-
Get all API keys for the organization associated with the API key
(requires organization-scoped API key)
operationId: organizations_getOrganizationApiKeys
tags:
- Organizations
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/OrganizationApiKeysResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/projects:
get:
description: >-
Get Project associated with API key (requires project-scoped API key).
You can use GET /api/public/organizations/projects to get all projects
with an organization-scoped key.
operationId: projects_get
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Projects'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a new project (requires organization-scoped API key)
operationId: projects_create
tags:
- Projects
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
description: >-
Number of days to retain data. Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional.
required:
- name
- retention
/api/public/projects/{projectId}:
put:
description: Update a project by ID (requires organization-scoped API key).
operationId: projects_update
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
description: Optional metadata for the project
retention:
type: integer
nullable: true
description: |-
Number of days to retain data.
Must be 0 or at least 3 days.
Requires data-retention entitlement for non-zero values.
Optional. Will retain existing retention setting if omitted.
required:
- name
delete:
description: >-
Delete a project by ID (requires organization-scoped API key). Project
deletion is processed asynchronously.
operationId: projects_delete
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'202':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/projects/{projectId}/apiKeys:
get:
description: Get all API keys for a project (requires organization-scoped API key)
operationId: projects_getApiKeys
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyList'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: >-
Create a new API key for a project (requires organization-scoped API
key)
operationId: projects_createApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
nullable: true
description: Optional note for the API key
publicKey:
type: string
nullable: true
description: >-
Optional predefined public key. Must start with 'pk-lf-'. If
provided, secretKey must also be provided.
secretKey:
type: string
nullable: true
description: >-
Optional predefined secret key. Must start with 'sk-lf-'. If
provided, publicKey must also be provided.
/api/public/projects/{projectId}/apiKeys/{apiKeyId}:
delete:
description: Delete an API key for a project (requires organization-scoped API key)
operationId: projects_deleteApiKey
tags:
- Projects
parameters:
- name: projectId
in: path
required: true
schema:
type: string
- name: apiKeyId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiKeyDeletionResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/prompts/{name}/versions/{version}:
patch:
description: Update labels for a specific prompt version
operationId: promptVersion_update
tags:
- PromptVersion
parameters:
- name: name
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: path
description: Version of the prompt to update
required: true
schema:
type: integer
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
newLabels:
type: array
items:
type: string
description: >-
New labels for the prompt version. Labels are unique across
versions. The "latest" label is reserved and managed by
Langfuse.
required:
- newLabels
/api/public/v2/prompts/{promptName}:
get:
description: Get a prompt
operationId: prompts_get
tags:
- Prompts
parameters:
- name: promptName
in: path
description: >-
The name of the prompt. If the prompt is in a folder (e.g.,
"folder/subfolder/prompt-name"),
the folder path must be URL encoded.
required: true
schema:
type: string
- name: version
in: query
description: Version of the prompt to be retrieved.
required: false
schema:
type: integer
nullable: true
- name: label
in: query
description: >-
Label of the prompt to be retrieved. Defaults to "production" if no
label or version is set.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Delete prompt versions. If neither version nor label is specified, all
versions of the prompt are deleted.
operationId: prompts_delete
tags:
- Prompts
parameters:
- name: promptName
in: path
description: The name of the prompt
required: true
schema:
type: string
- name: label
in: query
description: >-
Optional label to filter deletion. If specified, deletes all prompt
versions that have this label.
required: false
schema:
type: string
nullable: true
- name: version
in: query
description: >-
Optional version to filter deletion. If specified, deletes only this
specific version of the prompt.
required: false
schema:
type: integer
nullable: true
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/prompts:
get:
description: Get a list of prompt names with versions and labels
operationId: prompts_list
tags:
- Prompts
parameters:
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: label
in: query
required: false
schema:
type: string
nullable: true
- name: tag
in: query
required: false
schema:
type: string
nullable: true
- name: page
in: query
description: page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: limit of items per page
required: false
schema:
type: integer
nullable: true
- name: fromUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated on
or after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toUpdatedAt
in: query
description: >-
Optional filter to only include prompt versions created/updated
before a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PromptMetaListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: Create a new version for the prompt with the given `name`
operationId: prompts_create
tags:
- Prompts
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePromptRequest'
/api/public/scim/ServiceProviderConfig:
get:
description: >-
Get SCIM Service Provider Configuration (requires organization-scoped
API key)
operationId: scim_getServiceProviderConfig
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceProviderConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/ResourceTypes:
get:
description: Get SCIM Resource Types (requires organization-scoped API key)
operationId: scim_getResourceTypes
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceTypesResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/Schemas:
get:
description: Get SCIM Schemas (requires organization-scoped API key)
operationId: scim_getSchemas
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SchemasResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scim/Users:
get:
description: List users in the organization (requires organization-scoped API key)
operationId: scim_listUsers
tags:
- Scim
parameters:
- name: filter
in: query
description: Filter expression (e.g. userName eq "value")
required: false
schema:
type: string
nullable: true
- name: startIndex
in: query
description: 1-based index of the first result to return (default 1)
required: false
schema:
type: integer
nullable: true
- name: count
in: query
description: Maximum number of results to return (default 100)
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUsersListResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
post:
description: >-
Create a new user in the organization (requires organization-scoped API
key)
operationId: scim_createUser
tags:
- Scim
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userName:
type: string
description: User's email address (required)
name:
$ref: '#/components/schemas/ScimName'
description: User's name information
emails:
type: array
items:
$ref: '#/components/schemas/ScimEmail'
nullable: true
description: User's email addresses
active:
type: boolean
nullable: true
description: Whether the user is active
password:
type: string
nullable: true
description: Initial password for the user
required:
- userName
- name
/api/public/scim/Users/{userId}:
get:
description: Get a specific user by ID (requires organization-scoped API key)
operationId: scim_getUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScimUser'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: >-
Remove a user from the organization (requires organization-scoped API
key). Note that this only removes the user from the organization but
does not delete the user entity itself.
operationId: scim_deleteUser
tags:
- Scim
parameters:
- name: userId
in: path
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/score-configs:
post:
description: >-
Create a score configuration (config). Score configs are used to define
the structure of scores
operationId: scoreConfigs_create
tags:
- ScoreConfigs
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreConfigRequest'
get:
description: Get all score configs
operationId: scoreConfigs_get
tags:
- ScoreConfigs
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit
required: false
schema:
type: integer
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfigs'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/score-configs/{configId}:
get:
description: Get a score config
operationId: scoreConfigs_get-by-id
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
patch:
description: Update a score config
operationId: scoreConfigs_update
tags:
- ScoreConfigs
parameters:
- name: configId
in: path
description: The unique langfuse identifier of a score config
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ScoreConfig'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScoreConfigRequest'
/api/public/v2/scores:
get:
description: Get a list of scores (supports both trace and session scores)
operationId: scoreV2_get
tags:
- ScoreV2
parameters:
- name: page
in: query
description: Page number, starts at 1.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: userId
in: query
description: Retrieve only scores with this userId associated to the trace.
required: false
schema:
type: string
nullable: true
- name: name
in: query
description: Retrieve only scores with this name.
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include scores created on or after a certain
datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include scores created before a certain
datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: environment
in: query
description: >-
Optional filter for scores where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: source
in: query
description: Retrieve only scores from a specific source.
required: false
schema:
$ref: '#/components/schemas/ScoreSource'
nullable: true
- name: operator
in: query
description: Retrieve only scores with <operator> value.
required: false
schema:
type: string
nullable: true
- name: value
in: query
description: Retrieve only scores with <operator> value.
required: false
schema:
type: number
format: double
nullable: true
- name: scoreIds
in: query
description: Comma-separated list of score IDs to limit the results to.
required: false
schema:
type: string
nullable: true
- name: configId
in: query
description: Retrieve only scores with a specific configId.
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
description: Retrieve only scores with a specific sessionId.
required: false
schema:
type: string
nullable: true
- name: datasetRunId
in: query
description: Retrieve only scores with a specific datasetRunId.
required: false
schema:
type: string
nullable: true
- name: traceId
in: query
description: Retrieve only scores with a specific traceId.
required: false
schema:
type: string
nullable: true
- name: queueId
in: query
description: Retrieve only scores with a specific annotation queueId.
required: false
schema:
type: string
nullable: true
- name: dataType
in: query
description: Retrieve only scores with a specific dataType.
required: false
schema:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
- name: traceTags
in: query
description: >-
Only scores linked to traces that include all of these tags will be
returned.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated list of field groups to include in the response.
Available field groups: 'score' (core score fields), 'trace' (trace
properties: userId, tags, environment). If not specified, both
'score' and 'trace' are returned by default. Example: 'score' to
exclude trace data, 'score,trace' to include both. Note: When
filtering by trace properties (using userId or traceTags
parameters), the 'trace' field group must be included, otherwise a
400 error will be returned.
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetScoresResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/v2/scores/{scoreId}:
get:
description: Get a score (supports both trace and session scores)
operationId: scoreV2_get-by-id
tags:
- ScoreV2
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Score'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/scores:
post:
description: Create a score (supports both trace and session scores)
operationId: score_create
tags:
- Score
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScoreRequest'
/api/public/scores/{scoreId}:
delete:
description: Delete a score (supports both trace and session scores)
operationId: score_delete
tags:
- Score
parameters:
- name: scoreId
in: path
description: The unique langfuse identifier of a score
required: true
schema:
type: string
responses:
'204':
description: ''
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/sessions:
get:
description: Get sessions
operationId: sessions_list
tags:
- Sessions
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include sessions created on or after a
certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include sessions created before a certain
datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: environment
in: query
description: >-
Optional filter for sessions where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSessions'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/sessions/{sessionId}:
get:
description: >-
Get a session. Please note that `traces` on this endpoint are not
paginated, if you plan to fetch large sessions, consider `GET
/api/public/traces?sessionId=<sessionId>`
operationId: sessions_get
tags:
- Sessions
parameters:
- name: sessionId
in: path
description: The unique id of a session
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SessionWithTraces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/traces/{traceId}:
get:
description: Get a specific trace
operationId: trace_get
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of a trace
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/TraceWithFullDetails'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete a specific trace
operationId: trace_delete
tags:
- Trace
parameters:
- name: traceId
in: path
description: The unique langfuse identifier of the trace to delete
required: true
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
/api/public/traces:
get:
description: Get list of traces
operationId: trace_list
tags:
- Trace
parameters:
- name: page
in: query
description: Page number, starts at 1
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
description: >-
Limit of items per page. If you encounter api issues due to too
large page sizes, try to reduce the limit.
required: false
schema:
type: integer
nullable: true
- name: userId
in: query
required: false
schema:
type: string
nullable: true
- name: name
in: query
required: false
schema:
type: string
nullable: true
- name: sessionId
in: query
required: false
schema:
type: string
nullable: true
- name: fromTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp on or
after a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: toTimestamp
in: query
description: >-
Optional filter to only include traces with a trace.timestamp before
a certain datetime (ISO 8601)
required: false
schema:
type: string
format: date-time
nullable: true
- name: orderBy
in: query
description: >-
Format of the string [field].[asc/desc]. Fields: id, timestamp,
name, userId, release, version, public, bookmarked, sessionId.
Example: timestamp.asc
required: false
schema:
type: string
nullable: true
- name: tags
in: query
description: Only traces that include all of these tags will be returned.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: version
in: query
description: Optional filter to only include traces with a certain version.
required: false
schema:
type: string
nullable: true
- name: release
in: query
description: Optional filter to only include traces with a certain release.
required: false
schema:
type: string
nullable: true
- name: environment
in: query
description: >-
Optional filter for traces where the environment is one of the
provided values.
required: false
schema:
type: array
items:
type: string
nullable: true
- name: fields
in: query
description: >-
Comma-separated list of fields to include in the response. Available
field groups: 'core' (always included), 'io' (input, output,
metadata), 'scores', 'observations', 'metrics'. If not specified,
all fields are returned. Example: 'core,scores,metrics'. Note:
Excluded 'observations' or 'scores' fields return empty arrays;
excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
required: false
schema:
type: string
nullable: true
- name: filter
in: query
description: >-
JSON string containing an array of filter conditions. When provided,
this takes precedence over query parameter filters (userId, name,
sessionId, tags, version, release, environment, fromTimestamp,
toTimestamp).
## Filter Structure
Each filter condition has the following structure:
```json
[
{
"type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
"column": string, // Required. Column to filter on (see available columns below)
"operator": string, // Required. Operator based on type:
// - datetime: ">", "<", ">=", "<="
// - string: "=", "contains", "does not contain", "starts with", "ends with"
// - stringOptions: "any of", "none of"
// - categoryOptions: "any of", "none of"
// - arrayOptions: "any of", "none of", "all of"
// - number: "=", ">", "<", ">=", "<="
// - stringObject: "=", "contains", "does not contain", "starts with", "ends with"
// - numberObject: "=", ">", "<", ">=", "<="
// - boolean: "=", "<>"
// - null: "is null", "is not null"
"value": any, // Required (except for null type). Value to compare against. Type depends on filter type
"key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
}
]
```
## Available Columns
### Core Trace Fields
- `id` (string) - Trace ID
- `name` (string) - Trace name
- `timestamp` (datetime) - Trace timestamp
- `userId` (string) - User ID
- `sessionId` (string) - Session ID
- `environment` (string) - Environment tag
- `version` (string) - Version tag
- `release` (string) - Release tag
- `tags` (arrayOptions) - Array of tags
- `bookmarked` (boolean) - Bookmark status
### Structured Data
- `metadata` (stringObject/numberObject/categoryOptions) - Metadata
key-value pairs. Use `key` parameter to filter on specific metadata
keys.
### Aggregated Metrics (from observations)
These metrics are aggregated from all observations within the trace:
- `latency` (number) - Latency in seconds (time from first
observation start to last observation end)
- `inputTokens` (number) - Total input tokens across all
observations
- `outputTokens` (number) - Total output tokens across all
observations
- `totalTokens` (number) - Total tokens (alias: `tokens`)
- `inputCost` (number) - Total input cost in USD
- `outputCost` (number) - Total output cost in USD
- `totalCost` (number) - Total cost in USD
### Observation Level Aggregations
These fields aggregate observation levels within the trace:
- `level` (string) - Highest severity level (ERROR > WARNING >
DEFAULT > DEBUG)
- `warningCount` (number) - Count of WARNING level observations
- `errorCount` (number) - Count of ERROR level observations
- `defaultCount` (number) - Count of DEFAULT level observations
- `debugCount` (number) - Count of DEBUG level observations
### Scores (requires join with scores table)
- `scores_avg` (number) - Average of numeric scores (alias:
`scores`)
- `score_categories` (categoryOptions) - Categorical score values
## Filter Examples
```json
[
{
"type": "datetime",
"column": "timestamp",
"operator": ">=",
"value": "2024-01-01T00:00:00Z"
},
{
"type": "string",
"column": "userId",
"operator": "=",
"value": "user-123"
},
{
"type": "number",
"column": "totalCost",
"operator": ">=",
"value": 0.01
},
{
"type": "arrayOptions",
"column": "tags",
"operator": "all of",
"value": ["production", "critical"]
},
{
"type": "stringObject",
"column": "metadata",
"key": "customer_tier",
"operator": "=",
"value": "enterprise"
}
]
```
## Performance Notes
- Filtering on `userId`, `sessionId`, or `metadata` may enable skip
indexes for better query performance
- Score filters require a join with the scores table and may impact
query performance
required: false
schema:
type: string
nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/Traces'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
delete:
description: Delete multiple traces
operationId: trace_deleteMultiple
tags:
- Trace
parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteTraceResponse'
'400':
description: ''
content:
application/json:
schema: {}
'401':
description: ''
content:
application/json:
schema: {}
'403':
description: ''
content:
application/json:
schema: {}
'404':
description: ''
content:
application/json:
schema: {}
'405':
description: ''
content:
application/json:
schema: {}
security:
- BasicAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
traceIds:
type: array
items:
type: string
description: List of trace IDs to delete
required:
- traceIds
components:
schemas:
AnnotationQueueStatus:
title: AnnotationQueueStatus
type: string
enum:
- PENDING
- COMPLETED
AnnotationQueueObjectType:
title: AnnotationQueueObjectType
type: string
enum:
- TRACE
- OBSERVATION
- SESSION
AnnotationQueue:
title: AnnotationQueue
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- scoreConfigIds
- createdAt
- updatedAt
AnnotationQueueItem:
title: AnnotationQueueItem
type: object
properties:
id:
type: string
queueId:
type: string
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
completedAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- queueId
- objectId
- objectType
- status
- createdAt
- updatedAt
PaginatedAnnotationQueues:
title: PaginatedAnnotationQueues
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueue'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PaginatedAnnotationQueueItems:
title: PaginatedAnnotationQueueItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AnnotationQueueItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateAnnotationQueueRequest:
title: CreateAnnotationQueueRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
scoreConfigIds:
type: array
items:
type: string
required:
- name
- scoreConfigIds
CreateAnnotationQueueItemRequest:
title: CreateAnnotationQueueItemRequest
type: object
properties:
objectId:
type: string
objectType:
$ref: '#/components/schemas/AnnotationQueueObjectType'
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
description: Defaults to PENDING for new queue items
required:
- objectId
- objectType
UpdateAnnotationQueueItemRequest:
title: UpdateAnnotationQueueItemRequest
type: object
properties:
status:
$ref: '#/components/schemas/AnnotationQueueStatus'
nullable: true
DeleteAnnotationQueueItemResponse:
title: DeleteAnnotationQueueItemResponse
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
AnnotationQueueAssignmentRequest:
title: AnnotationQueueAssignmentRequest
type: object
properties:
userId:
type: string
required:
- userId
DeleteAnnotationQueueAssignmentResponse:
title: DeleteAnnotationQueueAssignmentResponse
type: object
properties:
success:
type: boolean
required:
- success
CreateAnnotationQueueAssignmentResponse:
title: CreateAnnotationQueueAssignmentResponse
type: object
properties:
userId:
type: string
queueId:
type: string
projectId:
type: string
required:
- userId
- queueId
- projectId
BlobStorageIntegrationType:
title: BlobStorageIntegrationType
type: string
enum:
- S3
- S3_COMPATIBLE
- AZURE_BLOB_STORAGE
BlobStorageIntegrationFileType:
title: BlobStorageIntegrationFileType
type: string
enum:
- JSON
- CSV
- JSONL
BlobStorageExportMode:
title: BlobStorageExportMode
type: string
enum:
- FULL_HISTORY
- FROM_TODAY
- FROM_CUSTOM_DATE
BlobStorageExportFrequency:
title: BlobStorageExportFrequency
type: string
enum:
- hourly
- daily
- weekly
CreateBlobStorageIntegrationRequest:
title: CreateBlobStorageIntegrationRequest
type: object
properties:
projectId:
type: string
description: ID of the project in which to configure the blob storage integration
type:
$ref: '#/components/schemas/BlobStorageIntegrationType'
bucketName:
type: string
description: Name of the storage bucket
endpoint:
type: string
nullable: true
description: Custom endpoint URL (required for S3_COMPATIBLE type)
region:
type: string
description: Storage region
accessKeyId:
type: string
nullable: true
description: Access key ID for authentication
secretAccessKey:
type: string
nullable: true
description: Secret access key for authentication (will be encrypted when stored)
prefix:
type: string
nullable: true
description: >-
Path prefix for exported files (must end with forward slash if
provided)
exportFrequency:
$ref: '#/components/schemas/BlobStorageExportFrequency'
enabled:
type: boolean
description: Whether the integration is active
forcePathStyle:
type: boolean
description: Use path-style URLs for S3 requests
fileType:
$ref: '#/components/schemas/BlobStorageIntegrationFileType'
exportMode:
$ref: '#/components/schemas/BlobStorageExportMode'
exportStartDate:
type: string
format: date-time
nullable: true
description: >-
Custom start date for exports (required when exportMode is
FROM_CUSTOM_DATE)
required:
- projectId
- type
- bucketName
- region
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
BlobStorageIntegrationResponse:
title: BlobStorageIntegrationResponse
type: object
properties:
id:
type: string
projectId:
type: string
type:
$ref: '#/components/schemas/BlobStorageIntegrationType'
bucketName:
type: string
endpoint:
type: string
nullable: true
region:
type: string
accessKeyId:
type: string
nullable: true
prefix:
type: string
exportFrequency:
$ref: '#/components/schemas/BlobStorageExportFrequency'
enabled:
type: boolean
forcePathStyle:
type: boolean
fileType:
$ref: '#/components/schemas/BlobStorageIntegrationFileType'
exportMode:
$ref: '#/components/schemas/BlobStorageExportMode'
exportStartDate:
type: string
format: date-time
nullable: true
nextSyncAt:
type: string
format: date-time
nullable: true
lastSyncAt:
type: string
format: date-time
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- projectId
- type
- bucketName
- region
- prefix
- exportFrequency
- enabled
- forcePathStyle
- fileType
- exportMode
- createdAt
- updatedAt
BlobStorageIntegrationsResponse:
title: BlobStorageIntegrationsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/BlobStorageIntegrationResponse'
required:
- data
BlobStorageIntegrationDeletionResponse:
title: BlobStorageIntegrationDeletionResponse
type: object
properties:
message:
type: string
required:
- message
CreateCommentRequest:
title: CreateCommentRequest
type: object
properties:
projectId:
type: string
description: The id of the project to attach the comment to.
objectType:
type: string
description: >-
The type of the object to attach the comment to (trace, observation,
session, prompt).
objectId:
type: string
description: >-
The id of the object to attach the comment to. If this does not
reference a valid existing object, an error will be thrown.
content:
type: string
description: >-
The content of the comment. May include markdown. Currently limited
to 5000 characters.
authorUserId:
type: string
nullable: true
description: The id of the user who created the comment.
required:
- projectId
- objectType
- objectId
- content
CreateCommentResponse:
title: CreateCommentResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
GetCommentsResponse:
title: GetCommentsResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Comment'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Trace:
title: Trace
type: object
properties:
id:
type: string
description: The unique identifier of a trace
timestamp:
type: string
format: date-time
description: The timestamp when the trace was created
name:
type: string
nullable: true
description: The name of the trace
input:
nullable: true
description: The input data of the trace. Can be any JSON.
output:
nullable: true
description: The output data of the trace. Can be any JSON.
sessionId:
type: string
nullable: true
description: The session identifier associated with the trace
release:
type: string
nullable: true
description: The release version of the application when the trace was created
version:
type: string
nullable: true
description: The version of the trace
userId:
type: string
nullable: true
description: The user identifier associated with the trace
metadata:
nullable: true
description: The metadata associated with the trace. Can be any JSON.
tags:
type: array
items:
type: string
description: The tags associated with the trace.
public:
type: boolean
description: Public traces are accessible via url without login
environment:
type: string
description: >-
The environment from which this trace originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- timestamp
- tags
- public
- environment
TraceWithDetails:
title: TraceWithDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
type: string
nullable: true
description: List of observation ids
scores:
type: array
items:
type: string
nullable: true
description: List of score ids
required:
- htmlPath
allOf:
- $ref: '#/components/schemas/Trace'
TraceWithFullDetails:
title: TraceWithFullDetails
type: object
properties:
htmlPath:
type: string
description: Path of trace in Langfuse UI
latency:
type: number
format: double
nullable: true
description: Latency of trace in seconds
totalCost:
type: number
format: double
nullable: true
description: Cost of trace in USD
observations:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
description: List of observations
scores:
type: array
items:
$ref: '#/components/schemas/ScoreV1'
description: List of scores
required:
- htmlPath
- observations
- scores
allOf:
- $ref: '#/components/schemas/Trace'
Session:
title: Session
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
projectId:
type: string
environment:
type: string
description: The environment from which this session originated.
required:
- id
- createdAt
- projectId
- environment
SessionWithTraces:
title: SessionWithTraces
type: object
properties:
traces:
type: array
items:
$ref: '#/components/schemas/Trace'
required:
- traces
allOf:
- $ref: '#/components/schemas/Session'
Observation:
title: Observation
type: object
properties:
id:
type: string
description: The unique identifier of the observation
traceId:
type: string
nullable: true
description: The trace ID associated with the observation
type:
type: string
description: The type of the observation
name:
type: string
nullable: true
description: The name of the observation
startTime:
type: string
format: date-time
description: The start time of the observation
endTime:
type: string
format: date-time
nullable: true
description: The end time of the observation.
completionStartTime:
type: string
format: date-time
nullable: true
description: The completion start time of the observation
model:
type: string
nullable: true
description: The model used for the observation
modelParameters:
description: The parameters of the model used for the observation
input:
description: The input data of the observation
version:
type: string
nullable: true
description: The version of the observation
metadata:
description: Additional metadata of the observation
output:
description: The output data of the observation
usage:
$ref: '#/components/schemas/Usage'
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The usage
data of the observation
level:
$ref: '#/components/schemas/ObservationLevel'
description: The level of the observation
statusMessage:
type: string
nullable: true
description: The status message of the observation
parentObservationId:
type: string
nullable: true
description: The parent observation ID
promptId:
type: string
nullable: true
description: The prompt ID associated with the observation
usageDetails:
type: object
additionalProperties:
type: integer
description: >-
The usage details of the observation. Key is the name of the usage
metric, value is the number of units consumed. The total key is the
sum of all (non-total) usage metrics or the total value ingested.
costDetails:
type: object
additionalProperties:
type: number
format: double
description: >-
The cost details of the observation. Key is the name of the cost
metric, value is the cost in USD. The total key is the sum of all
(non-total) cost metrics or the total value ingested.
environment:
type: string
description: >-
The environment from which this observation originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- type
- startTime
- modelParameters
- input
- metadata
- output
- usage
- level
- usageDetails
- costDetails
- environment
ObservationsView:
title: ObservationsView
type: object
properties:
promptName:
type: string
nullable: true
description: The name of the prompt associated with the observation
promptVersion:
type: integer
nullable: true
description: The version of the prompt associated with the observation
modelId:
type: string
nullable: true
description: The unique identifier of the model
inputPrice:
type: number
format: double
nullable: true
description: The price of the input in USD
outputPrice:
type: number
format: double
nullable: true
description: The price of the output in USD.
totalPrice:
type: number
format: double
nullable: true
description: The total price in USD.
calculatedInputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the input in USD
calculatedOutputCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated cost of the output in USD
calculatedTotalCost:
type: number
format: double
nullable: true
description: >-
(Deprecated. Use usageDetails and costDetails instead.) The
calculated total cost in USD
latency:
type: number
format: double
nullable: true
description: The latency in seconds.
timeToFirstToken:
type: number
format: double
nullable: true
description: The time to the first token in seconds
allOf:
- $ref: '#/components/schemas/Observation'
Usage:
title: Usage
type: object
description: >-
(Deprecated. Use usageDetails and costDetails instead.) Standard
interface for usage and cost
properties:
input:
type: integer
description: Number of input units (e.g. tokens)
output:
type: integer
description: Number of output units (e.g. tokens)
total:
type: integer
description: Defaults to input+output if not set
unit:
type: string
nullable: true
description: Unit of measurement
inputCost:
type: number
format: double
nullable: true
description: USD input cost
outputCost:
type: number
format: double
nullable: true
description: USD output cost
totalCost:
type: number
format: double
nullable: true
description: USD total cost, defaults to input+output
required:
- input
- output
- total
ScoreConfig:
title: ScoreConfig
type: object
description: Configuration for a score
properties:
id:
type: string
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
projectId:
type: string
dataType:
$ref: '#/components/schemas/ScoreConfigDataType'
isArchived:
type: boolean
description: Whether the score config is archived. Defaults to false
minValue:
type: number
format: double
nullable: true
description: >-
Sets minimum value for numerical scores. If not set, the minimum
value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Sets maximum value for numerical scores. If not set, the maximum
value defaults to +∞
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: Configures custom categories for categorical scores
description:
type: string
nullable: true
description: Description of the score config
required:
- id
- name
- createdAt
- updatedAt
- projectId
- dataType
- isArchived
ConfigCategory:
title: ConfigCategory
type: object
properties:
value:
type: number
format: double
label:
type: string
required:
- value
- label
BaseScoreV1:
title: BaseScoreV1
type: object
properties:
id:
type: string
traceId:
type: string
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
observationId:
type: string
nullable: true
description: The observation ID associated with the score
timestamp:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
authorUserId:
type: string
nullable: true
description: The user ID of the author
comment:
type: string
nullable: true
description: Comment on the score
metadata:
description: Metadata associated with the score
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, config and score name
must be equal and value must comply to optionally defined numerical
range
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
environment:
type: string
description: >-
The environment from which this score originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- traceId
- name
- source
- timestamp
- createdAt
- updatedAt
- metadata
- environment
NumericScoreV1:
title: NumericScoreV1
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
BooleanScoreV1:
title: BooleanScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for
"False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
CategoricalScoreV1:
title: CategoricalScoreV1
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScoreV1'
ScoreV1:
title: ScoreV1
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScoreV1'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScoreV1'
required:
- dataType
BaseScore:
title: BaseScore
type: object
properties:
id:
type: string
traceId:
type: string
nullable: true
description: The trace ID associated with the score
sessionId:
type: string
nullable: true
description: The session ID associated with the score
observationId:
type: string
nullable: true
description: The observation ID associated with the score
datasetRunId:
type: string
nullable: true
description: The dataset run ID associated with the score
name:
type: string
source:
$ref: '#/components/schemas/ScoreSource'
timestamp:
type: string
format: date-time
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
authorUserId:
type: string
nullable: true
description: The user ID of the author
comment:
type: string
nullable: true
description: Comment on the score
metadata:
description: Metadata associated with the score
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, config and score name
must be equal and value must comply to optionally defined numerical
range
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
environment:
type: string
description: >-
The environment from which this score originated. Can be any
lowercase alphanumeric string with hyphens and underscores that does
not start with 'langfuse'.
required:
- id
- name
- source
- timestamp
- createdAt
- updatedAt
- metadata
- environment
NumericScore:
title: NumericScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score
required:
- value
allOf:
- $ref: '#/components/schemas/BaseScore'
BooleanScore:
title: BooleanScore
type: object
properties:
value:
type: number
format: double
description: >-
The numeric value of the score. Equals 1 for "True" and 0 for
"False"
stringValue:
type: string
description: >-
The string representation of the score value. Is inferred from the
numeric value and equals "True" or "False"
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CategoricalScore:
title: CategoricalScore
type: object
properties:
value:
type: number
format: double
description: >-
Represents the numeric category mapping of the stringValue. If no
config is linked, defaults to 0.
stringValue:
type: string
description: >-
The string representation of the score value. If no config is
linked, can be any string. Otherwise, must map to a config category
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
CorrectionScore:
title: CorrectionScore
type: object
properties:
value:
type: number
format: double
description: The numeric value of the score. Always 0 for correction scores.
stringValue:
type: string
description: The string representation of the correction content
required:
- value
- stringValue
allOf:
- $ref: '#/components/schemas/BaseScore'
Score:
title: Score
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/NumericScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/CategoricalScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/BooleanScore'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/CorrectionScore'
required:
- dataType
CreateScoreValue:
title: CreateScoreValue
oneOf:
- type: number
format: double
- type: string
description: >-
The value of the score. Must be passed as string for categorical scores,
and numeric for boolean and numeric scores
Comment:
title: Comment
type: object
properties:
id:
type: string
projectId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
objectType:
$ref: '#/components/schemas/CommentObjectType'
objectId:
type: string
content:
type: string
authorUserId:
type: string
nullable: true
description: The user ID of the comment author
required:
- id
- projectId
- createdAt
- updatedAt
- objectType
- objectId
- content
Dataset:
title: Dataset
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
nullable: true
description: Description of the dataset
metadata:
description: Metadata associated with the dataset
inputSchema:
nullable: true
description: JSON Schema for validating dataset item inputs
expectedOutputSchema:
nullable: true
description: JSON Schema for validating dataset item expected outputs
projectId:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- metadata
- projectId
- createdAt
- updatedAt
DatasetItem:
title: DatasetItem
type: object
properties:
id:
type: string
status:
$ref: '#/components/schemas/DatasetStatus'
input:
description: Input data for the dataset item
expectedOutput:
description: Expected output for the dataset item
metadata:
description: Metadata associated with the dataset item
sourceTraceId:
type: string
nullable: true
description: The trace ID that sourced this dataset item
sourceObservationId:
type: string
nullable: true
description: The observation ID that sourced this dataset item
datasetId:
type: string
datasetName:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- status
- input
- expectedOutput
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunItem:
title: DatasetRunItem
type: object
properties:
id:
type: string
datasetRunId:
type: string
datasetRunName:
type: string
datasetItemId:
type: string
traceId:
type: string
observationId:
type: string
nullable: true
description: The observation ID associated with this run item
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- datasetRunId
- datasetRunName
- datasetItemId
- traceId
- createdAt
- updatedAt
DatasetRun:
title: DatasetRun
type: object
properties:
id:
type: string
description: Unique identifier of the dataset run
name:
type: string
description: Name of the dataset run
description:
type: string
nullable: true
description: Description of the run
metadata:
description: Metadata of the dataset run
datasetId:
type: string
description: Id of the associated dataset
datasetName:
type: string
description: Name of the associated dataset
createdAt:
type: string
format: date-time
description: The date and time when the dataset run was created
updatedAt:
type: string
format: date-time
description: The date and time when the dataset run was last updated
required:
- id
- name
- metadata
- datasetId
- datasetName
- createdAt
- updatedAt
DatasetRunWithItems:
title: DatasetRunWithItems
type: object
properties:
datasetRunItems:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
required:
- datasetRunItems
allOf:
- $ref: '#/components/schemas/DatasetRun'
Model:
title: Model
type: object
description: >-
Model definition used for transforming usage into USD cost and/or
tokenization.
Models can have either simple flat pricing or tiered pricing:
- Flat pricing: Single price per usage type (legacy, but still
supported)
- Tiered pricing: Multiple pricing tiers with conditional matching based
on usage patterns
The pricing tiers approach is recommended for models with usage-based
pricing variations.
When using tiered pricing, the flat price fields (inputPrice,
outputPrice, prices) are populated
from the default tier for backward compatibility.
properties:
id:
type: string
modelName:
type: string
description: >-
Name of the model definition. If multiple with the same name exist,
they are applied in the following order: (1) custom over built-in,
(2) newest according to startTime where
model.startTime<observation.startTime
matchPattern:
type: string
description: >-
Regex pattern which matches this model definition to
generation.model. Useful in case of fine-tuned models. If you want
to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per input unit
outputPrice:
type: number
format: double
nullable: true
description: Deprecated. See 'prices' instead. Price (USD) per output unit
totalPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot
be set if input or output price is set.
tokenizerId:
type: string
nullable: true
description: >-
Optional. Tokenizer to be applied to observations which match to
this model. See docs for more details.
tokenizerConfig:
description: >-
Optional. Configuration for the selected tokenizer. Needs to be
JSON. See docs for more details.
isLangfuseManaged:
type: boolean
createdAt:
type: string
format: date-time
description: Timestamp when the model was created
prices:
type: object
additionalProperties:
$ref: '#/components/schemas/ModelPrice'
description: >-
Deprecated. Use 'pricingTiers' instead for models with usage-based
pricing variations.
This field shows prices by usage type from the default pricing tier.
Maintained for backward compatibility.
If the model uses tiered pricing, this field will be populated from
the default tier's prices.
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTier'
description: >-
Array of pricing tiers with conditional pricing based on usage
thresholds.
Pricing tiers enable accurate cost tracking for models that charge
different rates based on usage patterns
(e.g., different rates for high-volume usage, large context windows,
or cached tokens).
Each model must have exactly one default tier (isDefault=true,
priority=0) that serves as a fallback.
Additional conditional tiers can be defined with specific matching
criteria.
If this array is empty, the model uses legacy flat pricing from the
inputPrice/outputPrice/totalPrice fields.
required:
- id
- modelName
- matchPattern
- tokenizerConfig
- isLangfuseManaged
- createdAt
- prices
- pricingTiers
ModelPrice:
title: ModelPrice
type: object
properties:
price:
type: number
format: double
required:
- price
PricingTierCondition:
title: PricingTierCondition
type: object
description: >-
Condition for matching a pricing tier based on usage details. Used to
implement tiered pricing models where costs vary based on usage
thresholds.
How it works:
1. The regex pattern matches against usage detail keys (e.g.,
"input_tokens", "input_cached")
2. Values of all matching keys are summed together
3. The sum is compared against the threshold value using the specified
operator
4. All conditions in a tier must be met (AND logic) for the tier to
match
Common use cases:
- Threshold-based pricing: Match when accumulated usage exceeds a
certain amount
- Usage-type-specific pricing: Different rates for cached vs non-cached
tokens, or input vs output
- Volume-based pricing: Different rates based on total request or token
count
properties:
usageDetailPattern:
type: string
description: >-
Regex pattern to match against usage detail keys. All matching keys'
values are summed for threshold comparison.
Examples:
- "^input" matches "input", "input_tokens", "input_cached", etc.
- "^(input|prompt)" matches both "input_tokens" and "prompt_tokens"
- "_cache$" matches "input_cache", "output_cache", etc.
The pattern is case-insensitive by default. If no keys match, the
sum is treated as zero.
operator:
$ref: '#/components/schemas/PricingTierOperator'
description: >-
Comparison operator to apply between the summed value and the
threshold.
- gt: greater than (sum > threshold)
- gte: greater than or equal (sum >= threshold)
- lt: less than (sum < threshold)
- lte: less than or equal (sum <= threshold)
- eq: equal (sum == threshold)
- neq: not equal (sum != threshold)
value:
type: number
format: double
description: >-
Threshold value for comparison. For token-based pricing, this is
typically the token count threshold (e.g., 200000 for a 200K token
threshold).
caseSensitive:
type: boolean
description: >-
Whether the regex pattern matching is case-sensitive. Default is
false (case-insensitive matching).
required:
- usageDetailPattern
- operator
- value
- caseSensitive
PricingTier:
title: PricingTier
type: object
description: >-
Pricing tier definition with conditional pricing based on usage
thresholds.
Pricing tiers enable accurate cost tracking for LLM providers that
charge different rates based on usage patterns.
For example, some providers charge higher rates when context size
exceeds certain thresholds.
How tier matching works:
1. Tiers are evaluated in ascending priority order (priority 1 before
priority 2, etc.)
2. The first tier where ALL conditions match is selected
3. If no conditional tiers match, the default tier is used as a fallback
4. The default tier has priority 0 and no conditions
Why priorities matter:
- Lower priority numbers are evaluated first, allowing you to define
specific cases before general ones
- Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
"medium usage" (>100K tokens), Priority 0 for default
- Without proper ordering, a less specific condition might match before
a more specific one
Every model must have exactly one default tier to ensure cost
calculation always succeeds.
properties:
id:
type: string
description: Unique identifier for the pricing tier
name:
type: string
description: >-
Name of the pricing tier for display and identification purposes.
Examples: "Standard", "High Volume Tier", "Large Context", "Extended
Context Tier"
isDefault:
type: boolean
description: >-
Whether this is the default tier. Every model must have exactly one
default tier with priority 0 and no conditions.
The default tier serves as a fallback when no conditional tiers
match, ensuring cost calculation always succeeds.
It typically represents the base pricing for standard usage
patterns.
priority:
type: integer
description: >-
Priority for tier matching evaluation. Lower numbers = higher
priority (evaluated first).
The default tier must always have priority 0. Conditional tiers
should have priority 1, 2, 3, etc.
Example ordering:
- Priority 0: Default tier (no conditions, always matches as
fallback)
- Priority 1: High usage tier (e.g., >200K tokens)
- Priority 2: Medium usage tier (e.g., >100K tokens)
This ensures more specific conditions are checked before general
ones.
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: >-
Array of conditions that must ALL be met for this tier to match (AND
logic).
The default tier must have an empty conditions array. Conditional
tiers should have one or more conditions
that define when this tier's pricing applies.
Multiple conditions enable complex matching scenarios (e.g., "high
input tokens AND low output tokens").
prices:
type: object
additionalProperties:
type: number
format: double
description: >-
Prices (USD) by usage type for this tier.
Common usage types: "input", "output", "total", "request", "image"
Prices are specified in USD per unit (e.g., per token, per request,
per second).
Example: {"input": 0.000003, "output": 0.000015} means $3 per
million input tokens and $15 per million output tokens.
required:
- id
- name
- isDefault
- priority
- conditions
- prices
PricingTierInput:
title: PricingTierInput
type: object
description: >-
Input schema for creating a pricing tier. The tier ID will be
automatically generated server-side.
When creating a model with pricing tiers:
- Exactly one tier must have isDefault=true (the fallback tier)
- The default tier must have priority=0 and conditions=[]
- All tier names and priorities must be unique within the model
- Each tier must define at least one price
See PricingTier for detailed information about how tiers work and why
they're useful.
properties:
name:
type: string
description: >-
Name of the pricing tier for display and identification purposes.
Must be unique within the model. Common patterns: "Standard", "High
Volume Tier", "Extended Context"
isDefault:
type: boolean
description: >-
Whether this is the default tier. Exactly one tier per model must be
marked as default.
Requirements for default tier:
- Must have isDefault=true
- Must have priority=0
- Must have empty conditions array (conditions=[])
The default tier acts as a fallback when no conditional tiers match.
priority:
type: integer
description: >-
Priority for tier matching evaluation. Lower numbers = higher
priority (evaluated first).
Must be unique within the model. The default tier must have
priority=0.
Conditional tiers should use priority 1, 2, 3, etc. based on their
specificity.
conditions:
type: array
items:
$ref: '#/components/schemas/PricingTierCondition'
description: >-
Array of conditions that must ALL be met for this tier to match (AND
logic).
The default tier must have an empty array (conditions=[]).
Conditional tiers should define one or more conditions that specify
when this tier's pricing applies.
Each condition specifies a regex pattern, operator, and threshold
value for matching against usage details.
prices:
type: object
additionalProperties:
type: number
format: double
description: >-
Prices (USD) by usage type for this tier. At least one price must be
defined.
Common usage types: "input", "output", "total", "request", "image"
Prices are in USD per unit (e.g., per token).
Example: {"input": 0.000003, "output": 0.000015} represents $3 per
million input tokens and $15 per million output tokens.
required:
- name
- isDefault
- priority
- conditions
- prices
PricingTierOperator:
title: PricingTierOperator
type: string
enum:
- gt
- gte
- lt
- lte
- eq
- neq
description: Comparison operators for pricing tier conditions
ModelUsageUnit:
title: ModelUsageUnit
type: string
enum:
- CHARACTERS
- TOKENS
- MILLISECONDS
- SECONDS
- IMAGES
- REQUESTS
description: Unit of usage in Langfuse
ObservationLevel:
title: ObservationLevel
type: string
enum:
- DEBUG
- DEFAULT
- WARNING
- ERROR
MapValue:
title: MapValue
oneOf:
- type: string
nullable: true
- type: integer
nullable: true
- type: boolean
nullable: true
- type: array
items:
type: string
nullable: true
CommentObjectType:
title: CommentObjectType
type: string
enum:
- TRACE
- OBSERVATION
- SESSION
- PROMPT
DatasetStatus:
title: DatasetStatus
type: string
enum:
- ACTIVE
- ARCHIVED
ScoreSource:
title: ScoreSource
type: string
enum:
- ANNOTATION
- API
- EVAL
ScoreConfigDataType:
title: ScoreConfigDataType
type: string
enum:
- NUMERIC
- BOOLEAN
- CATEGORICAL
ScoreDataType:
title: ScoreDataType
type: string
enum:
- NUMERIC
- BOOLEAN
- CATEGORICAL
- CORRECTION
DeleteDatasetItemResponse:
title: DeleteDatasetItemResponse
type: object
properties:
message:
type: string
description: Success message after deletion
required:
- message
CreateDatasetItemRequest:
title: CreateDatasetItemRequest
type: object
properties:
datasetName:
type: string
input:
nullable: true
expectedOutput:
nullable: true
metadata:
nullable: true
sourceTraceId:
type: string
nullable: true
sourceObservationId:
type: string
nullable: true
id:
type: string
nullable: true
description: >-
Dataset items are upserted on their id. Id needs to be unique
(project-level) and cannot be reused across datasets.
status:
$ref: '#/components/schemas/DatasetStatus'
nullable: true
description: Defaults to ACTIVE for newly created items
required:
- datasetName
PaginatedDatasetItems:
title: PaginatedDatasetItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRunItemRequest:
title: CreateDatasetRunItemRequest
type: object
properties:
runName:
type: string
runDescription:
type: string
nullable: true
description: Description of the run. If run exists, description will be updated.
metadata:
nullable: true
description: Metadata of the dataset run, updates run if run already exists
datasetItemId:
type: string
observationId:
type: string
nullable: true
traceId:
type: string
nullable: true
description: >-
traceId should always be provided. For compatibility with older SDK
versions it can also be inferred from the provided observationId.
required:
- runName
- datasetItemId
PaginatedDatasetRunItems:
title: PaginatedDatasetRunItems
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRunItem'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PaginatedDatasets:
title: PaginatedDatasets
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Dataset'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateDatasetRequest:
title: CreateDatasetRequest
type: object
properties:
name:
type: string
description:
type: string
nullable: true
metadata:
nullable: true
inputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item inputs. When set, all new
and existing dataset items will be validated against this schema.
expectedOutputSchema:
nullable: true
description: >-
JSON Schema for validating dataset item expected outputs. When set,
all new and existing dataset items will be validated against this
schema.
required:
- name
PaginatedDatasetRuns:
title: PaginatedDatasetRuns
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/DatasetRun'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
DeleteDatasetRunResponse:
title: DeleteDatasetRunResponse
type: object
properties:
message:
type: string
required:
- message
HealthResponse:
title: HealthResponse
type: object
properties:
version:
type: string
description: Langfuse server version
example: 1.25.0
status:
type: string
example: OK
required:
- version
- status
IngestionEvent:
title: IngestionEvent
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- trace-create
- $ref: '#/components/schemas/TraceEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- score-create
- $ref: '#/components/schemas/ScoreEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-create
- $ref: '#/components/schemas/CreateSpanEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- span-update
- $ref: '#/components/schemas/UpdateSpanEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-create
- $ref: '#/components/schemas/CreateGenerationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- generation-update
- $ref: '#/components/schemas/UpdateGenerationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- event-create
- $ref: '#/components/schemas/CreateEventEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- sdk-log
- $ref: '#/components/schemas/SDKLogEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-create
- $ref: '#/components/schemas/CreateObservationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- observation-update
- $ref: '#/components/schemas/UpdateObservationEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- agent-create
- $ref: '#/components/schemas/CreateAgentEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- tool-create
- $ref: '#/components/schemas/CreateToolEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- chain-create
- $ref: '#/components/schemas/CreateChainEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- retriever-create
- $ref: '#/components/schemas/CreateRetrieverEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- evaluator-create
- $ref: '#/components/schemas/CreateEvaluatorEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- embedding-create
- $ref: '#/components/schemas/CreateEmbeddingEvent'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- guardrail-create
- $ref: '#/components/schemas/CreateGuardrailEvent'
required:
- type
ObservationType:
title: ObservationType
type: string
enum:
- SPAN
- GENERATION
- EVENT
- AGENT
- TOOL
- CHAIN
- RETRIEVER
- EVALUATOR
- EMBEDDING
- GUARDRAIL
IngestionUsage:
title: IngestionUsage
oneOf:
- $ref: '#/components/schemas/Usage'
- $ref: '#/components/schemas/OpenAIUsage'
OpenAIUsage:
title: OpenAIUsage
type: object
description: Usage interface of OpenAI for improved compatibility.
properties:
promptTokens:
type: integer
nullable: true
completionTokens:
type: integer
nullable: true
totalTokens:
type: integer
nullable: true
OptionalObservationBody:
title: OptionalObservationBody
type: object
properties:
traceId:
type: string
nullable: true
name:
type: string
nullable: true
startTime:
type: string
format: date-time
nullable: true
metadata:
nullable: true
input:
nullable: true
output:
nullable: true
level:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
statusMessage:
type: string
nullable: true
parentObservationId:
type: string
nullable: true
version:
type: string
nullable: true
environment:
type: string
nullable: true
CreateEventBody:
title: CreateEventBody
type: object
properties:
id:
type: string
nullable: true
allOf:
- $ref: '#/components/schemas/OptionalObservationBody'
UpdateEventBody:
title: UpdateEventBody
type: object
properties:
id:
type: string
required:
- id
allOf:
- $ref: '#/components/schemas/OptionalObservationBody'
CreateSpanBody:
title: CreateSpanBody
type: object
properties:
endTime:
type: string
format: date-time
nullable: true
allOf:
- $ref: '#/components/schemas/CreateEventBody'
UpdateSpanBody:
title: UpdateSpanBody
type: object
properties:
endTime:
type: string
format: date-time
nullable: true
allOf:
- $ref: '#/components/schemas/UpdateEventBody'
CreateGenerationBody:
title: CreateGenerationBody
type: object
properties:
completionStartTime:
type: string
format: date-time
nullable: true
model:
type: string
nullable: true
modelParameters:
type: object
additionalProperties:
$ref: '#/components/schemas/MapValue'
nullable: true
usage:
$ref: '#/components/schemas/IngestionUsage'
nullable: true
usageDetails:
$ref: '#/components/schemas/UsageDetails'
nullable: true
costDetails:
type: object
additionalProperties:
type: number
format: double
nullable: true
promptName:
type: string
nullable: true
promptVersion:
type: integer
nullable: true
allOf:
- $ref: '#/components/schemas/CreateSpanBody'
UpdateGenerationBody:
title: UpdateGenerationBody
type: object
properties:
completionStartTime:
type: string
format: date-time
nullable: true
model:
type: string
nullable: true
modelParameters:
type: object
additionalProperties:
$ref: '#/components/schemas/MapValue'
nullable: true
usage:
$ref: '#/components/schemas/IngestionUsage'
nullable: true
promptName:
type: string
nullable: true
usageDetails:
$ref: '#/components/schemas/UsageDetails'
nullable: true
costDetails:
type: object
additionalProperties:
type: number
format: double
nullable: true
promptVersion:
type: integer
nullable: true
allOf:
- $ref: '#/components/schemas/UpdateSpanBody'
ObservationBody:
title: ObservationBody
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
type:
$ref: '#/components/schemas/ObservationType'
name:
type: string
nullable: true
startTime:
type: string
format: date-time
nullable: true
endTime:
type: string
format: date-time
nullable: true
completionStartTime:
type: string
format: date-time
nullable: true
model:
type: string
nullable: true
modelParameters:
type: object
additionalProperties:
$ref: '#/components/schemas/MapValue'
nullable: true
input:
nullable: true
version:
type: string
nullable: true
metadata:
nullable: true
output:
nullable: true
usage:
$ref: '#/components/schemas/Usage'
nullable: true
level:
$ref: '#/components/schemas/ObservationLevel'
nullable: true
statusMessage:
type: string
nullable: true
parentObservationId:
type: string
nullable: true
environment:
type: string
nullable: true
required:
- type
TraceBody:
title: TraceBody
type: object
properties:
id:
type: string
nullable: true
timestamp:
type: string
format: date-time
nullable: true
name:
type: string
nullable: true
userId:
type: string
nullable: true
input:
nullable: true
output:
nullable: true
sessionId:
type: string
nullable: true
release:
type: string
nullable: true
version:
type: string
nullable: true
metadata:
nullable: true
tags:
type: array
items:
type: string
nullable: true
environment:
type: string
nullable: true
public:
type: boolean
nullable: true
description: Make trace publicly accessible via url
SDKLogBody:
title: SDKLogBody
type: object
properties:
log: {}
required:
- log
ScoreBody:
title: ScoreBody
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
sessionId:
type: string
nullable: true
observationId:
type: string
nullable: true
datasetRunId:
type: string
nullable: true
name:
type: string
description: >-
The name of the score. Always overrides "output" for correction
scores.
example: novelty
environment:
type: string
nullable: true
queueId:
type: string
nullable: true
description: >-
The annotation queue referenced by the score. Indicates if score was
initially created while processing annotation queue.
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical
scores, and numeric for boolean and numeric scores. Boolean score
values must equal either 1 or 0 (true or false)
comment:
type: string
nullable: true
metadata:
nullable: true
dataType:
$ref: '#/components/schemas/ScoreDataType'
nullable: true
description: >-
When set, must match the score value's type. If not set, will be
inferred from the score value or config
configId:
type: string
nullable: true
description: >-
Reference a score config on a score. When set, the score name must
equal the config name and scores must comply with the config's range
and data type. For categorical scores, the value must map to a
config category. Numeric scores might be constrained by the score
config's max and min values
required:
- name
- value
BaseEvent:
title: BaseEvent
type: object
properties:
id:
type: string
description: UUID v4 that identifies the event
timestamp:
type: string
description: >-
Datetime (ISO 8601) of event creation in client. Should be as close
to actual event creation in client as possible, this timestamp will
be used for ordering of events in future release. Resolution:
milliseconds (required), microseconds (optimal).
metadata:
nullable: true
description: Optional. Metadata field used by the Langfuse SDKs for debugging.
required:
- id
- timestamp
TraceEvent:
title: TraceEvent
type: object
properties:
body:
$ref: '#/components/schemas/TraceBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateObservationEvent:
title: CreateObservationEvent
type: object
properties:
body:
$ref: '#/components/schemas/ObservationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateObservationEvent:
title: UpdateObservationEvent
type: object
properties:
body:
$ref: '#/components/schemas/ObservationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
ScoreEvent:
title: ScoreEvent
type: object
properties:
body:
$ref: '#/components/schemas/ScoreBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
SDKLogEvent:
title: SDKLogEvent
type: object
properties:
body:
$ref: '#/components/schemas/SDKLogBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateGenerationEvent:
title: CreateGenerationEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateGenerationEvent:
title: UpdateGenerationEvent
type: object
properties:
body:
$ref: '#/components/schemas/UpdateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateSpanEvent:
title: CreateSpanEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
UpdateSpanEvent:
title: UpdateSpanEvent
type: object
properties:
body:
$ref: '#/components/schemas/UpdateSpanBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateEventEvent:
title: CreateEventEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateEventBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateAgentEvent:
title: CreateAgentEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateToolEvent:
title: CreateToolEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateChainEvent:
title: CreateChainEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateRetrieverEvent:
title: CreateRetrieverEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateEvaluatorEvent:
title: CreateEvaluatorEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateEmbeddingEvent:
title: CreateEmbeddingEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
CreateGuardrailEvent:
title: CreateGuardrailEvent
type: object
properties:
body:
$ref: '#/components/schemas/CreateGenerationBody'
required:
- body
allOf:
- $ref: '#/components/schemas/BaseEvent'
IngestionSuccess:
title: IngestionSuccess
type: object
properties:
id:
type: string
status:
type: integer
required:
- id
- status
IngestionError:
title: IngestionError
type: object
properties:
id:
type: string
status:
type: integer
message:
type: string
nullable: true
error:
nullable: true
required:
- id
- status
IngestionResponse:
title: IngestionResponse
type: object
properties:
successes:
type: array
items:
$ref: '#/components/schemas/IngestionSuccess'
errors:
type: array
items:
$ref: '#/components/schemas/IngestionError'
required:
- successes
- errors
OpenAICompletionUsageSchema:
title: OpenAICompletionUsageSchema
type: object
description: OpenAI Usage schema from (Chat-)Completion APIs
properties:
prompt_tokens:
type: integer
completion_tokens:
type: integer
total_tokens:
type: integer
prompt_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
completion_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
required:
- prompt_tokens
- completion_tokens
- total_tokens
OpenAIResponseUsageSchema:
title: OpenAIResponseUsageSchema
type: object
description: OpenAI Usage schema from Response API
properties:
input_tokens:
type: integer
output_tokens:
type: integer
total_tokens:
type: integer
input_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
output_tokens_details:
type: object
additionalProperties:
type: integer
nullable: true
nullable: true
required:
- input_tokens
- output_tokens
- total_tokens
UsageDetails:
title: UsageDetails
oneOf:
- type: object
additionalProperties:
type: integer
- $ref: '#/components/schemas/OpenAICompletionUsageSchema'
- $ref: '#/components/schemas/OpenAIResponseUsageSchema'
LlmConnection:
title: LlmConnection
type: object
description: LLM API connection configuration (secrets excluded)
properties:
id:
type: string
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
type: string
description: The adapter used to interface with the LLM
displaySecretKey:
type: string
description: Masked version of the secret key for display purposes
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
description: List of custom model names available for this connection
withDefaultModels:
type: boolean
description: Whether to include default models for this adapter
extraHeaderKeys:
type: array
items:
type: string
description: >-
Keys of extra headers sent with requests (values excluded for
security)
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Required for Bedrock
(`{"region":"us-east-1"}`), optional for VertexAI
(`{"location":"us-central1"}`), not used by other adapters.
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- provider
- adapter
- displaySecretKey
- customModels
- withDefaultModels
- extraHeaderKeys
- createdAt
- updatedAt
PaginatedLlmConnections:
title: PaginatedLlmConnections
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/LlmConnection'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
UpsertLlmConnectionRequest:
title: UpsertLlmConnectionRequest
type: object
description: Request to create or update an LLM connection (upsert)
properties:
provider:
type: string
description: >-
Provider name (e.g., 'openai', 'my-gateway'). Must be unique in
project, used for upserting.
adapter:
$ref: '#/components/schemas/LlmAdapter'
description: The adapter used to interface with the LLM
secretKey:
type: string
description: Secret key for the LLM API.
baseURL:
type: string
nullable: true
description: Custom base URL for the LLM API
customModels:
type: array
items:
type: string
nullable: true
description: List of custom model names
withDefaultModels:
type: boolean
nullable: true
description: Whether to include default models. Default is true.
extraHeaders:
type: object
additionalProperties:
type: string
nullable: true
description: Extra headers to send with requests
config:
type: object
additionalProperties: true
nullable: true
description: >-
Adapter-specific configuration. Validation rules: - **Bedrock**:
Required. Must be `{"region": "<aws-region>"}` (e.g.,
`{"region":"us-east-1"}`) - **VertexAI**: Optional. If provided,
must be `{"location": "<gcp-location>"}` (e.g.,
`{"location":"us-central1"}`) - **Other adapters**: Not supported.
Omit this field or set to null.
required:
- provider
- adapter
- secretKey
LlmAdapter:
title: LlmAdapter
type: string
enum:
- anthropic
- openai
- azure
- bedrock
- google-vertex-ai
- google-ai-studio
GetMediaResponse:
title: GetMediaResponse
type: object
properties:
mediaId:
type: string
description: The unique langfuse identifier of a media record
contentType:
type: string
description: The MIME type of the media record
contentLength:
type: integer
description: The size of the media record in bytes
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
url:
type: string
description: The download URL of the media record
urlExpiry:
type: string
description: The expiry date and time of the media record download URL
required:
- mediaId
- contentType
- contentLength
- uploadedAt
- url
- urlExpiry
PatchMediaBody:
title: PatchMediaBody
type: object
properties:
uploadedAt:
type: string
format: date-time
description: The date and time when the media record was uploaded
uploadHttpStatus:
type: integer
description: The HTTP status code of the upload
uploadHttpError:
type: string
nullable: true
description: The HTTP error message of the upload
uploadTimeMs:
type: integer
nullable: true
description: The time in milliseconds it took to upload the media record
required:
- uploadedAt
- uploadHttpStatus
GetMediaUploadUrlRequest:
title: GetMediaUploadUrlRequest
type: object
properties:
traceId:
type: string
description: The trace ID associated with the media record
observationId:
type: string
nullable: true
description: >-
The observation ID associated with the media record. If the media
record is associated directly with a trace, this will be null.
contentType:
$ref: '#/components/schemas/MediaContentType'
contentLength:
type: integer
description: The size of the media record in bytes
sha256Hash:
type: string
description: The SHA-256 hash of the media record
field:
type: string
description: >-
The trace / observation field the media record is associated with.
This can be one of `input`, `output`, `metadata`
required:
- traceId
- contentType
- contentLength
- sha256Hash
- field
GetMediaUploadUrlResponse:
title: GetMediaUploadUrlResponse
type: object
properties:
uploadUrl:
type: string
nullable: true
description: >-
The presigned upload URL. If the asset is already uploaded, this
will be null
mediaId:
type: string
description: The unique langfuse identifier of a media record
required:
- mediaId
MediaContentType:
title: MediaContentType
type: string
enum:
- image/png
- image/jpeg
- image/jpg
- image/webp
- image/gif
- image/svg+xml
- image/tiff
- image/bmp
- image/avif
- image/heic
- audio/mpeg
- audio/mp3
- audio/wav
- audio/ogg
- audio/oga
- audio/aac
- audio/mp4
- audio/flac
- audio/opus
- audio/webm
- video/mp4
- video/webm
- video/ogg
- video/mpeg
- video/quicktime
- video/x-msvideo
- video/x-matroska
- text/plain
- text/html
- text/css
- text/csv
- text/markdown
- text/x-python
- application/javascript
- text/x-typescript
- application/x-yaml
- application/pdf
- application/msword
- application/vnd.ms-excel
- application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- application/zip
- application/json
- application/xml
- application/octet-stream
- >-
application/vnd.openxmlformats-officedocument.wordprocessingml.document
- >-
application/vnd.openxmlformats-officedocument.presentationml.presentation
- application/rtf
- application/x-ndjson
- application/vnd.apache.parquet
- application/gzip
- application/x-tar
- application/x-7z-compressed
description: The MIME type of the media record
MetricsV2Response:
title: MetricsV2Response
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
required:
- data
MetricsResponse:
title: MetricsResponse
type: object
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
The metrics data. Each item in the list contains the metric values
and dimensions requested in the query.
Format varies based on the query parameters.
Histograms will return an array with [lower, upper, height] tuples.
required:
- data
PaginatedModels:
title: PaginatedModels
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Model'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateModelRequest:
title: CreateModelRequest
type: object
properties:
modelName:
type: string
description: >-
Name of the model definition. If multiple with the same name exist,
they are applied in the following order: (1) custom over built-in,
(2) newest according to startTime where
model.startTime<observation.startTime
matchPattern:
type: string
description: >-
Regex pattern which matches this model definition to
generation.model. Useful in case of fine-tuned models. If you want
to exact match, use `(?i)^modelname$`
startDate:
type: string
format: date-time
nullable: true
description: Apply only to generations which are newer than this ISO date.
unit:
$ref: '#/components/schemas/ModelUsageUnit'
nullable: true
description: Unit used by this model.
inputPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit.
Creates a default tier if pricingTiers not provided.
outputPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit.
Creates a default tier if pricingTiers not provided.
totalPrice:
type: number
format: double
nullable: true
description: >-
Deprecated. Use 'pricingTiers' instead. Price (USD) per total units.
Cannot be set if input or output price is set. Creates a default
tier if pricingTiers not provided.
pricingTiers:
type: array
items:
$ref: '#/components/schemas/PricingTierInput'
nullable: true
description: >-
Optional. Array of pricing tiers for this model.
Use pricing tiers for all models - both those with threshold-based
pricing variations and those with simple flat pricing:
- For models with standard flat pricing: Create a single default
tier with your prices
(e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices)
- For models with threshold-based pricing: Create a default tier
plus additional conditional tiers
(e.g., default tier for standard usage + high-volume tier for usage above certain thresholds)
Requirements:
- Cannot be provided with flat prices
(inputPrice/outputPrice/totalPrice) - use one approach or the other
- Must include exactly one default tier with isDefault=true,
priority=0, and conditions=[]
- All tier names and priorities must be unique within the model
- Each tier must define at least one price
If omitted, you must provide flat prices instead
(inputPrice/outputPrice/totalPrice),
which will automatically create a single default tier named
"Standard".
tokenizerId:
type: string
nullable: true
description: >-
Optional. Tokenizer to be applied to observations which match to
this model. See docs for more details.
tokenizerConfig:
nullable: true
description: >-
Optional. Configuration for the selected tokenizer. Needs to be
JSON. See docs for more details.
required:
- modelName
- matchPattern
ObservationsV2Response:
title: ObservationsV2Response
type: object
description: >-
Response containing observations with field-group-based filtering and
cursor-based pagination.
The `data` array contains observation objects with only the requested
field groups included.
Use the `cursor` in `meta` to retrieve the next page of results.
properties:
data:
type: array
items:
type: object
additionalProperties: true
description: >-
Array of observation objects. Fields included depend on the `fields`
parameter in the request.
meta:
$ref: '#/components/schemas/ObservationsV2Meta'
required:
- data
- meta
ObservationsV2Meta:
title: ObservationsV2Meta
type: object
description: Metadata for cursor-based pagination
properties:
cursor:
type: string
nullable: true
description: >-
Base64-encoded cursor to use for retrieving the next page. If not
present, there are no more results.
Observations:
title: Observations
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Observation'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
ObservationsViews:
title: ObservationsViews
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ObservationsView'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
OtelResourceSpan:
title: OtelResourceSpan
type: object
description: >-
Represents a collection of spans from a single resource as per OTLP
specification
properties:
resource:
$ref: '#/components/schemas/OtelResource'
nullable: true
description: Resource information
scopeSpans:
type: array
items:
$ref: '#/components/schemas/OtelScopeSpan'
nullable: true
description: Array of scope spans
OtelResource:
title: OtelResource
type: object
description: Resource attributes identifying the source of telemetry
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: Resource attributes like service.name, service.version, etc.
OtelScopeSpan:
title: OtelScopeSpan
type: object
description: Collection of spans from a single instrumentation scope
properties:
scope:
$ref: '#/components/schemas/OtelScope'
nullable: true
description: Instrumentation scope information
spans:
type: array
items:
$ref: '#/components/schemas/OtelSpan'
nullable: true
description: Array of spans
OtelScope:
title: OtelScope
type: object
description: Instrumentation scope information
properties:
name:
type: string
nullable: true
description: Instrumentation scope name
version:
type: string
nullable: true
description: Instrumentation scope version
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: Additional scope attributes
OtelSpan:
title: OtelSpan
type: object
description: Individual span representing a unit of work or operation
properties:
traceId:
nullable: true
description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary)
spanId:
nullable: true
description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary)
parentSpanId:
nullable: true
description: Parent span ID if this is a child span
name:
type: string
nullable: true
description: Span name describing the operation
kind:
type: integer
nullable: true
description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER)
startTimeUnixNano:
nullable: true
description: Start time in nanoseconds since Unix epoch
endTimeUnixNano:
nullable: true
description: End time in nanoseconds since Unix epoch
attributes:
type: array
items:
$ref: '#/components/schemas/OtelAttribute'
nullable: true
description: >-
Span attributes including Langfuse-specific attributes
(langfuse.observation.*)
status:
nullable: true
description: Span status object
OtelAttribute:
title: OtelAttribute
type: object
description: Key-value attribute pair for resources, scopes, or spans
properties:
key:
type: string
nullable: true
description: Attribute key (e.g., "service.name", "langfuse.observation.type")
value:
$ref: '#/components/schemas/OtelAttributeValue'
nullable: true
description: Attribute value
OtelAttributeValue:
title: OtelAttributeValue
type: object
description: Attribute value wrapper supporting different value types
properties:
stringValue:
type: string
nullable: true
description: String value
intValue:
type: integer
nullable: true
description: Integer value
doubleValue:
type: number
format: double
nullable: true
description: Double value
boolValue:
type: boolean
nullable: true
description: Boolean value
OtelTraceResponse:
title: OtelTraceResponse
type: object
description: Response from trace export request. Empty object indicates success.
properties: {}
MembershipRole:
title: MembershipRole
type: string
enum:
- OWNER
- ADMIN
- MEMBER
- VIEWER
MembershipRequest:
title: MembershipRequest
type: object
properties:
userId:
type: string
role:
$ref: '#/components/schemas/MembershipRole'
required:
- userId
- role
DeleteMembershipRequest:
title: DeleteMembershipRequest
type: object
properties:
userId:
type: string
required:
- userId
MembershipResponse:
title: MembershipResponse
type: object
properties:
userId:
type: string
role:
$ref: '#/components/schemas/MembershipRole'
email:
type: string
name:
type: string
required:
- userId
- role
- email
- name
MembershipDeletionResponse:
title: MembershipDeletionResponse
type: object
properties:
message:
type: string
userId:
type: string
required:
- message
- userId
MembershipsResponse:
title: MembershipsResponse
type: object
properties:
memberships:
type: array
items:
$ref: '#/components/schemas/MembershipResponse'
required:
- memberships
OrganizationProject:
title: OrganizationProject
type: object
properties:
id:
type: string
name:
type: string
metadata:
type: object
additionalProperties: true
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
- createdAt
- updatedAt
OrganizationProjectsResponse:
title: OrganizationProjectsResponse
type: object
properties:
projects:
type: array
items:
$ref: '#/components/schemas/OrganizationProject'
required:
- projects
OrganizationApiKey:
title: OrganizationApiKey
type: object
properties:
id:
type: string
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
nullable: true
lastUsedAt:
type: string
format: date-time
nullable: true
note:
type: string
nullable: true
publicKey:
type: string
displaySecretKey:
type: string
required:
- id
- createdAt
- publicKey
- displaySecretKey
OrganizationApiKeysResponse:
title: OrganizationApiKeysResponse
type: object
properties:
apiKeys:
type: array
items:
$ref: '#/components/schemas/OrganizationApiKey'
required:
- apiKeys
Projects:
title: Projects
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Project'
required:
- data
Organization:
title: Organization
type: object
properties:
id:
type: string
description: The unique identifier of the organization
name:
type: string
description: The name of the organization
required:
- id
- name
Project:
title: Project
type: object
properties:
id:
type: string
name:
type: string
organization:
$ref: '#/components/schemas/Organization'
description: The organization this project belongs to
metadata:
type: object
additionalProperties: true
description: Metadata for the project
retentionDays:
type: integer
nullable: true
description: >-
Number of days to retain data. Null or 0 means no retention. Omitted
if no retention is configured.
required:
- id
- name
- organization
- metadata
ProjectDeletionResponse:
title: ProjectDeletionResponse
type: object
properties:
success:
type: boolean
message:
type: string
required:
- success
- message
ApiKeyList:
title: ApiKeyList
type: object
description: List of API keys for a project
properties:
apiKeys:
type: array
items:
$ref: '#/components/schemas/ApiKeySummary'
required:
- apiKeys
ApiKeySummary:
title: ApiKeySummary
type: object
description: Summary of an API key
properties:
id:
type: string
createdAt:
type: string
format: date-time
expiresAt:
type: string
format: date-time
nullable: true
lastUsedAt:
type: string
format: date-time
nullable: true
note:
type: string
nullable: true
publicKey:
type: string
displaySecretKey:
type: string
required:
- id
- createdAt
- publicKey
- displaySecretKey
ApiKeyResponse:
title: ApiKeyResponse
type: object
description: Response for API key creation
properties:
id:
type: string
createdAt:
type: string
format: date-time
publicKey:
type: string
secretKey:
type: string
displaySecretKey:
type: string
note:
type: string
nullable: true
required:
- id
- createdAt
- publicKey
- secretKey
- displaySecretKey
ApiKeyDeletionResponse:
title: ApiKeyDeletionResponse
type: object
description: Response for API key deletion
properties:
success:
type: boolean
required:
- success
PromptMetaListResponse:
title: PromptMetaListResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PromptMeta'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
PromptMeta:
title: PromptMeta
type: object
properties:
name:
type: string
type:
$ref: '#/components/schemas/PromptType'
description: Indicates whether the prompt is a text or chat prompt.
versions:
type: array
items:
type: integer
labels:
type: array
items:
type: string
tags:
type: array
items:
type: string
lastUpdatedAt:
type: string
format: date-time
lastConfig:
description: >-
Config object of the most recent prompt version that matches the
filters (if any are provided)
required:
- name
- type
- versions
- labels
- tags
- lastUpdatedAt
- lastConfig
CreatePromptRequest:
title: CreatePromptRequest
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- chat
- $ref: '#/components/schemas/CreateChatPromptRequest'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- text
- $ref: '#/components/schemas/CreateTextPromptRequest'
required:
- type
CreateChatPromptRequest:
title: CreateChatPromptRequest
type: object
properties:
name:
type: string
prompt:
type: array
items:
$ref: '#/components/schemas/ChatMessageWithPlaceholders'
config:
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
CreateTextPromptRequest:
title: CreateTextPromptRequest
type: object
properties:
name:
type: string
prompt:
type: string
config:
nullable: true
labels:
type: array
items:
type: string
nullable: true
description: List of deployment labels of this prompt version.
tags:
type: array
items:
type: string
nullable: true
description: List of tags to apply to all versions of this prompt.
commitMessage:
type: string
nullable: true
description: Commit message for this prompt version.
required:
- name
- prompt
Prompt:
title: Prompt
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- chat
- $ref: '#/components/schemas/ChatPrompt'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- text
- $ref: '#/components/schemas/TextPrompt'
required:
- type
PromptType:
title: PromptType
type: string
enum:
- chat
- text
BasePrompt:
title: BasePrompt
type: object
properties:
name:
type: string
version:
type: integer
config: {}
labels:
type: array
items:
type: string
description: List of deployment labels of this prompt version.
tags:
type: array
items:
type: string
description: >-
List of tags. Used to filter via UI and API. The same across
versions of a prompt.
commitMessage:
type: string
nullable: true
description: Commit message for this prompt version.
resolutionGraph:
type: object
additionalProperties: true
nullable: true
description: >-
The dependency resolution graph for the current prompt. Null if
prompt has no dependencies.
required:
- name
- version
- config
- labels
- tags
ChatMessageWithPlaceholders:
title: ChatMessageWithPlaceholders
oneOf:
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- chatmessage
- $ref: '#/components/schemas/ChatMessage'
required:
- type
- type: object
allOf:
- type: object
properties:
type:
type: string
enum:
- placeholder
- $ref: '#/components/schemas/PlaceholderMessage'
required:
- type
ChatMessage:
title: ChatMessage
type: object
properties:
role:
type: string
content:
type: string
required:
- role
- content
PlaceholderMessage:
title: PlaceholderMessage
type: object
properties:
name:
type: string
required:
- name
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'
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
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: The name of the score config
categories:
type: array
items:
$ref: '#/components/schemas/ConfigCategory'
nullable: true
description: >-
Configure custom categories for categorical scores. Pass a list of
objects with `label` and `value` properties. Categories are
autogenerated for boolean configs and cannot be passed
minValue:
type: number
format: double
nullable: true
description: >-
Configure a minimum value for numerical scores. If not set, the
minimum value defaults to -∞
maxValue:
type: number
format: double
nullable: true
description: >-
Configure a maximum value for numerical scores. If not set, the
maximum value defaults to +∞
description:
type: string
nullable: true
description: >-
Description is shown across the Langfuse UI and can be used to e.g.
explain the config categories in detail, why a numeric range was
set, or provide additional context on config name or usage
GetScoresResponseTraceData:
title: GetScoresResponseTraceData
type: object
properties:
userId:
type: string
nullable: true
description: The user ID associated with the trace referenced by score
tags:
type: array
items:
type: string
nullable: true
description: A list of tags associated with the trace referenced by score
environment:
type: string
nullable: true
description: The environment of the trace referenced by score
GetScoresResponseDataNumeric:
title: GetScoresResponseDataNumeric
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/NumericScore'
GetScoresResponseDataCategorical:
title: GetScoresResponseDataCategorical
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/CategoricalScore'
GetScoresResponseDataBoolean:
title: GetScoresResponseDataBoolean
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/BooleanScore'
GetScoresResponseDataCorrection:
title: GetScoresResponseDataCorrection
type: object
properties:
trace:
$ref: '#/components/schemas/GetScoresResponseTraceData'
nullable: true
allOf:
- $ref: '#/components/schemas/CorrectionScore'
GetScoresResponseData:
title: GetScoresResponseData
oneOf:
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- NUMERIC
- $ref: '#/components/schemas/GetScoresResponseDataNumeric'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CATEGORICAL
- $ref: '#/components/schemas/GetScoresResponseDataCategorical'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- BOOLEAN
- $ref: '#/components/schemas/GetScoresResponseDataBoolean'
required:
- dataType
- type: object
allOf:
- type: object
properties:
dataType:
type: string
enum:
- CORRECTION
- $ref: '#/components/schemas/GetScoresResponseDataCorrection'
required:
- dataType
GetScoresResponse:
title: GetScoresResponse
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/GetScoresResponseData'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
CreateScoreRequest:
title: CreateScoreRequest
type: object
properties:
id:
type: string
nullable: true
traceId:
type: string
nullable: true
sessionId:
type: string
nullable: true
observationId:
type: string
nullable: true
datasetRunId:
type: string
nullable: true
name:
type: string
example: novelty
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
The value of the score. Must be passed as string for categorical
scores, and numeric for boolean and numeric scores. Boolean score
values must equal either 1 or 0 (true or false)
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.
required:
- name
- value
CreateScoreResponse:
title: CreateScoreResponse
type: object
properties:
id:
type: string
description: The id of the created object in Langfuse
required:
- id
PaginatedSessions:
title: PaginatedSessions
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/Session'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
Traces:
title: Traces
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TraceWithDetails'
meta:
$ref: '#/components/schemas/utilsMetaResponse'
required:
- data
- meta
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
properties:
message:
type: string
required:
- message
Sort:
title: Sort
type: object
properties:
id:
type: string
required:
- id
utilsMetaResponse:
title: utilsMetaResponse
type: object
properties:
page:
type: integer
description: current page number
limit:
type: integer
description: number of items per page
totalItems:
type: integer
description: number of total items given the current filters/selection (if any)
totalPages:
type: integer
description: number of total pages given the current limit
required:
- page
- limit
- totalItems
- totalPages
securitySchemes:
BasicAuth:
type: http
scheme: basic