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