diff --git a/README.md b/README.md index 53d8d96..91cf1de 100644 --- a/README.md +++ b/README.md @@ -147,6 +147,7 @@ without a clean discriminator stay `--body-json`-only rather than guessing. | 4 | Network, DNS, TLS, or timeout failure reaching the host | | 5 | The API responded with a non-success HTTP status (response is still printed) | | 6 | Local file or bundled-contract failure | +| 7 | Invalid or inconsistent API response | ## Agent Usage diff --git a/bun.lock b/bun.lock index 13fc674..2be4a57 100644 --- a/bun.lock +++ b/bun.lock @@ -13,6 +13,7 @@ "semver": "^7.8.5", "typescript": "^7.0.2", "yaml": "^2.9.0", + "zod": "^4.6.5", }, }, }, @@ -107,5 +108,7 @@ "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="], "yaml": ["yaml@2.9.0", "", { "bin": { "yaml": "bin.mjs" } }, "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA=="], + + "zod": ["zod@4.6.5", "", {}, "sha512-v5l/aFXZQeai4awLbOpSoHecE9UiMrnfx75tEXLjNonXVARxQ5mOeipTjROUchszUNCqnE+hqAMujRsRHsut2Q=="], } } diff --git a/conformance/README.md b/conformance/README.md index fec31d5..56efb34 100644 --- a/conformance/README.md +++ b/conformance/README.md @@ -14,7 +14,7 @@ The primary test invokes every operation in every cataloged spec through the rea For operations marked `deprecated: true`, it instead verifies exit code 2, a helpful error on stderr, and zero network requests. -The black-box oracle does not share request-building code with the CLI. `bun run conformance:all` checks all 596 operations across 6 pinned snapshots through the actual CLI using lossless `--body-json` input, including pre-network rejection for deprecated operations. +The black-box oracle does not share request-building code with the CLI. `bun run conformance:all` checks all 720 operations across 7 pinned snapshots through the actual CLI using lossless `--body-json` input, including pre-network rejection for deprecated operations. Supporting unit tests verify immutable spec hashes, valid sampling, serialization, naming, invocation generation, and the capture runner itself. @@ -30,6 +30,7 @@ OpenAPI cannot describe database setup, generated IDs, cross-request bindings, c | 3.225.3 | 69 | 113 | | 4.10.0 | 70 | 114 | | 4.35.0 | 71 | 117 | +| 4.48.0 | 75 | 124 | Each source file is downloaded by immutable commit and verified against the SHA-256 in `catalog.json`. Tests are network-free after sync. diff --git a/conformance/catalog.json b/conformance/catalog.json index 3d713f4..eef95b8 100644 --- a/conformance/catalog.json +++ b/conformance/catalog.json @@ -46,6 +46,13 @@ "commit": "3089a77f2b86e08058a868802f43e417982094f0", "sha256": "8f3a25d28afbf8bdd710d8e7a5c60d65ff5c71315764c46c8dea504e8f67adb6", "knownIssues": ["oas3.0-const-keyword"] + }, + { + "version": "4.48.0", + "ref": "v4.48.0", + "commit": "0de9ccd64e0f9d35c1990fb6c851fa00530e7960", + "sha256": "0cfedceece040eb5d042dc0db7f561c4f5bb96ebfd5971a4807fb490f0a328ed", + "knownIssues": ["oas3.0-const-keyword"] } ] } diff --git a/conformance/goldens/4.48.0.json b/conformance/goldens/4.48.0.json new file mode 100644 index 0000000..cca4606 --- /dev/null +++ b/conformance/goldens/4.48.0.json @@ -0,0 +1,1094 @@ +[ + { + "operationId": "annotationQueues_createQueue", + "key": "POST /api/public/annotation-queues", + "resource": "annotation-queues", + "action": "create" + }, + { + "operationId": "annotationQueues_createQueueAssignment", + "key": "POST /api/public/annotation-queues/{queueId}/assignments", + "resource": "annotation-queues", + "action": "create-assignment" + }, + { + "operationId": "annotationQueues_createQueueItem", + "key": "POST /api/public/annotation-queues/{queueId}/items", + "resource": "annotation-queues", + "action": "create-item" + }, + { + "operationId": "annotationQueues_deleteQueueAssignment", + "key": "DELETE /api/public/annotation-queues/{queueId}/assignments", + "resource": "annotation-queues", + "action": "delete-assignment" + }, + { + "operationId": "annotationQueues_deleteQueueItem", + "key": "DELETE /api/public/annotation-queues/{queueId}/items/{itemId}", + "resource": "annotation-queues", + "action": "delete-item" + }, + { + "operationId": "annotationQueues_getQueue", + "key": "GET /api/public/annotation-queues/{queueId}", + "resource": "annotation-queues", + "action": "get" + }, + { + "operationId": "annotationQueues_getQueueItem", + "key": "GET /api/public/annotation-queues/{queueId}/items/{itemId}", + "resource": "annotation-queues", + "action": "get-item" + }, + { + "operationId": "annotationQueues_listQueueItems", + "key": "GET /api/public/annotation-queues/{queueId}/items", + "resource": "annotation-queues", + "action": "list-items" + }, + { + "operationId": "annotationQueues_listQueues", + "key": "GET /api/public/annotation-queues", + "resource": "annotation-queues", + "action": "list" + }, + { + "operationId": "annotationQueues_updateQueueItem", + "key": "PATCH /api/public/annotation-queues/{queueId}/items/{itemId}", + "resource": "annotation-queues", + "action": "update-item" + }, + { + "operationId": "blobStorageIntegrations_deleteBlobStorageIntegration", + "key": "DELETE /api/public/integrations/blob-storage/{id}", + "resource": "integrations", + "action": "delete-blob-storage", + "aliases": [ + { + "resource": "blob-storage-integrations", + "action": "delete-blob-storage", + "source": "tag" + } + ] + }, + { + "operationId": "blobStorageIntegrations_getBlobStorageIntegrationStatus", + "key": "GET /api/public/integrations/blob-storage/{id}", + "resource": "integrations", + "action": "get-blob-storage-integration-status", + "aliases": [ + { + "resource": "blob-storage-integrations", + "action": "get-blob-storage-integration-status", + "source": "tag" + } + ] + }, + { + "operationId": "blobStorageIntegrations_getBlobStorageIntegrations", + "key": "GET /api/public/integrations/blob-storage", + "resource": "integrations", + "action": "list-blob-storage", + "aliases": [ + { + "resource": "blob-storage-integrations", + "action": "list-blob-storage", + "source": "tag" + } + ] + }, + { + "operationId": "blobStorageIntegrations_upsertBlobStorageIntegration", + "key": "PUT /api/public/integrations/blob-storage", + "resource": "integrations", + "action": "upsert-blob-storage", + "aliases": [ + { + "resource": "blob-storage-integrations", + "action": "upsert-blob-storage", + "source": "tag" + } + ] + }, + { + "operationId": "comments_create", + "key": "POST /api/public/comments", + "resource": "comments", + "action": "create" + }, + { + "operationId": "comments_get", + "key": "GET /api/public/comments", + "resource": "comments", + "action": "list" + }, + { + "operationId": "comments_get-by-id", + "key": "GET /api/public/comments/{commentId}", + "resource": "comments", + "action": "get" + }, + { + "operationId": "datasetItems_create", + "key": "POST /api/public/dataset-items", + "resource": "dataset-items", + "action": "create" + }, + { + "operationId": "datasetItems_delete", + "key": "DELETE /api/public/dataset-items/{id}", + "resource": "dataset-items", + "action": "delete" + }, + { + "operationId": "datasetItems_get", + "key": "GET /api/public/dataset-items/{id}", + "resource": "dataset-items", + "action": "get" + }, + { + "operationId": "datasetItems_list", + "key": "GET /api/public/dataset-items", + "resource": "dataset-items", + "action": "list" + }, + { + "operationId": "datasetRunItems_create", + "key": "POST /api/public/dataset-run-items", + "resource": "legacy-dataset-run-items", + "action": "create", + "aliases": [ + { + "resource": "dataset-run-items", + "action": "create", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "datasetRunItems_list", + "key": "GET /api/public/dataset-run-items", + "resource": "legacy-dataset-run-items", + "action": "list", + "aliases": [ + { + "resource": "dataset-run-items", + "action": "list", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "datasets_create", + "key": "POST /api/public/v2/datasets", + "resource": "datasets", + "action": "create", + "aliases": [ + { + "resource": "datasets-v2", + "action": "create", + "source": "version" + } + ] + }, + { + "operationId": "datasets_deleteRun", + "key": "DELETE /api/public/datasets/{datasetName}/runs/{runName}", + "resource": "legacy-datasets", + "action": "delete-run", + "aliases": [ + { + "resource": "datasets", + "action": "delete-run", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "datasets_get", + "key": "GET /api/public/v2/datasets/{datasetName}", + "resource": "datasets", + "action": "get", + "aliases": [ + { + "resource": "datasets-v2", + "action": "get", + "source": "version" + } + ] + }, + { + "operationId": "datasets_getRun", + "key": "GET /api/public/datasets/{datasetName}/runs/{runName}", + "resource": "legacy-datasets", + "action": "get-run", + "aliases": [ + { + "resource": "datasets", + "action": "get-run", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "datasets_getRuns", + "key": "GET /api/public/datasets/{datasetName}/runs", + "resource": "legacy-datasets", + "action": "list-runs", + "aliases": [ + { + "resource": "datasets", + "action": "list-runs", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "datasets_list", + "key": "GET /api/public/v2/datasets", + "resource": "datasets", + "action": "list", + "aliases": [ + { + "resource": "datasets-v2", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "evaluationRules_create", + "key": "POST /api/public/v2/evaluation-rules", + "resource": "evaluation-rules", + "action": "create", + "aliases": [ + { + "resource": "evaluation-rules-v2", + "action": "create", + "source": "version" + } + ] + }, + { + "operationId": "evaluationRules_delete", + "key": "DELETE /api/public/v2/evaluation-rules/{evaluationRuleId}", + "resource": "evaluation-rules", + "action": "delete", + "aliases": [ + { + "resource": "evaluation-rules-v2", + "action": "delete", + "source": "version" + } + ] + }, + { + "operationId": "evaluationRules_get", + "key": "GET /api/public/v2/evaluation-rules/{evaluationRuleId}", + "resource": "evaluation-rules", + "action": "get", + "aliases": [ + { + "resource": "evaluation-rules-v2", + "action": "get", + "source": "version" + } + ] + }, + { + "operationId": "evaluationRules_list", + "key": "GET /api/public/v2/evaluation-rules", + "resource": "evaluation-rules", + "action": "list", + "aliases": [ + { + "resource": "evaluation-rules-v2", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "evaluationRules_update", + "key": "PATCH /api/public/v2/evaluation-rules/{evaluationRuleId}", + "resource": "evaluation-rules", + "action": "update", + "aliases": [ + { + "resource": "evaluation-rules-v2", + "action": "update", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_create", + "key": "POST /api/public/v2/evaluators", + "resource": "evaluators", + "action": "create", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "create", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_delete", + "key": "DELETE /api/public/v2/evaluators/{evaluatorId}", + "resource": "evaluators", + "action": "delete", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "delete", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_get", + "key": "GET /api/public/v2/evaluators/{evaluatorId}", + "resource": "evaluators", + "action": "get", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "get", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_list", + "key": "GET /api/public/v2/evaluators", + "resource": "evaluators", + "action": "list", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_listVersions", + "key": "GET /api/public/v2/evaluators/{evaluatorId}/versions", + "resource": "evaluators", + "action": "list-versions", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "list-versions", + "source": "version" + } + ] + }, + { + "operationId": "evaluators_update", + "key": "PATCH /api/public/v2/evaluators/{evaluatorId}", + "resource": "evaluators", + "action": "update", + "aliases": [ + { + "resource": "evaluators-v2", + "action": "update", + "source": "version" + } + ] + }, + { + "operationId": "experiments_list", + "key": "GET /api/public/experiments", + "resource": "experiments", + "action": "list" + }, + { + "operationId": "experiments_listItems", + "key": "GET /api/public/experiment-items", + "resource": "experiment-items", + "action": "list" + }, + { + "operationId": "feedback_submit", + "key": "POST /api/public/feedback", + "resource": "feedback", + "action": "submit" + }, + { + "operationId": "health_health", + "key": "GET /api/public/health", + "resource": "health", + "action": "get" + }, + { + "operationId": "ingestion_batch", + "key": "POST /api/public/ingestion", + "resource": "legacy-ingestion", + "action": "batch", + "aliases": [ + { + "resource": "ingestion", + "action": "batch", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "legacy_metricsV1_metrics", + "key": "GET /api/public/metrics", + "resource": "legacy-metrics", + "action": "get", + "aliases": [ + { + "resource": "legacy-metrics-v1", + "action": "get", + "source": "tag" + } + ], + "deprecated": true + }, + { + "operationId": "legacy_observationsV1_get", + "key": "GET /api/public/observations/{observationId}", + "resource": "legacy-observations", + "action": "get", + "aliases": [ + { + "resource": "observations", + "action": "get", + "source": "path" + }, + { + "resource": "legacy-observations-v1", + "action": "get", + "source": "tag" + } + ], + "deprecated": true + }, + { + "operationId": "legacy_observationsV1_getMany", + "key": "GET /api/public/observations", + "resource": "legacy-observations", + "action": "list", + "aliases": [ + { + "resource": "legacy-observations-v1", + "action": "list", + "source": "tag" + } + ], + "deprecated": true + }, + { + "operationId": "legacy_scoreV1_delete", + "key": "DELETE /api/public/scores/{scoreId}", + "resource": "scores", + "action": "delete", + "aliases": [ + { + "resource": "legacy-score-v1", + "action": "delete", + "source": "tag" + } + ] + }, + { + "operationId": "llmConnections_delete", + "key": "DELETE /api/public/llm-connections/{id}", + "resource": "llm-connections", + "action": "delete" + }, + { + "operationId": "llmConnections_list", + "key": "GET /api/public/llm-connections", + "resource": "llm-connections", + "action": "list" + }, + { + "operationId": "llmConnections_upsert", + "key": "PUT /api/public/llm-connections", + "resource": "llm-connections", + "action": "upsert" + }, + { + "operationId": "media_get", + "key": "GET /api/public/media/{mediaId}", + "resource": "media", + "action": "get" + }, + { + "operationId": "media_getUploadUrl", + "key": "POST /api/public/media", + "resource": "media", + "action": "get-upload-url" + }, + { + "operationId": "media_patch", + "key": "PATCH /api/public/media/{mediaId}", + "resource": "media", + "action": "update" + }, + { + "operationId": "metrics_metrics", + "key": "GET /api/public/v2/metrics", + "resource": "metrics", + "action": "get", + "aliases": [ + { + "resource": "metrics-v2", + "action": "get", + "source": "version" + } + ] + }, + { + "operationId": "models_create", + "key": "POST /api/public/models", + "resource": "models", + "action": "create" + }, + { + "operationId": "models_delete", + "key": "DELETE /api/public/models/{id}", + "resource": "models", + "action": "delete" + }, + { + "operationId": "models_get", + "key": "GET /api/public/models/{id}", + "resource": "models", + "action": "get" + }, + { + "operationId": "models_list", + "key": "GET /api/public/models", + "resource": "models", + "action": "list" + }, + { + "operationId": "models_upsert", + "key": "PUT /api/public/models/{id}", + "resource": "models", + "action": "upsert" + }, + { + "operationId": "observations_getMany", + "key": "GET /api/public/v2/observations", + "resource": "observations", + "action": "list", + "aliases": [ + { + "resource": "observations-v2", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "opentelemetry_exportTraces", + "key": "POST /api/public/otel/v1/traces", + "resource": "otel", + "action": "export-traces", + "aliases": [ + { + "resource": "otel-v1", + "action": "export-traces", + "source": "version" + }, + { + "resource": "opentelemetry", + "action": "export-traces", + "source": "tag" + } + ] + }, + { + "operationId": "organizations_deleteOrganizationMembership", + "key": "DELETE /api/public/organizations/memberships", + "resource": "organizations", + "action": "delete-membership" + }, + { + "operationId": "organizations_deleteProjectMembership", + "key": "DELETE /api/public/projects/{projectId}/memberships", + "resource": "projects", + "action": "delete-membership" + }, + { + "operationId": "organizations_getOrganizationApiKeys", + "key": "GET /api/public/organizations/apiKeys", + "resource": "organizations", + "action": "list-api-keys" + }, + { + "operationId": "organizations_getOrganizationMemberships", + "key": "GET /api/public/organizations/memberships", + "resource": "organizations", + "action": "list-memberships" + }, + { + "operationId": "organizations_getOrganizationProjects", + "key": "GET /api/public/organizations/projects", + "resource": "organizations", + "action": "list-projects" + }, + { + "operationId": "organizations_getProjectMemberships", + "key": "GET /api/public/projects/{projectId}/memberships", + "resource": "projects", + "action": "list-memberships" + }, + { + "operationId": "organizations_updateOrganizationMembership", + "key": "PUT /api/public/organizations/memberships", + "resource": "organizations", + "action": "update-membership" + }, + { + "operationId": "organizations_updateProjectMembership", + "key": "PUT /api/public/projects/{projectId}/memberships", + "resource": "projects", + "action": "update-membership" + }, + { + "operationId": "projects_create", + "key": "POST /api/public/projects", + "resource": "projects", + "action": "create" + }, + { + "operationId": "projects_createApiKey", + "key": "POST /api/public/projects/{projectId}/apiKeys", + "resource": "projects", + "action": "create-api-key" + }, + { + "operationId": "projects_delete", + "key": "DELETE /api/public/projects/{projectId}", + "resource": "projects", + "action": "delete" + }, + { + "operationId": "projects_deleteApiKey", + "key": "DELETE /api/public/projects/{projectId}/apiKeys/{apiKeyId}", + "resource": "projects", + "action": "delete-api-key" + }, + { + "operationId": "projects_get", + "key": "GET /api/public/projects", + "resource": "projects", + "action": "list" + }, + { + "operationId": "projects_getApiKeys", + "key": "GET /api/public/projects/{projectId}/apiKeys", + "resource": "projects", + "action": "list-api-keys" + }, + { + "operationId": "projects_update", + "key": "PUT /api/public/projects/{projectId}", + "resource": "projects", + "action": "update" + }, + { + "operationId": "promptVersion_update", + "key": "PATCH /api/public/v2/prompts/{name}/versions/{version}", + "resource": "prompts", + "action": "update-version", + "aliases": [ + { + "resource": "prompts-v2", + "action": "update-version", + "source": "version" + }, + { + "resource": "prompt-version", + "action": "update-version", + "source": "tag" + } + ] + }, + { + "operationId": "prompts_create", + "key": "POST /api/public/v2/prompts", + "resource": "prompts", + "action": "create", + "aliases": [ + { + "resource": "prompts-v2", + "action": "create", + "source": "version" + } + ] + }, + { + "operationId": "prompts_delete", + "key": "DELETE /api/public/v2/prompts/{promptName}", + "resource": "prompts", + "action": "delete", + "aliases": [ + { + "resource": "prompts-v2", + "action": "delete", + "source": "version" + } + ] + }, + { + "operationId": "prompts_get", + "key": "GET /api/public/v2/prompts/{promptName}", + "resource": "prompts", + "action": "get", + "aliases": [ + { + "resource": "prompts-v2", + "action": "get", + "source": "version" + } + ] + }, + { + "operationId": "prompts_list", + "key": "GET /api/public/v2/prompts", + "resource": "prompts", + "action": "list", + "aliases": [ + { + "resource": "prompts-v2", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "scim_createUser", + "key": "POST /api/public/scim/Users", + "resource": "scim", + "action": "create-user" + }, + { + "operationId": "scim_deleteUser", + "key": "DELETE /api/public/scim/Users/{userId}", + "resource": "scim", + "action": "delete-user" + }, + { + "operationId": "scim_getResourceTypes", + "key": "GET /api/public/scim/ResourceTypes", + "resource": "scim", + "action": "list-resource-types" + }, + { + "operationId": "scim_getSchemas", + "key": "GET /api/public/scim/Schemas", + "resource": "scim", + "action": "list-schemas" + }, + { + "operationId": "scim_getServiceProviderConfig", + "key": "GET /api/public/scim/ServiceProviderConfig", + "resource": "scim", + "action": "get-service-provider-config" + }, + { + "operationId": "scim_getUser", + "key": "GET /api/public/scim/Users/{userId}", + "resource": "scim", + "action": "get-user" + }, + { + "operationId": "scim_listUsers", + "key": "GET /api/public/scim/Users", + "resource": "scim", + "action": "list-users" + }, + { + "operationId": "scoreConfigs_create", + "key": "POST /api/public/score-configs", + "resource": "score-configs", + "action": "create" + }, + { + "operationId": "scoreConfigs_get", + "key": "GET /api/public/score-configs", + "resource": "score-configs", + "action": "list" + }, + { + "operationId": "scoreConfigs_get-by-id", + "key": "GET /api/public/score-configs/{configId}", + "resource": "score-configs", + "action": "get" + }, + { + "operationId": "scoreConfigs_update", + "key": "PATCH /api/public/score-configs/{configId}", + "resource": "score-configs", + "action": "update" + }, + { + "operationId": "scoresV3_getManyV3", + "key": "GET /api/public/v3/scores", + "resource": "scores", + "action": "list", + "aliases": [ + { + "resource": "scores-v3", + "action": "list", + "source": "version" + } + ] + }, + { + "operationId": "scores_create", + "key": "POST /api/public/scores", + "resource": "scores", + "action": "create" + }, + { + "operationId": "scores_get-by-id", + "key": "GET /api/public/v2/scores/{scoreId}", + "resource": "scores-v2", + "action": "get", + "aliases": [ + { + "resource": "scores", + "action": "get", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "scores_get-many", + "key": "GET /api/public/v2/scores", + "resource": "scores-v2", + "action": "list", + "deprecated": true + }, + { + "operationId": "sessions_get", + "key": "GET /api/public/sessions/{sessionId}", + "resource": "legacy-sessions", + "action": "get", + "aliases": [ + { + "resource": "sessions", + "action": "get", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "sessions_list", + "key": "GET /api/public/sessions", + "resource": "legacy-sessions", + "action": "list", + "aliases": [ + { + "resource": "sessions", + "action": "list", + "source": "path" + } + ], + "deprecated": true + }, + { + "operationId": "trace_delete", + "key": "DELETE /api/public/traces/{traceId}", + "resource": "traces", + "action": "delete", + "aliases": [ + { + "resource": "trace", + "action": "delete", + "source": "tag" + } + ] + }, + { + "operationId": "trace_deleteMultiple", + "key": "DELETE /api/public/traces", + "resource": "traces", + "action": "delete-many", + "aliases": [ + { + "resource": "trace", + "action": "delete-many", + "source": "tag" + } + ] + }, + { + "operationId": "trace_get", + "key": "GET /api/public/traces/{traceId}", + "resource": "legacy-traces", + "action": "get", + "aliases": [ + { + "resource": "traces", + "action": "get", + "source": "path" + }, + { + "resource": "trace", + "action": "get", + "source": "tag" + } + ], + "deprecated": true + }, + { + "operationId": "trace_list", + "key": "GET /api/public/traces", + "resource": "legacy-traces", + "action": "list", + "aliases": [ + { + "resource": "traces", + "action": "list", + "source": "path" + }, + { + "resource": "trace", + "action": "list", + "source": "tag" + } + ], + "deprecated": true + }, + { + "operationId": "unstable_dashboardWidgets_create", + "key": "POST /api/public/unstable/dashboard-widgets", + "resource": "unstable-dashboard-widgets", + "action": "create" + }, + { + "operationId": "unstable_dashboardWidgets_delete", + "key": "DELETE /api/public/unstable/dashboard-widgets/{widgetId}", + "resource": "unstable-dashboard-widgets", + "action": "delete" + }, + { + "operationId": "unstable_dashboardWidgets_get", + "key": "GET /api/public/unstable/dashboard-widgets/{widgetId}", + "resource": "unstable-dashboard-widgets", + "action": "get" + }, + { + "operationId": "unstable_dashboardWidgets_list", + "key": "GET /api/public/unstable/dashboard-widgets", + "resource": "unstable-dashboard-widgets", + "action": "list" + }, + { + "operationId": "unstable_dashboardWidgets_update", + "key": "PATCH /api/public/unstable/dashboard-widgets/{widgetId}", + "resource": "unstable-dashboard-widgets", + "action": "update" + }, + { + "operationId": "unstable_dashboards_addPlacement", + "key": "POST /api/public/unstable/dashboards/{dashboardId}/placements", + "resource": "unstable-dashboards", + "action": "add-placement" + }, + { + "operationId": "unstable_dashboards_create", + "key": "POST /api/public/unstable/dashboards", + "resource": "unstable-dashboards", + "action": "create" + }, + { + "operationId": "unstable_dashboards_delete", + "key": "DELETE /api/public/unstable/dashboards/{dashboardId}", + "resource": "unstable-dashboards", + "action": "delete" + }, + { + "operationId": "unstable_dashboards_deletePlacement", + "key": "DELETE /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}", + "resource": "unstable-dashboards", + "action": "delete-placement" + }, + { + "operationId": "unstable_dashboards_get", + "key": "GET /api/public/unstable/dashboards/{dashboardId}", + "resource": "unstable-dashboards", + "action": "get" + }, + { + "operationId": "unstable_dashboards_list", + "key": "GET /api/public/unstable/dashboards", + "resource": "unstable-dashboards", + "action": "list" + }, + { + "operationId": "unstable_dashboards_update", + "key": "PATCH /api/public/unstable/dashboards/{dashboardId}", + "resource": "unstable-dashboards", + "action": "update" + }, + { + "operationId": "unstable_dashboards_updatePlacement", + "key": "PATCH /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}", + "resource": "unstable-dashboards", + "action": "update-placement" + }, + { + "operationId": "unstable_skills_createVersion", + "key": "POST /api/public/unstable/skills", + "resource": "skills", + "action": "create" + }, + { + "operationId": "unstable_skills_deleteVersion", + "key": "DELETE /api/public/unstable/skills/{skillName}/versions/{skillVersion}", + "resource": "skills", + "action": "delete-version" + }, + { + "operationId": "unstable_skills_get", + "key": "GET /api/public/unstable/skills/{skillName}", + "resource": "skills", + "action": "get" + }, + { + "operationId": "unstable_skills_getFileContents", + "key": "GET /api/public/unstable/skills/files/content", + "resource": "skills", + "action": "list-content" + }, + { + "operationId": "unstable_skills_list", + "key": "GET /api/public/unstable/skills", + "resource": "skills", + "action": "list" + }, + { + "operationId": "unstable_skills_setLabels", + "key": "PATCH /api/public/unstable/skills/{skillName}/versions/{skillVersion}", + "resource": "skills", + "action": "update-version" + }, + { + "operationId": "unstable_skills_update", + "key": "PATCH /api/public/unstable/skills/{skillName}", + "resource": "skills", + "action": "update" + } +] diff --git a/conformance/specs/4.48.0/openapi.yml b/conformance/specs/4.48.0/openapi.yml new file mode 100644 index 0000000..cebaa95 --- /dev/null +++ b/conformance/specs/4.48.0/openapi.yml @@ -0,0 +1,18035 @@ +openapi: 3.0.1 +info: + title: server + version: '' + description: >- + ## Real-time data + + + The only real-time path to get tracing data is to ingest via OpenTelemetry + (`POST /api/public/otel/v1/traces`) and retrieve via Observations API v2 + (`GET /api/public/v2/observations`) and Metrics API v2 (`GET + /api/public/v2/metrics`). Other public API write and read endpoints can + delay data by about 10 minutes. Direct OpenTelemetry exporters must send the + `x-langfuse-ingestion-version: 4` header; current Python and JS SDKs already + do. See the [Public API + docs](https://langfuse.com/docs/api-and-data-platform/features/public-api) + and [real-time + ingestion](https://langfuse.com/integrations/native/opentelemetry.md#real-time-ingestion). + + + ## Authentication + + + Authenticate with the API using [Basic + Auth](https://en.wikipedia.org/wiki/Basic_access_authentication), get API + keys in the project settings: + + + - username: Langfuse Public Key + + - password: Langfuse Secret Key + + + ## Exports + + + - OpenAPI spec: https://cloud.langfuse.com/generated/api/openapi.yml + + - Self-hosted deployments: interactive API reference at `/api/docs` and + OpenAPI spec at `/api/openapi.yaml` +paths: + /api/public/annotation-queues: + get: + description: Get all annotation queues + operationId: annotationQueues_listQueues + tags: + - AnnotationQueues + parameters: + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedAnnotationQueues' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: &ref_0 + - BasicAuth: [] + post: + description: Create an annotation queue + operationId: annotationQueues_createQueue + tags: + - AnnotationQueues + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueue' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAnnotationQueueRequest' + /api/public/annotation-queues/{queueId}: + get: + description: Get an annotation queue by ID + operationId: annotationQueues_getQueue + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueue' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/annotation-queues/{queueId}/items: + get: + description: Get items for a specific annotation queue + operationId: annotationQueues_listQueueItems + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + - name: status + in: query + description: Filter by status + required: false + schema: + $ref: '#/components/schemas/AnnotationQueueStatus' + nullable: true + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedAnnotationQueueItems' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: Add an item to an annotation queue + operationId: annotationQueues_createQueueItem + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueueItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAnnotationQueueItemRequest' + /api/public/annotation-queues/{queueId}/items/{itemId}: + get: + description: Get a specific item from an annotation queue + operationId: annotationQueues_getQueueItem + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + - name: itemId + in: path + description: The unique identifier of the annotation queue item + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueueItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + patch: + description: Update an annotation queue item + operationId: annotationQueues_updateQueueItem + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + - name: itemId + in: path + description: The unique identifier of the annotation queue item + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueueItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAnnotationQueueItemRequest' + delete: + description: Remove an item from an annotation queue + operationId: annotationQueues_deleteQueueItem + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + - name: itemId + in: path + description: The unique identifier of the annotation queue item + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteAnnotationQueueItemResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/annotation-queues/{queueId}/assignments: + post: + description: Create an assignment for a user to an annotation queue + operationId: annotationQueues_createQueueAssignment + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAnnotationQueueAssignmentResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueueAssignmentRequest' + delete: + description: Delete an assignment for a user to an annotation queue + operationId: annotationQueues_deleteQueueAssignment + tags: + - AnnotationQueues + parameters: + - name: queueId + in: path + description: The unique identifier of the annotation queue + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteAnnotationQueueAssignmentResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationQueueAssignmentRequest' + /api/public/integrations/blob-storage: + get: + description: >- + Get all blob storage integrations for the organization (requires + organization-scoped API key) + operationId: blobStorageIntegrations_getBlobStorageIntegrations + tags: + - BlobStorageIntegrations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/BlobStorageIntegrationsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + put: + description: >- + Create or update a blob storage integration for a specific project + (requires organization-scoped API key). The configuration is validated + by performing a test upload to the bucket. + operationId: blobStorageIntegrations_upsertBlobStorageIntegration + tags: + - BlobStorageIntegrations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/BlobStorageIntegrationResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBlobStorageIntegrationRequest' + /api/public/integrations/blob-storage/{id}: + get: + description: >- + Get the sync status of a blob storage integration by integration ID + (requires organization-scoped API key) + operationId: blobStorageIntegrations_getBlobStorageIntegrationStatus + tags: + - BlobStorageIntegrations + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/BlobStorageIntegrationStatusResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + delete: + description: >- + Delete a blob storage integration by ID (requires organization-scoped + API key) + operationId: blobStorageIntegrations_deleteBlobStorageIntegration + tags: + - BlobStorageIntegrations + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/BlobStorageIntegrationDeletionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/comments: + post: + description: >- + Create a comment. Comments may be attached to different object types + (trace, observation, session, prompt). + operationId: comments_create + tags: + - Comments + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCommentResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateCommentRequest' + get: + description: Get all comments + operationId: comments_get + tags: + - Comments + parameters: + - name: page + in: query + description: Page number, starts at 1. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. If you encounter api issues due to too + large page sizes, try to reduce the limit + required: false + schema: + type: integer + nullable: true + - name: objectType + in: query + description: >- + Filter comments by object type (trace, observation, session, prompt). + required: false + schema: + type: string + nullable: true + - name: objectId + in: query + description: >- + Filter comments by object id. If objectType is not provided, an + error will be thrown. + required: false + schema: + type: string + nullable: true + - name: authorUserId + in: query + description: Filter comments by author user id. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GetCommentsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/comments/{commentId}: + get: + description: Get a comment by id + operationId: comments_get-by-id + tags: + - Comments + parameters: + - name: commentId + in: path + description: The unique langfuse identifier of a comment + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Comment' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/dataset-items: + post: + description: Create a dataset item + operationId: datasetItems_create + tags: + - DatasetItems + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DatasetItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDatasetItemRequest' + get: + description: >- + Get dataset items. Optionally specify a version to get the items as they + existed at that point in time. + + Note: If version parameter is provided, datasetName must also be + provided. + operationId: datasetItems_list + tags: + - DatasetItems + parameters: + - name: datasetName + in: query + required: false + schema: + type: string + nullable: true + - name: sourceTraceId + in: query + required: false + schema: + type: string + nullable: true + - name: sourceObservationId + in: query + required: false + schema: + type: string + nullable: true + - name: version + in: query + description: >- + ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g., + "2026-01-21T14:35:42Z"). + + If provided, returns state of dataset at this timestamp. + + If not provided, returns the latest version. Requires datasetName to + be specified. + required: false + schema: + type: string + format: date-time + nullable: true + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedDatasetItems' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/dataset-items/{id}: + get: + description: Get a dataset item + operationId: datasetItems_get + tags: + - DatasetItems + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DatasetItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + delete: + description: >- + Delete a dataset item and all its run items. This action is irreversible. + operationId: datasetItems_delete + tags: + - DatasetItems + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteDatasetItemResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/dataset-run-items: + post: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, create + experiment data via the SDK experiment runner or the OpenTelemetry + endpoint at POST /api/public/otel/v1/traces. Self-hosted deployments are + unaffected by this date; the endpoint becomes unavailable when they + upgrade to Langfuse v4. See the [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Create a dataset run item + operationId: datasetRunItems_create + tags: + - DatasetRunItems + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DatasetRunItem' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDatasetRunItemRequest' + deprecated: true + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, dataset + run items are replaced by experiment items; use `GET + /api/public/experiment-items?fromStartTime=&toStartTime=` + instead. Self-hosted deployments are unaffected by this date; the + endpoint becomes unavailable when they upgrade to Langfuse v4. See the + [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + List dataset run items + operationId: datasetRunItems_list + tags: + - DatasetRunItems + parameters: + - name: datasetId + in: query + required: true + schema: + type: string + - name: runName + in: query + required: true + schema: + type: string + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedDatasetRunItems' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/v2/datasets: + get: + description: Get all datasets + operationId: datasets_list + tags: + - Datasets + parameters: + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedDatasets' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: Create a dataset + operationId: datasets_create + tags: + - Datasets + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Dataset' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDatasetRequest' + /api/public/v2/datasets/{datasetName}: + get: + description: Get a dataset + operationId: datasets_get + tags: + - Datasets + parameters: + - name: datasetName + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Dataset' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/datasets/{datasetName}/runs/{runName}: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, dataset + runs are replaced by experiments; use GET /api/public/experiments + instead. Self-hosted deployments are unaffected by this date; the + endpoint becomes unavailable when they upgrade to Langfuse v4. See the + [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a dataset run and its items + operationId: datasets_getRun + tags: + - Datasets + parameters: + - name: datasetName + in: path + required: true + schema: + type: string + - name: runName + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DatasetRunWithItems' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + delete: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, dataset + runs are replaced by experiments. Self-hosted deployments are unaffected + by this date; the endpoint becomes unavailable when they upgrade to + Langfuse v4. See the [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Delete a dataset run and all its run items. This action is irreversible. + operationId: datasets_deleteRun + tags: + - Datasets + parameters: + - name: datasetName + in: path + required: true + schema: + type: string + - name: runName + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteDatasetRunResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/datasets/{datasetName}/runs: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, dataset + runs are replaced by experiments; use GET /api/public/experiments + instead. Self-hosted deployments are unaffected by this date; the + endpoint becomes unavailable when they upgrade to Langfuse v4. See the + [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get dataset runs + operationId: datasets_getRuns + tags: + - Datasets + parameters: + - name: datasetName + in: path + required: true + schema: + type: string + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedDatasetRuns' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/v2/evaluation-rules: + post: + description: >- + Create an evaluation rule using stable evaluator identifiers. + + + An evaluation rule defines **which** incoming observations should be + evaluated and how prompt variables should be populated. + + + Key behavior: + + - rule names are not identifiers and do not need to be unique + + - rules always use the latest version of each associated evaluator + + - an enabled rule requires at least one evaluator assignment + + - omit `sampling` to evaluate every matching observation + + - omit `filter` to match every incoming observation + + - `datasetId` is the public filter name for selecting experiment + datasets + operationId: evaluationRules_create + tags: + - EvaluationRules + parameters: [] + responses: + '201': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateEvaluationRuleRequest' + get: + description: >- + List evaluation rules in newest-first creation order. + + + This includes legacy trace and dataset rules so they can be inspected + and migrated. Treat the cursor as opaque and return it unchanged. + operationId: evaluationRules_list + tags: + - EvaluationRules + parameters: + - name: limit + in: query + description: >- + Maximum number of items to return. Defaults to `50` and cannot + exceed `100`. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: Opaque cursor returned by the previous page. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRulesPage' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + /api/public/v2/evaluation-rules/{evaluationRuleId}: + get: + description: >- + Get one evaluation rule, including a legacy trace or dataset rule, by + its stable identifier. + operationId: evaluationRules_get + tags: + - EvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: >- + Stable evaluation-rule identifier returned by the evaluation-rule + endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + patch: + description: >- + Update an evaluation rule by its stable identifier. + + + Provide only the fields to change. Providing `evaluatorAssignments` + replaces the complete assignment list. Replacing the list with an empty + array disables the rule. Setting `enabled=true` is rejected when the + resulting assignment list is empty, including when both fields are sent + in the same request. + + + Legacy trace and dataset rules follow the existing lifecycle + restrictions: they can be deactivated with `enabled=false`, but their + name, filters, sampling, and evaluator assignments cannot be changed. + operationId: evaluationRules_update + tags: + - EvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: >- + Stable evaluation-rule identifier returned by the evaluation-rule + endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateEvaluationRuleRequest' + delete: + description: >- + Delete an evaluation rule. + + + This removes the live-ingestion rule only. It does not delete associated + evaluators or scores already produced by them. + + + Legacy trace and dataset rules can also be deleted. Their evaluators and + previously produced scores are preserved. + operationId: evaluationRules_delete + tags: + - EvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: >- + Stable evaluation-rule identifier returned by the evaluation-rule + endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedEvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + /api/public/v2/evaluators: + post: + description: >- + Create an evaluator in the authenticated project. + + + An evaluator defines **how** Langfuse should score data. LLM-as-a-judge + evaluators define a prompt, expected structured output, and optional + model configuration. Code evaluators define source code and a runtime + language. + + + This always creates a new evaluator with version `1`. Names are not + identifiers and do not need to be unique. + operationId: evaluators_create + tags: + - Evaluators + parameters: [] + responses: + '201': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Evaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '412': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateEvaluatorRequest' + get: + description: >- + List evaluators in newest-first creation order. + + + Every evaluator includes its latest definition and version metadata + flattened into the evaluator object, plus associated evaluation rules. + Treat the cursor as opaque and return it unchanged. + operationId: evaluators_list + tags: + - Evaluators + parameters: + - name: limit + in: query + description: >- + Maximum number of items to return. Defaults to `50` and cannot + exceed `100`. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: Opaque cursor returned by the previous page. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluatorsPage' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + /api/public/v2/evaluators/{evaluatorId}: + get: + description: >- + Get one evaluator by its stable identifier. + + + The response includes the evaluator's latest definition and version + metadata flattened into the evaluator object, plus associated evaluation + rules. Use the version-history endpoint when older definitions are + needed. + operationId: evaluators_get + tags: + - Evaluators + parameters: + - name: evaluatorId + in: path + description: Stable evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Evaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + patch: + description: >- + Update an evaluator by its stable identifier. + + + Provide only the top-level fields to change. Metadata-only changes do + not create a version. Evaluator type cannot change. + + + Definition fields are flattened into the request. To replace a + definition, include `type` and every definition field for that type. + Definition fields are replaced as a complete unit rather than merged. + For LLM-as-a-judge evaluators, omitting or setting `modelConfig` to + `null` selects the project's default evaluation model. + + + Replacing a definition automatically returns an evaluator paused by an + invalid or missing model configuration to `active`, while preserving its + id and evaluation-rule assignments. Pauses caused by provider + authentication, billing, connectivity, account state, or an unknown + legacy reason remain paused until the explicit reactivation check + succeeds. + operationId: evaluators_update + tags: + - Evaluators + parameters: + - name: evaluatorId + in: path + description: Stable evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Evaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '412': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateEvaluatorRequest' + delete: + description: >- + Delete an evaluator and all of its stored versions. + + + Associated evaluation-rule assignments are also removed. Scores already + produced by the evaluator are preserved. + operationId: evaluators_delete + tags: + - Evaluators + parameters: + - name: evaluatorId + in: path + description: Stable evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedEvaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + /api/public/v2/evaluators/{evaluatorId}/versions: + get: + description: >- + List an evaluator's version history in newest-first order. + + + This endpoint is intended for history and audit use cases. Ordinary + clients can use the flattened `version` and definition fields on the + evaluator response. + operationId: evaluators_listVersions + tags: + - Evaluators + parameters: + - name: evaluatorId + in: path + description: Stable evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + - name: limit + in: query + description: >- + Maximum number of versions to return. Defaults to `50` and cannot + exceed `100`. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: Opaque cursor returned by the previous page. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluatorVersionsPage' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PublicApiError' + security: *ref_0 + /api/public/experiments: + get: + description: |- + List experiments with cursor-based pagination. Results are ordered by + latest experiment activity descending. + operationId: experiments_list + tags: + - Experiments + parameters: + - name: fields + in: query + description: |- + Comma-separated list of field groups to include. Available groups: + `core`, `metadata`, `scores`. If omitted, `core` is returned. + required: false + schema: + type: string + nullable: true + - name: limit + in: query + description: Number of experiments to return per page. Maximum 100, default 50. + required: false + schema: + type: integer + nullable: true + - name: scoreLimit + in: query + description: >- + Number of scores to return per experiment when `fields=scores` is + requested. Maximum 50, default 50. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: Versioned base64url cursor from the previous response page. + required: false + schema: + type: string + nullable: true + - name: fromStartTime + in: query + description: |- + Required. Retrieve only experiments with events on or after this + datetime. A lower bound is required so the query stays fast on + large projects; pair it with `toStartTime` to select a specific + window. + required: true + schema: + type: string + format: date-time + - name: toStartTime + in: query + description: Retrieve only experiments before this datetime. + required: false + schema: + type: string + format: date-time + nullable: true + - name: id + in: query + description: Comma-separated list of experiment IDs. + required: false + schema: + type: string + nullable: true + - name: name + in: query + description: Comma-separated list of experiment names. + required: false + schema: + type: string + nullable: true + - name: datasetId + in: query + description: Comma-separated list of dataset IDs. + required: false + schema: + type: string + nullable: true + - name: filter + in: query + description: |- + JSON string containing an array of structured filter conditions. + Supported columns are `id`, `name`, and `datasetId`. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ExperimentsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/experiment-items: + get: + description: |- + List experiment items with cursor-based pagination. Use this endpoint + to export experiment item inputs, outputs, expected outputs, metadata, + and optionally item/trace scores. Results are ordered by time + descending. + operationId: experiments_listItems + tags: + - Experiments + parameters: + - name: fields + in: query + description: |- + Comma-separated list of field groups to include. Available groups: + `core`, `dataset`, `io`, `metadata`, `itemMetadata`, + `experimentMetadata`, `scores`. If omitted, `core,dataset` is + returned. + required: false + schema: + type: string + nullable: true + - name: limit + in: query + description: >- + Number of experiment items to return per page. Maximum 100, default + 50. + required: false + schema: + type: integer + nullable: true + - name: scoreLimit + in: query + description: >- + Number of scores to return per experiment item when `fields=scores` + is requested. Maximum 50, default 50. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: Versioned base64url cursor from the previous response page. + required: false + schema: + type: string + nullable: true + - name: fromStartTime + in: query + description: |- + Required. Retrieve only experiment items started on or after this + datetime. A lower bound is required so the query stays fast on + large projects; pair it with `toStartTime` to select a specific + window. + required: true + schema: + type: string + format: date-time + - name: toStartTime + in: query + description: Retrieve only experiment items started before this datetime. + required: false + schema: + type: string + format: date-time + nullable: true + - name: experimentId + in: query + description: Comma-separated list of experiment IDs. + required: false + schema: + type: string + nullable: true + - name: experimentName + in: query + description: Comma-separated list of experiment names. + required: false + schema: + type: string + nullable: true + - name: experimentItemId + in: query + description: Comma-separated list of experiment item IDs. + required: false + schema: + type: string + nullable: true + - name: datasetId + in: query + description: Comma-separated list of dataset IDs. + required: false + schema: + type: string + nullable: true + - name: filter + in: query + description: |- + JSON string containing an array of structured filter conditions. + Supported columns are `experimentId`, `experimentName`, + `experimentItemId`, and `datasetId`. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ExperimentItemsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/feedback: + post: + description: >- + Submit explicit user-approved feedback about Langfuse skills, MCP tools, + CLI, docs, or public API. Do not include secrets, credentials, customer + data, trace payloads, or unrelated use-case details. + + + Not available in the HIPAA cloud region. + operationId: feedback_submit + tags: + - Feedback + parameters: [] + responses: + '201': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFeedbackResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFeedbackRequest' + /api/public/health: + get: + description: Check health of API and database + operationId: health_health + tags: + - Health + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/HealthResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '503': + description: '' + /api/public/ingestion: + post: + description: >- + **Deprecated:** On Langfuse Cloud, this is the deprecated Langfuse v3 + ingestion API and it is shut down on November 16, 2026, except for score + events: from that date it accepts only `score-create` events and rejects + all other event types. To write scores, prefer `POST + /api/public/scores`; see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs; if you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint at `POST /api/public/otel/v1/traces` (for + example with curl); see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`; all other + public APIs may have data delays of several minutes. Self-hosted + deployments are unaffected by the November 16 date; this behavior begins + only when they enable v4-only write mode. See the [Langfuse v3 to v4 + upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + **Legacy endpoint for batch ingestion for Langfuse Observability.** + + + This is the deprecated Langfuse v3 ingestion API. It is shut down on + November 16, 2026, except for score events: from that date it accepts + only `score-create` events and rejects all other event types. + + + To write scores, prefer `POST /api/public/scores`: + https://langfuse.com/docs/api-and-data-platform/features/scores-api + + + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl: + https://langfuse.com/integrations/native/opentelemetry + + + To read data back, use the v4 read APIs: + https://langfuse.com/docs/api-and-data-platform/features/observations-api + and https://langfuse.com/docs/metrics/features/metrics-api + + + The only path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + + + Within each batch, there can be multiple events. + + Each event has a type, an id, a timestamp, metadata and a body. + + Internally, we refer to this as the "event envelope" as it tells us + something about the event but not the trace. + + We use the event id within this envelope to deduplicate messages to + avoid processing the same event twice, i.e. the event id should be + unique per request. + + The event.body.id is the ID of the actual trace and will be used for + updates and will be visible within the Langfuse App. + + I.e. if you want to update a trace, you'd use the same body id, but + separate event IDs. + + + Notes: + + - Introduction to data model: + https://langfuse.com/docs/observability/data-model + + - Batch sizes are limited to 3.5 MB in total. You need to adjust the + number of events per batch accordingly. + + - The API does not return a 4xx status code for input errors. Instead, + it responds with a 207 status code, which includes a list of the + encountered errors. + operationId: ingestion_batch + tags: + - Ingestion + parameters: [] + responses: + '207': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/IngestionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + batch: + type: array + items: + $ref: '#/components/schemas/IngestionEvent' + description: >- + Batch of events to be ingested, discriminated by attribute + `type`. From November 16, 2026 on Langfuse Cloud, only + `score-create` events are accepted; all other event types + are rejected. + metadata: + nullable: true + description: >- + Optional. Metadata field used by the Langfuse SDKs for + debugging. + required: + - batch + deprecated: true + /api/public/metrics: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. Use `GET + /api/public/v2/metrics?query=` instead. + Self-hosted deployments are unaffected by this date; the endpoint + becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse + v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get metrics from the Langfuse project using a query object. + + + Consider using the [v2 metrics + endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for + better performance. + + + For more details, see the [Metrics API + documentation](https://langfuse.com/docs/metrics/features/metrics-api). + operationId: legacy_metricsV1_metrics + tags: + - LegacyMetricsV1 + parameters: + - name: query + in: query + description: >- + JSON string containing the query parameters with the following + structure: + + ```json + + { + "view": string, // Required. One of "traces", "observations", "scores-numeric", "scores-boolean", "scores-categorical" + "dimensions": [ // Optional. Default: [] + { + "field": string // Field to group by, e.g. "name", "userId", "sessionId" + } + ], + "metrics": [ // Required. At least one metric must be provided + { + "measure": string, // What to measure, e.g. "count", "latency", "value" + "aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram" + } + ], + "filters": [ // Optional. Default: [] + { + "column": string, // Column to filter on + "operator": string, // Operator, e.g. "=", ">", "<", "contains" + "value": any, // Value to compare against + "type": string, // Data type, e.g. "string", "number", "stringObject" + "key": string // Required only when filtering on metadata + } + ], + "timeDimension": { // Optional. Default: null. If provided, results will be grouped by time + "granularity": string // One of "minute", "hour", "day", "week", "month", "auto" + }, + "fromTimestamp": string, // Required. ISO datetime string for start of time range + "toTimestamp": string, // Required. ISO datetime string for end of time range + "orderBy": [ // Optional. Default: null + { + "field": string, // Field to order by + "direction": string // "asc" or "desc" + } + ], + "config": { // Optional. Query-specific configuration + "bins": number, // Optional. Number of bins for histogram (1-100), default: 10 + "row_limit": number // Optional. Row limit for results (1-1000) + } + } + + ``` + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/legacyMetricsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/observations/{observationId}: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. Use `GET + /api/public/v2/observations?fromStartTime=&toStartTime=` + instead. Self-hosted deployments are unaffected by this date; the + endpoint becomes unavailable when they upgrade to Langfuse v4. See the + [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a observation + operationId: legacy_observationsV1_get + tags: + - LegacyObservationsV1 + parameters: + - name: observationId + in: path + description: >- + The unique langfuse identifier of an observation, can be an event, + span or generation + required: true + schema: + type: string + - name: startTime + in: query + description: >- + The start time of the observation (ISO 8601 with offset, e.g. + 2024-01-01T00:00:00Z). Optional performance hint - when provided, + Langfuse narrows the lookup to make the request substantially + faster. It only affects speed - an incorrect or omitted value never + changes the result. + required: false + schema: + type: string + format: date-time + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ObservationsViewSingle' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/observations: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. Use `GET + /api/public/v2/observations?fromStartTime=&toStartTime=` + instead. Self-hosted deployments are unaffected by this date; the + endpoint becomes unavailable when they upgrade to Langfuse v4. See the + [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a list of observations. + + + Consider using the [v2 observations + endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations) + for cursor-based pagination and field selection. + operationId: legacy_observationsV1_getMany + tags: + - LegacyObservationsV1 + parameters: + - name: page + in: query + description: Page number, starts at 1. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. If you encounter api issues due to too + large page sizes, try to reduce the limit. + required: false + schema: + type: integer + nullable: true + - name: name + in: query + required: false + schema: + type: string + nullable: true + - name: userId + in: query + required: false + schema: + type: string + nullable: true + - name: type + in: query + required: false + schema: + type: string + nullable: true + - name: traceId + in: query + required: false + schema: + type: string + nullable: true + - name: level + in: query + description: >- + Optional filter for observations with a specific level (e.g. + "DEBUG", "DEFAULT", "WARNING", "ERROR"). + required: false + schema: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + - name: parentObservationId + in: query + required: false + schema: + type: string + nullable: true + - name: environment + in: query + description: >- + Optional filter for observations where the environment is one of the + provided values. + required: false + schema: + type: array + items: + type: string + nullable: true + - name: fromStartTime + in: query + description: >- + Retrieve only observations with a start_time on or after this + datetime (ISO 8601). + required: false + schema: + type: string + format: date-time + nullable: true + - name: toStartTime + in: query + description: >- + Retrieve only observations with a start_time before this datetime + (ISO 8601). + required: false + schema: + type: string + format: date-time + nullable: true + - name: version + in: query + description: Optional filter to only include observations with a certain version. + required: false + schema: + type: string + nullable: true + - name: filter + in: query + description: >- + JSON string containing an array of filter conditions. When provided, + this takes precedence over query parameter filters (userId, name, + type, level, environment, fromStartTime, ...). + + + ## Filter Structure + + Each filter condition has the following structure: + + ```json + + [ + { + "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null" + "column": string, // Required. Column to filter on (see available columns below) + "operator": string, // Required. Operator based on type: + // - datetime: ">", "<", ">=", "<=" + // - string: "=", "contains", "does not contain", "starts with", "ends with" + // - stringOptions: "any of", "none of" + // - categoryOptions: "any of", "none of" + // - arrayOptions: "any of", "none of", "all of" + // - number: "=", ">", "<", ">=", "<=" + // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set" + // - numberObject: "=", ">", "<", ">=", "<=" + // - boolean: "=", "<>" + // - null: "is null", "is not null" + "value": any, // Required (except for null type). Value to compare against. Type depends on filter type + "key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata + } + ] + + ``` + + + ## Available Columns + + + ### Core Observation Fields + + - `id` (string) - Observation ID + + - `type` (string) - Observation type (SPAN, GENERATION, EVENT) + + - `name` (string) - Observation name + + - `traceId` (string) - Associated trace ID + + - `startTime` (datetime) - Observation start time + + - `endTime` (datetime) - Observation end time + + - `environment` (string) - Environment tag + + - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR) + + - `statusMessage` (string) - Status message + + - `version` (string) - Version tag + + + ### Performance Metrics + + - `latency` (number) - Latency in seconds (calculated: end_time - + start_time) + + - `timeToFirstToken` (number) - Time to first token in seconds + + - `tokensPerSecond` (number) - Output tokens per second + + + ### Token Usage + + - `inputTokens` (number) - Number of input tokens + + - `outputTokens` (number) - Number of output tokens + + - `totalTokens` (number) - Total tokens (alias: `tokens`) + + + ### Cost Metrics + + - `inputCost` (number) - Input cost in USD + + - `outputCost` (number) - Output cost in USD + + - `totalCost` (number) - Total cost in USD + + + ### Model Information + + - `model` (string) - Provided model name + + - `promptName` (string) - Associated prompt name + + - `promptVersion` (number) - Associated prompt version + + + ### Structured Data + + - `metadata` (stringObject/numberObject/categoryOptions) - Metadata + key-value pairs. Use `key` parameter to filter on specific metadata + keys. + + + ### Associated Trace Fields (requires join with traces table) + + - `userId` (string) - User ID from associated trace + + - `traceName` (string) - Name from associated trace + + - `traceEnvironment` (string) - Environment from associated trace + + - `traceTags` (arrayOptions) - Tags from associated trace + + + ## Filter Examples + + ```json + + [ + { + "type": "string", + "column": "type", + "operator": "=", + "value": "GENERATION" + }, + { + "type": "number", + "column": "latency", + "operator": ">=", + "value": 2.5 + }, + { + "type": "stringObject", + "column": "metadata", + "key": "environment", + "operator": "=", + "value": "production" + } + ] + + ``` + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/legacyObservationsViews' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/scores/{scoreId}: + delete: + description: Delete a score (supports both trace and session scores) + operationId: legacy_scoreV1_delete + tags: + - LegacyScoreV1 + parameters: + - name: scoreId + in: path + description: The unique langfuse identifier of a score + required: true + schema: + type: string + responses: + '204': + description: '' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/llm-connections: + get: + description: Get all LLM connections in a project + operationId: llmConnections_list + tags: + - LlmConnections + parameters: + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedLlmConnections' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + put: + description: >- + Create or update an LLM connection. The connection is upserted on + provider. + operationId: llmConnections_upsert + tags: + - LlmConnections + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/LlmConnection' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpsertLlmConnectionRequest' + /api/public/llm-connections/{id}: + delete: + description: >- + Delete an LLM connection by id. Evaluators that depend on the deleted + connection are automatically paused. + operationId: llmConnections_delete + tags: + - LlmConnections + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteLlmConnectionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/media/{mediaId}: + get: + description: Get a media record + operationId: media_get + tags: + - Media + parameters: + - name: mediaId + in: path + description: The unique langfuse identifier of a media record + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GetMediaResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + patch: + description: Patch a media record + operationId: media_patch + tags: + - Media + parameters: + - name: mediaId + in: path + description: The unique langfuse identifier of a media record + required: true + schema: + type: string + responses: + '204': + description: '' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PatchMediaBody' + /api/public/media: + post: + description: Get a presigned upload URL for a media record + operationId: media_getUploadUrl + tags: + - Media + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GetMediaUploadUrlResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/GetMediaUploadUrlRequest' + /api/public/v2/metrics: + get: + description: >- + Get metrics from the Langfuse project using a query object. V2 endpoint + with optimized performance. + + + Together with OpenTelemetry ingestion and Observations API v2, this is + the only real-time read path. Other public API endpoints can delay data + by about 10 minutes. + + + ## V2 Differences + + - Supports `observations`, `scores-numeric`, `scores-boolean`, and + `scores-categorical` views only (traces view not supported) + + - Direct access to tags and release fields on observations + + - Semantic-root filtering and grouping through the v2-only + `isRootObservation` dimension + + - Backwards-compatible: traceName, traceRelease, traceVersion dimensions + are still available on observations view + + - High cardinality dimensions are not supported and will return a 400 + error (see below) + + + For more details, see the [Metrics API + documentation](https://langfuse.com/docs/metrics/features/metrics-api). + + + ## Available Views + + + ### observations + + Query observation-level data (spans, generations, events). + + + **Dimensions:** + + - `environment` - Deployment environment (e.g., production, staging) + + - `type` - Type of observation (SPAN, GENERATION, EVENT) + + - `name` - Name of the observation + + - `level` - Logging level of the observation + + - `version` - Version of the observation + + - `tags` - User-defined tags + + - `release` - Release version + + - `traceName` - Name of the parent trace (backwards-compatible) + + - `traceRelease` - Release version of the parent trace + (backwards-compatible, maps to release) + + - `traceVersion` - Version of the parent trace (backwards-compatible, + maps to version) + + - `providedModelName` - Name of the model used + + - `promptName` - Name of the prompt used + + - `promptVersion` - Version of the prompt used + + - `isRootObservation` - Boolean semantic-root status. `true` includes + physical roots and app roots whose SDK parent is external (so + `parentObservationId` may be non-null). + + - `startTimeMonth` - Month of start_time in YYYY-MM format + + + **Measures:** + + - `count` - Total number of observations + + - `latency` - Observation latency (milliseconds) + + - `streamingLatency` - Generation latency from completion start to end + (milliseconds) + + - `inputTokens` - Sum of input tokens consumed + + - `outputTokens` - Sum of output tokens produced + + - `totalTokens` - Sum of all tokens consumed + + - `outputTokensPerSecond` - Output tokens per second + + - `tokensPerSecond` - Total tokens per second + + - `inputCost` - Input cost (USD) + + - `outputCost` - Output cost (USD) + + - `totalCost` - Total cost (USD) + + - `timeToFirstToken` - Time to first token (milliseconds) + + - `countScores` - Number of scores attached to the observation + + + ### scores-numeric + + Query numeric and boolean score data. + + + **Dimensions:** + + - `environment` - Deployment environment + + - `name` - Name of the score (e.g., accuracy, toxicity) + + - `source` - Origin of the score (API, ANNOTATION, EVAL) + + - `dataType` - Data type (NUMERIC, BOOLEAN) + + - `configId` - Identifier of the score config + + - `timestampMonth` - Month in YYYY-MM format + + - `timestampDay` - Day in YYYY-MM-DD format + + - `value` - Numeric value of the score + + - `traceName` - Name of the parent trace + + - `tags` - Tags + + - `traceRelease` - Release version + + - `traceVersion` - Version + + - `observationName` - Name of the associated observation + + - `observationModelName` - Model name of the associated observation + + - `observationPromptName` - Prompt name of the associated observation + + - `observationPromptVersion` - Prompt version of the associated + observation + + + **Measures:** + + - `count` - Total number of scores + + - `value` - Score value (for aggregations) + + + ### scores-boolean + + Query boolean score data. It has the same score and parent + trace/observation dimensions as scores-numeric, plus: + + + **Dimensions:** + + - `booleanValue` - Boolean value for true/false grouping and filtering + + + **Measures:** + + - `count` - Total number of boolean scores + + - `value` - Numeric 0/1 score value; `avg` returns the true-rate + + + ### scores-categorical + + Query categorical score data. Same dimensions as scores-numeric except + uses `stringValue` instead of `value`. + + + **Measures:** + + - `count` - Total number of scores + + + ## High Cardinality Dimensions + + The following dimensions cannot be used as grouping dimensions in v2 + metrics API as they can cause performance issues. + + Use them in filters instead. + + + **observations view:** + + - `id` - Use traceId filter to narrow down results + + - `traceId` - Use traceId filter instead + + - `userId` - Use userId filter instead + + - `sessionId` - Use sessionId filter instead + + - `parentObservationId` - Use parentObservationId filter instead + + + **scores-numeric / scores-boolean / scores-categorical views:** + + - `id` - Use specific filters to narrow down results + + - `traceId` - Use traceId filter instead + + - `userId` - Use userId filter instead + + - `sessionId` - Use sessionId filter instead + + - `observationId` - Use observationId filter instead + + + ## Aggregations + + Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`, + `p50`, `p75`, `p90`, `p95`, `p99`, `histogram` + + + ## Time Granularities + + Available granularities for timeDimension: `auto`, `minute`, `hour`, + `day`, `week`, `month` + + - `auto` bins the data into approximately 50 buckets based on the time + range + operationId: metrics_metrics + tags: + - Metrics + parameters: + - name: query + in: query + description: >- + JSON string containing the query parameters with the following + structure: + + ```json + + { + "view": string, // Required. One of "observations", "scores-numeric", "scores-boolean", "scores-categorical" + "dimensions": [ // Optional. Default: [] + { + "field": string // Field to group by (see available dimensions above) + } + ], + "metrics": [ // Required. At least one metric must be provided + { + "measure": string, // What to measure (see available measures above) + "aggregation": string // How to aggregate: "sum", "avg", "count", "max", "min", "p50", "p75", "p90", "p95", "p99", "histogram" + } + ], + "filters": [ // Optional. Default: [] + { + "column": string, // Column to filter on (any dimension field) + "operator": string, // Operator based on type: + // - datetime: ">", "<", ">=", "<=" + // - string: "=", "contains", "does not contain", "starts with", "ends with" + // - stringOptions: "any of", "none of" + // - arrayOptions: "any of", "none of", "all of" + // - number: "=", ">", "<", ">=", "<=" + // - stringObject/numberObject: same as string/number with required "key" + // - boolean: "=", "<>" + // - null: "is null", "is not null" + "value": any, // Value to compare against + "type": string, // Data type: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null" + "key": string // Required only for stringObject/numberObject types (e.g., metadata filtering) + } + ], + "timeDimension": { // Optional. Default: null. If provided, results will be grouped by time + "granularity": string // One of "auto", "minute", "hour", "day", "week", "month" + }, + "fromTimestamp": string, // Required. ISO datetime string for start of time range + "toTimestamp": string, // Required. ISO datetime string for end of time range (must be after fromTimestamp) + "orderBy": [ // Optional. Default: null + { + "field": string, // Field to order by (dimension or metric alias) + "direction": string // "asc" or "desc" + } + ], + "config": { // Optional. Query-specific configuration + "bins": number, // Optional. Number of bins for histogram aggregation (1-100), default: 10 + "row_limit": number // Optional. Maximum number of rows to return (1-1000), default: 100 + } + } + + ``` + + + For example, to count semantic roots (including app roots with a + non-null external parent), use a boolean filter: + + ```json + + { + "view": "observations", + "metrics": [{"measure": "count", "aggregation": "count"}], + "filters": [{"column": "isRootObservation", "operator": "=", "value": true, "type": "boolean"}], + "fromTimestamp": "2025-01-01T00:00:00.000Z", + "toTimestamp": "2025-02-01T00:00:00.000Z" + } + + ``` + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MetricsV2Response' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/models: + post: + description: Create a model + operationId: models_create + tags: + - Models + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Model' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateModelRequest' + get: + description: Get all models + operationId: models_list + tags: + - Models + parameters: + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedModels' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/models/{id}: + put: + description: >- + Create or replace a project-owned model using its id. Built-in models + cannot be modified. + operationId: models_upsert + tags: + - Models + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Model' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateModelRequest' + get: + description: Get a model + operationId: models_get + tags: + - Models + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Model' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + delete: + description: >- + Delete a model. Cannot delete models managed by Langfuse. You can create + your own definition with the same modelName to override the definition + though. + operationId: models_delete + tags: + - Models + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '204': + description: '' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/v2/observations: + get: + description: >- + Get a list of observations with cursor-based pagination and flexible + field selection. + + + Together with OpenTelemetry ingestion and Metrics API v2, this is the + only real-time read path. Other public API endpoints can delay data by + about 10 minutes. + + + ## Cursor-based Pagination + + This endpoint uses cursor-based pagination for efficient traversal of + large datasets. + + The cursor is returned in the response metadata and should be passed in + subsequent requests + + to retrieve the next page of results. + + + ## Field Selection + + Use the `fields` parameter to control which observation fields are + returned: + + - `core` - Always included: id, traceId, startTime, endTime, projectId, + parentObservationId, type + + - `basic` - name, level, statusMessage, version, environment, + bookmarked, public, userId, sessionId, isRootObservation + + - `time` - completionStartTime, createdAt, updatedAt + + - `io` - input, output + + - `metadata` - metadata (truncated to 200 chars by default, use + `expandMetadata` to get full values) + + - `model` - model, internalModelId, modelParameters + + - `usage` - usageDetails, costDetails, totalCost, usagePricingTierName + + - `prompt` - promptId, promptName, promptVersion + + - `metrics` - latency, timeToFirstToken + + - `trace_context` - tags, release, traceName + + + If not specified, `core` and `basic` field groups are returned. + + + ## Filters + + Multiple filtering options are available via query parameters or the + structured `filter` parameter. + + When using the `filter` parameter, it takes precedence over individual + query parameter filters. + operationId: observations_getMany + tags: + - Observations + parameters: + - name: fields + in: query + description: >- + Comma-separated list of field groups to include in the response. + + Available groups: core, basic, time, io, metadata, model, usage, + prompt, metrics, trace_context. + + If not specified, `core` and `basic` field groups are returned. + + Example: "basic,usage,model" + required: false + schema: + type: string + nullable: true + - name: expandMetadata + in: query + description: |- + Comma-separated list of metadata keys to return non-truncated. + By default, metadata values over 200 characters are truncated. + Use this parameter to retrieve full values for specific keys. + Example: "key1,key2" + required: false + schema: + type: string + nullable: true + - name: limit + in: query + description: Number of items to return per page. Maximum 1000, default 50. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: >- + Base64-encoded cursor for pagination. Use the cursor from the + previous response to get the next page. + required: false + schema: + type: string + nullable: true + - name: parseIoAsJson + in: query + description: |- + **Deprecated.** Setting this to `true` will return a 400 error. + Input/output fields are always returned as raw strings. + Remove this parameter or set it to `false`. + required: false + schema: + type: boolean + nullable: true + - name: name + in: query + required: false + schema: + type: string + nullable: true + - name: userId + in: query + required: false + schema: + type: string + nullable: true + - name: sessionId + in: query + description: Filter by session ID. + required: false + schema: + type: string + nullable: true + - name: type + in: query + description: >- + Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", + "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", + "GUARDRAIL") + required: false + schema: + type: string + nullable: true + - name: traceId + in: query + required: false + schema: + type: string + nullable: true + - name: level + in: query + description: >- + Optional filter for observations with a specific level (e.g. + "DEBUG", "DEFAULT", "WARNING", "ERROR"). + required: false + schema: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + - name: parentObservationId + in: query + description: >- + Filter by the physical parent observation ID. + + An empty value matches only observations without a physical parent. + Use `isRootObservation` to include observations marked as app roots + by the SDK, which may retain a non-null `parentObservationId`. + required: false + schema: + type: string + nullable: true + - name: isRootObservation + in: query + description: >- + Filter by whether an observation is a logical root. + + Root observations include observations without a physical parent and + observations marked as app roots by the SDK. + + An app-root observation may have `isRootObservation=true` and a + non-null `parentObservationId`. + required: false + schema: + type: boolean + nullable: true + - name: environment + in: query + description: >- + Optional filter for observations where the environment is one of the + provided values. + required: false + schema: + type: array + items: + type: string + nullable: true + - name: fromStartTime + in: query + description: >- + Retrieve only observations with a start_time on or after this + datetime (ISO 8601). + required: false + schema: + type: string + format: date-time + nullable: true + - name: toStartTime + in: query + description: >- + Retrieve only observations with a start_time before this datetime + (ISO 8601). + required: false + schema: + type: string + format: date-time + nullable: true + - name: version + in: query + description: Optional filter to only include observations with a certain version. + required: false + schema: + type: string + nullable: true + - name: filter + in: query + description: >- + JSON string containing an array of filter conditions. When provided, + this takes precedence over query parameter filters (userId, name, + type, level, environment, fromStartTime, ...). + + + ## Filter Structure + + Each filter condition has the following structure: + + ```json + + [ + { + "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null" + "column": string, // Required. Column to filter on (see available columns below) + "operator": string, // Required. Operator based on type: + // - datetime: ">", "<", ">=", "<=" + // - string: "=", "contains", "does not contain", "starts with", "ends with", "matches" + // - stringOptions: "any of", "none of" + // - categoryOptions: "any of", "none of" + // - arrayOptions: "any of", "none of", "all of" + // - number: "=", ">", "<", ">=", "<=" + // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set" + // - numberObject: "=", ">", "<", ">=", "<=" + // - boolean: "=", "<>" + // - null: "is null", "is not null" + "value": any, // Required (except for null type). Value to compare against. Type depends on filter type + "key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata + } + ] + + ``` + + + ## Available Columns + + + ### Core Observation Fields + + - `id` (string) - Observation ID + + - `type` (string) - Observation type (SPAN, GENERATION, EVENT) + + - `name` (string) - Observation name + + - `traceId` (string) - Associated trace ID + + - `startTime` (datetime) - Observation start time + + - `endTime` (datetime) - Observation end time + + - `environment` (string) - Environment tag + + - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR) + + - `statusMessage` (string) - Status message + + - `version` (string) - Version tag + + - `userId` (string) - User ID + + - `sessionId` (string) - Session ID + + - `isRootObservation` (boolean) - Whether the observation is a + logical root. Observations marked as app roots by the SDK may retain + a non-null parentObservationId. + + + ### Trace-Related Fields + + - `traceName` (string) - Name of the parent trace + + - `traceTags` (arrayOptions) - Tags from the parent trace + + - `tags` (arrayOptions) - Alias for traceTags + + + ### Performance Metrics + + - `latency` (number) - Latency in seconds (calculated: end_time - + start_time) + + - `timeToFirstToken` (number) - Time to first token in seconds + + - `tokensPerSecond` (number) - Output tokens per second + + + ### Token Usage + + - `inputTokens` (number) - Number of input tokens + + - `outputTokens` (number) - Number of output tokens + + - `totalTokens` (number) - Total tokens (alias: `tokens`) + + + ### Cost Metrics + + - `inputCost` (number) - Input cost in USD + + - `outputCost` (number) - Output cost in USD + + - `totalCost` (number) - Total cost in USD + + + ### Model Information + + - `model` (string) - Provided model name (alias: + `providedModelName`) + + - `promptName` (string) - Associated prompt name + + - `promptVersion` (number) - Associated prompt version + + + ### Structured Data + + - `input` (string) - Observation input. Supports accelerated indexed + literal search with the `matches` operator. + + - `output` (string) - Observation output. Supports accelerated + indexed literal search with the `matches` operator. + + - `metadata` (stringObject/numberObject/categoryOptions) - Metadata + key-value pairs. Use `key` parameter to filter on specific metadata + keys. + + + The `matches` operator is only supported for `input`, `output`, and + stringObject `metadata` filters. It performs indexed literal search + with token-boundary pruning using the events table text indexes. + Case sensitivity differs by target: `input` and `output` matches are + case-insensitive, while metadata value matches are case-sensitive. + Unlike SQL `LIKE`, `%` and `_` are treated as literal characters. + Use `contains` for legacy substring semantics where the API allows + it. Any v2 `input` or `output` filter must be accompanied by at + least one `=` or `matches` filter on `input` or `output`; standalone + `contains`, `starts with`, `ends with`, and `does not contain` + filters on these columns are rejected. + + + ## Filter Examples + + ```json + + [ + { + "type": "string", + "column": "type", + "operator": "=", + "value": "GENERATION" + }, + { + "type": "number", + "column": "latency", + "operator": ">=", + "value": 2.5 + }, + { + "type": "stringObject", + "column": "metadata", + "key": "environment", + "operator": "=", + "value": "production" + }, + { + "type": "string", + "column": "output", + "operator": "matches", + "value": "needle" + }, + { + "type": "boolean", + "column": "isRootObservation", + "operator": "=", + "value": true + } + ] + + ``` + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ObservationsV2Response' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/otel/v1/traces: + post: + description: >- + **OpenTelemetry Traces Ingestion Endpoint** + + + This endpoint implements the OTLP/HTTP specification for trace + ingestion, providing native OpenTelemetry integration for Langfuse + Observability. + + + Together with Observations API v2 and Metrics API v2, this is the only + real-time write path. Other public API endpoints can delay data by about + 10 minutes. Direct exporters must send `x-langfuse-ingestion-version: + 4`; current Python and JS SDKs already do. + + + **Supported Formats:** + + - Binary Protobuf: `Content-Type: application/x-protobuf` + + - JSON Protobuf: `Content-Type: application/json` + + - Supports gzip compression via `Content-Encoding: gzip` header + + + **Specification Compliance:** + + - Conforms to [OTLP/HTTP Trace + Export](https://opentelemetry.io/docs/specs/otlp/#otlphttp) + + - Implements `ExportTraceServiceRequest` message format + + + **Documentation:** + + - Integration guide: + https://langfuse.com/integrations/native/opentelemetry + + - Data model: https://langfuse.com/docs/observability/data-model + operationId: opentelemetry_exportTraces + tags: + - Opentelemetry + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/OtelTraceResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + resourceSpans: + type: array + items: + $ref: '#/components/schemas/OtelResourceSpan' + description: >- + Array of resource spans containing trace data as defined in + the OTLP specification + required: + - resourceSpans + /api/public/organizations/memberships: + get: + description: >- + Get all memberships for the organization associated with the API key + (requires organization-scoped API key) + operationId: organizations_getOrganizationMemberships + tags: + - Organizations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + put: + description: >- + Create or update a membership for the organization associated with the + API key (requires organization-scoped API key) + operationId: organizations_updateOrganizationMembership + tags: + - Organizations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipRequest' + delete: + description: >- + Delete a membership from the organization associated with the API key + (requires organization-scoped API key) + operationId: organizations_deleteOrganizationMembership + tags: + - Organizations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipDeletionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteMembershipRequest' + /api/public/projects/{projectId}/memberships: + get: + description: >- + Get all memberships for a specific project (requires organization-scoped + API key) + operationId: organizations_getProjectMemberships + tags: + - Organizations + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + put: + description: >- + Create or update a membership for a specific project (requires + organization-scoped API key). The user must already be a member of the + organization. + operationId: organizations_updateProjectMembership + tags: + - Organizations + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipRequest' + delete: + description: >- + Delete a membership from a specific project (requires + organization-scoped API key). The user must be a member of the + organization. + operationId: organizations_deleteProjectMembership + tags: + - Organizations + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/MembershipDeletionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteMembershipRequest' + /api/public/organizations/projects: + get: + description: >- + Get all projects for the organization associated with the API key + (requires organization-scoped API key) + operationId: organizations_getOrganizationProjects + tags: + - Organizations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationProjectsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/organizations/apiKeys: + get: + description: >- + Get all API keys for the organization associated with the API key + (requires organization-scoped API key) + operationId: organizations_getOrganizationApiKeys + tags: + - Organizations + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationApiKeysResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/projects: + get: + description: >- + Get Project associated with API key (requires project-scoped API key). + You can use GET /api/public/organizations/projects to get all projects + with an organization-scoped key. + operationId: projects_get + tags: + - Projects + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Projects' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: Create a new project (requires organization-scoped API key) + operationId: projects_create + tags: + - Projects + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + metadata: + type: object + additionalProperties: true + nullable: true + description: Optional metadata for the project + retention: + type: integer + description: >- + Number of days to retain data. Must be 0 or at least 3 days. + Requires data-retention entitlement for non-zero values. + Optional. + required: + - name + - retention + /api/public/projects/{projectId}: + put: + description: Update a project by ID (requires organization-scoped API key). + operationId: projects_update + tags: + - Projects + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Project' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + name: + type: string + metadata: + type: object + additionalProperties: true + nullable: true + description: Optional metadata for the project + retention: + type: integer + nullable: true + description: |- + Number of days to retain data. + Must be 0 or at least 3 days. + Requires data-retention entitlement for non-zero values. + Optional. Will retain existing retention setting if omitted. + required: + - name + delete: + description: >- + Delete a project by ID (requires organization-scoped API key). Project + deletion is processed asynchronously. + operationId: projects_delete + tags: + - Projects + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '202': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ProjectDeletionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/projects/{projectId}/apiKeys: + get: + description: Get all API keys for a project (requires organization-scoped API key) + operationId: projects_getApiKeys + tags: + - Projects + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyList' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: >- + Create a new API key for a project (requires organization-scoped API key) + operationId: projects_createApiKey + tags: + - Projects + parameters: + - name: projectId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + note: + type: string + nullable: true + description: Optional note for the API key + publicKey: + type: string + nullable: true + description: >- + Optional predefined public key. Must start with 'pk-lf-'. If + provided, secretKey must also be provided. + secretKey: + type: string + nullable: true + description: >- + Optional predefined secret key. Must start with 'sk-lf-'. If + provided, publicKey must also be provided. + /api/public/projects/{projectId}/apiKeys/{apiKeyId}: + delete: + description: Delete an API key for a project (requires organization-scoped API key) + operationId: projects_deleteApiKey + tags: + - Projects + parameters: + - name: projectId + in: path + required: true + schema: + type: string + - name: apiKeyId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ApiKeyDeletionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/v2/prompts/{name}/versions/{version}: + patch: + description: Update labels for a specific prompt version + operationId: promptVersion_update + tags: + - PromptVersion + parameters: + - name: name + in: path + description: >- + The name of the prompt. If the prompt is in a folder (e.g., + "folder/subfolder/prompt-name"), + + the folder path must be URL encoded. + required: true + schema: + type: string + - name: version + in: path + description: Version of the prompt to update + required: true + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Prompt' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + newLabels: + type: array + items: + type: string + description: >- + New labels for the prompt version. Labels are unique across + versions. The "latest" label is reserved and managed by + Langfuse. + required: + - newLabels + /api/public/v2/prompts/{promptName}: + get: + description: Get a prompt + operationId: prompts_get + tags: + - Prompts + parameters: + - name: promptName + in: path + description: >- + The name of the prompt. If the prompt is in a folder (e.g., + "folder/subfolder/prompt-name"), + + the folder path must be URL encoded. + required: true + schema: + type: string + - name: version + in: query + description: Version of the prompt to be retrieved. + required: false + schema: + type: integer + nullable: true + - name: label + in: query + description: >- + Label of the prompt to be retrieved. Defaults to "production" if no + label or version is set. + required: false + schema: + type: string + nullable: true + - name: resolve + in: query + description: >- + Resolve prompt dependencies before returning the prompt. Defaults to + `true`. Set to `false` to return the raw stored prompt with + dependency tags intact. This bypasses prompt caching and is intended + for debugging or one-off jobs, not production runtime fetches. + required: false + schema: + type: boolean + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Prompt' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + delete: + description: >- + Delete prompt versions. If neither version nor label is specified, all + versions of the prompt are deleted. + operationId: prompts_delete + tags: + - Prompts + parameters: + - name: promptName + in: path + description: The name of the prompt + required: true + schema: + type: string + - name: label + in: query + description: >- + Optional label to filter deletion. If specified, deletes all prompt + versions that have this label. + required: false + schema: + type: string + nullable: true + - name: version + in: query + description: >- + Optional version to filter deletion. If specified, deletes only this + specific version of the prompt. + required: false + schema: + type: integer + nullable: true + responses: + '204': + description: '' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/v2/prompts: + get: + description: Get a list of prompt names with versions and labels + operationId: prompts_list + tags: + - Prompts + parameters: + - name: name + in: query + required: false + schema: + type: string + nullable: true + - name: label + in: query + required: false + schema: + type: string + nullable: true + - name: tag + in: query + required: false + schema: + type: string + nullable: true + - name: page + in: query + description: page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: limit of items per page + required: false + schema: + type: integer + nullable: true + - name: fromUpdatedAt + in: query + description: >- + Optional filter to only include prompt versions created/updated on + or after a certain datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: toUpdatedAt + in: query + description: >- + Optional filter to only include prompt versions created/updated + before a certain datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: filter + in: query + description: >- + JSON string containing an array of filter conditions, combined with + AND. + + When provided, this takes precedence over name, version, + + label, tag, fromUpdatedAt, and toUpdatedAt. An empty array applies + no + + filters. Project scoping and pagination always apply. + + + Each condition requires `type`, `column`, `operator`, and `value`. + + Supported types and columns: + + - `string`: `id`, `name`, `type`. Operators: `=`, `contains`, `does + not contain`, `starts with`, `ends with`, `is not empty`. + + - `stringOptions`: `id`, `name`, `type`. Operators: `any of`, `none + of`. Value: non-empty string array. + + - `number`: `version`. Operators: `=`, `>`, `<`, `>=`, `<=`. Value: + number. + + - `datetime`: `createdAt`, `updatedAt`. Operators: `>`, `<`, `>=`, + `<=`. Value: ISO 8601 timestamp. + + - `arrayOptions`: `labels`, `tags`. Operators: `any of`, `all of`, + `none of`. Value: non-empty string array. + + - `stringObject`: `config`. Requires an additional `key` field. + Operators: `=`, `contains`, `does not contain`, `starts with`, `ends + with`, `is set`, `is not set`. Value: string (use an empty string + for key-presence operators). + + + String equality is case-sensitive. String search operators use + + case-insensitive SQL pattern matching: `%` matches any sequence and + + `_` matches a single character. A backslash escapes these + characters; + + JSON-escape the backslash in the filter value. Asterisks are + literal. + + For config, an empty search value is treated as `is set`. + + + Filters apply to prompt versions before aggregation: returned + versions, + + labels, and lastConfig reflect only matching versions. + + + Example: [{"type":"string","column":"name","operator":"starts + with","value":"tools/"},{"type":"string","column":"name","operator":"ends + with","value":"/description"}] + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PromptMetaListResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: Create a new version for the prompt with the given `name` + operationId: prompts_create + tags: + - Prompts + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Prompt' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreatePromptRequest' + /api/public/scim/ServiceProviderConfig: + get: + description: >- + Get SCIM Service Provider Configuration (requires organization-scoped + API key) + operationId: scim_getServiceProviderConfig + tags: + - Scim + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceProviderConfig' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/scim/ResourceTypes: + get: + description: Get SCIM Resource Types (requires organization-scoped API key) + operationId: scim_getResourceTypes + tags: + - Scim + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ResourceTypesResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/scim/Schemas: + get: + description: Get SCIM Schemas (requires organization-scoped API key) + operationId: scim_getSchemas + tags: + - Scim + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/SchemasResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/scim/Users: + get: + description: List users in the organization (requires organization-scoped API key) + operationId: scim_listUsers + tags: + - Scim + parameters: + - name: filter + in: query + description: Filter expression (e.g. userName eq "value") + required: false + schema: + type: string + nullable: true + - name: startIndex + in: query + description: 1-based index of the first result to return (default 1) + required: false + schema: + type: integer + nullable: true + - name: count + in: query + description: Maximum number of results to return (default 100) + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScimUsersListResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: >- + Create a new user in the organization (requires organization-scoped API + key) + operationId: scim_createUser + tags: + - Scim + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScimUser' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + userName: + type: string + description: User's email address (required) + name: + $ref: '#/components/schemas/ScimName' + description: User's name information + emails: + type: array + items: + $ref: '#/components/schemas/ScimEmail' + nullable: true + description: User's email addresses + active: + type: boolean + nullable: true + description: Whether the user is active + password: + type: string + nullable: true + description: >- + Ignored. Accepted only for compatibility with identity + providers that always send a password on user creation (Okta + sends a placeholder value even when password sync is + disabled). No credential is created for the user; + provisioned users authenticate via SSO or set a password + themselves through the password reset flow. + required: + - userName + - name + /api/public/scim/Users/{userId}: + get: + description: Get a specific user by ID (requires organization-scoped API key) + operationId: scim_getUser + tags: + - Scim + parameters: + - name: userId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScimUser' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + delete: + description: >- + Remove a user from the organization (requires organization-scoped API + key). Note that this only removes the user from the organization but + does not delete the user entity itself. + operationId: scim_deleteUser + tags: + - Scim + parameters: + - name: userId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/EmptyResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/score-configs: + post: + description: >- + Create a score configuration (config). Score configs are used to define + the structure of scores + operationId: scoreConfigs_create + tags: + - ScoreConfigs + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScoreConfig' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScoreConfigRequest' + get: + description: Get all score configs + operationId: scoreConfigs_get + tags: + - ScoreConfigs + parameters: + - name: page + in: query + description: Page number, starts at 1. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. If you encounter api issues due to too + large page sizes, try to reduce the limit + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScoreConfigs' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/score-configs/{configId}: + get: + description: Get a score config + operationId: scoreConfigs_get-by-id + tags: + - ScoreConfigs + parameters: + - name: configId + in: path + description: The unique langfuse identifier of a score config + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScoreConfig' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + patch: + description: Update a score config + operationId: scoreConfigs_update + tags: + - ScoreConfigs + parameters: + - name: configId + in: path + description: The unique langfuse identifier of a score config + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/ScoreConfig' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateScoreConfigRequest' + /api/public/v3/scores: + get: + description: |- + Get a list of scores with a polymorphic `value` field (v3). + + The `value` field type depends on `dataType`: + - `NUMERIC` → number + - `BOOLEAN` → boolean + - `CATEGORICAL`, `TEXT`, `CORRECTION` → string + + The response always includes the core fields: id, projectId, name, + value, dataType, source, timestamp, environment, createdAt, updatedAt. + + Additional field groups can be requested via the `fields` parameter: + - `details` — adds comment, configId, metadata + - `subject` — adds the subject object describing the entity the score + is attached to: kind (trace, observation, session, or experiment), + id, and traceId for observation-level scores + - `annotation` — adds authorUserId, queueId + + Unknown group names return HTTP 400. + operationId: scoresV3_getManyV3 + tags: + - ScoresV3 + parameters: + - name: limit + in: query + description: >- + Number of items per page. Maximum 100, default 50. Requests with a + limit greater than 100 return HTTP 400. + required: false + schema: + type: integer + nullable: true + - name: cursor + in: query + description: >- + URL-safe base64 (base64url) cursor for pagination. Use the cursor + from the previous response to get the next page. Absent on the final + page. + required: false + schema: + type: string + nullable: true + - name: fields + in: query + description: >- + Comma-separated field groups to include in addition to the + always-returned core fields. Allowed: details, subject, annotation — + see the endpoint description for the fields each group adds. Unknown + names return HTTP 400. + required: false + schema: + type: string + nullable: true + - name: id + in: query + description: >- + Comma-separated list of score IDs to filter by (OR within, AND + across filters). + required: false + schema: + type: string + nullable: true + - name: name + in: query + description: Comma-separated list of score names to filter by. + required: false + schema: + type: string + nullable: true + - name: source + in: query + description: >- + Comma-separated list of score sources to filter by (e.g. API, + ANNOTATION, EVAL). Case-insensitive — `api` and `API` are + equivalent. + required: false + schema: + type: string + nullable: true + - name: dataType + in: query + description: >- + Comma-separated list of data types to filter by (NUMERIC, BOOLEAN, + CATEGORICAL, TEXT, CORRECTION). Case-insensitive — `numeric` and + `NUMERIC` are equivalent. Must be a single value when used with + value, valueMin, or valueMax; otherwise the request returns HTTP + 400. Must be NUMERIC when used with valueMin or valueMax. + required: false + schema: + type: string + nullable: true + - name: environment + in: query + description: Comma-separated list of environments to filter by. + required: false + schema: + type: string + nullable: true + - name: configId + in: query + description: Comma-separated list of score config IDs to filter by. + required: false + schema: + type: string + nullable: true + - name: queueId + in: query + description: Comma-separated list of annotation queue IDs to filter by. + required: false + schema: + type: string + nullable: true + - name: authorUserId + in: query + description: Comma-separated list of author user IDs to filter by. + required: false + schema: + type: string + nullable: true + - name: value + in: query + description: >- + Comma-separated list of exact values to filter by. Requires a single + dataType from NUMERIC, BOOLEAN, or CATEGORICAL; any other dataType, + multiple dataTypes, or omitting dataType returns HTTP 400. For + BOOLEAN, each value must be "true" or "false"; for NUMERIC, each + value must be a finite number. Otherwise the request returns HTTP + 400. + required: false + schema: + type: string + nullable: true + - name: valueMin + in: query + description: >- + Inclusive lower bound on the numeric value. Requires + dataType=NUMERIC as a single value; otherwise the request returns + HTTP 400. + required: false + schema: + type: number + format: double + nullable: true + - name: valueMax + in: query + description: >- + Inclusive upper bound on the numeric value. Requires + dataType=NUMERIC as a single value; otherwise the request returns + HTTP 400. + required: false + schema: + type: number + format: double + nullable: true + - name: traceId + in: query + description: >- + Comma-separated list of trace IDs to filter by. Mutually exclusive + with sessionId, experimentId. May be combined with observationId to + scope the observation lookup to a specific trace. + required: false + schema: + type: string + nullable: true + - name: sessionId + in: query + description: >- + Comma-separated list of session IDs to filter by. Mutually exclusive + with traceId, observationId, experimentId. + required: false + schema: + type: string + nullable: true + - name: observationId + in: query + description: >- + Comma-separated list of observation IDs to filter by. Requires + traceId to be specified, because observation IDs are scoped to a + trace. Mutually exclusive with sessionId, experimentId. Returns HTTP + 400 when used without traceId. + required: false + schema: + type: string + nullable: true + - name: experimentId + in: query + description: >- + Comma-separated list of dataset run IDs (experiment IDs) to filter + by. Mutually exclusive with traceId, sessionId, observationId. + required: false + schema: + type: string + nullable: true + - name: fromTimestamp + in: query + description: Inclusive lower bound on the score timestamp. + required: false + schema: + type: string + format: date-time + nullable: true + - name: toTimestamp + in: query + description: Exclusive upper bound on the score timestamp. + required: false + schema: + type: string + format: date-time + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GetScoresV3Response' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/scores: + post: + description: >- + Create a score (supports trace, observation, session, and dataset run + scores) + operationId: scores_create + tags: + - Scores + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScoreResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScoreRequest' + /api/public/v2/scores: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. Use `GET + /api/public/v3/scores` instead. Self-hosted deployments are unaffected + by this date; the endpoint becomes unavailable when they upgrade to + Langfuse v4. See the [Langfuse v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a list of scores (supports both trace and session scores) + operationId: scores_get-many + tags: + - Scores + parameters: + - name: page + in: query + description: Page number, starts at 1. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. Maximum 100. Defaults to 50. Requests with + a limit greater than 100 return HTTP 400. If you encounter api + issues due to too large page sizes, try to reduce the limit. + required: false + schema: + type: integer + nullable: true + - name: userId + in: query + description: Retrieve only scores with this userId associated to the trace. + required: false + schema: + type: string + nullable: true + - name: name + in: query + description: Retrieve only scores with this name. + required: false + schema: + type: string + nullable: true + - name: fromTimestamp + in: query + description: >- + Optional filter to only include scores created on or after a certain + datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: toTimestamp + in: query + description: >- + Optional filter to only include scores created before a certain + datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: environment + in: query + description: >- + Optional filter for scores where the environment is one of the + provided values. + required: false + schema: + type: array + items: + type: string + nullable: true + - name: source + in: query + description: Retrieve only scores from a specific source. + required: false + schema: + $ref: '#/components/schemas/ScoreSource' + nullable: true + - name: operator + in: query + description: Retrieve only scores with 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, is set, is not set. Use is set / is not set to + filter on metadata key presence. An empty value for contains, starts + with, or ends with is treated as is set (key presence). + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/GetScoresResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/v2/scores/{scoreId}: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. Use `GET + /api/public/v3/scores` with the `id` filter instead. Self-hosted + deployments are unaffected by this date; the endpoint becomes + unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4 + upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a score (supports both trace and session scores) + operationId: scores_get-by-id + tags: + - Scores + parameters: + - name: scoreId + in: path + description: The unique langfuse identifier of a score + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Score' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/sessions: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, read + session data via `GET /api/public/v2/observations?filter=&fromStartTime=&toStartTime=`. Self-hosted + deployments are unaffected by this date; the endpoint becomes + unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4 + upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get sessions. + + + This legacy endpoint is not recommended for new data extraction + workflows. + + Use the v2 observations endpoint with a bounded time range and group + rows by + + `sessionId` instead: + + `GET /api/public/v2/observations?fromStartTime=&toStartTime=`. + operationId: sessions_list + tags: + - Sessions + parameters: + - name: page + in: query + description: Page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. If you encounter api issues due to too + large page sizes, try to reduce the limit. + required: false + schema: + type: integer + nullable: true + - name: fromTimestamp + in: query + description: >- + Optional filter to only include sessions created on or after a + certain datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: toTimestamp + in: query + description: >- + Optional filter to only include sessions created before a certain + datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: environment + in: query + description: >- + Optional filter for sessions where the environment is one of the + provided values. + required: false + schema: + type: array + items: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedSessions' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/sessions/{sessionId}: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, read + session data via `GET /api/public/v2/observations?filter=&fromStartTime=&toStartTime=`. Self-hosted + deployments are unaffected by this date; the endpoint becomes + unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4 + upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a session. + + + Please note that `traces` on this endpoint are not paginated. For large + + sessions or new data extraction workflows, use the v2 observations + endpoint + + with a URL-encoded `sessionId` filter and a bounded time range: + + `GET /api/public/v2/observations?filter=&fromStartTime=&toStartTime=`. + operationId: sessions_get + tags: + - Sessions + parameters: + - name: sessionId + in: path + description: The unique id of a session + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/SessionWithTraces' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + /api/public/traces/{traceId}: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, read span + and trace data via `GET + /api/public/v2/observations?fromStartTime=&toStartTime=`. + Self-hosted deployments are unaffected by this date; the endpoint + becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse + v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get a specific trace + operationId: trace_get + tags: + - Trace + parameters: + - name: traceId + in: path + description: The unique langfuse identifier of a trace + required: true + schema: + type: string + - name: fields + in: query + description: >- + Comma-separated list of fields to include in the response. Available + field groups: 'core' (always included), 'io' (input, output, + metadata), 'scores', 'observations', 'metrics'. If not specified, + all fields are returned. Example: 'core,scores,metrics'. Note: + Excluded 'observations' or 'scores' fields return empty arrays; + excluded 'metrics' returns -1 for 'totalCost' and 'latency'. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/TraceWithFullDetails' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + delete: + description: Delete a specific trace + operationId: trace_delete + tags: + - Trace + parameters: + - name: traceId + in: path + description: The unique langfuse identifier of the trace to delete + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteTraceResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/traces: + get: + description: >- + **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this + endpoint will be removed on November 16, 2026. In Langfuse v4, read span + and trace data via `GET + /api/public/v2/observations?fromStartTime=&toStartTime=`. + Self-hosted deployments are unaffected by this date; the endpoint + becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse + v3 to v4 upgrade + guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). + + + Get list of traces + operationId: trace_list + tags: + - Trace + parameters: + - name: page + in: query + description: Page number, starts at 1 + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: >- + Limit of items per page. If you encounter api issues due to too + large page sizes, try to reduce the limit. + required: false + schema: + type: integer + nullable: true + - name: userId + in: query + required: false + schema: + type: string + nullable: true + - name: name + in: query + required: false + schema: + type: string + nullable: true + - name: sessionId + in: query + required: false + schema: + type: string + nullable: true + - name: fromTimestamp + in: query + description: >- + Optional filter to only include traces with a trace.timestamp on or + after a certain datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: toTimestamp + in: query + description: >- + Optional filter to only include traces with a trace.timestamp before + a certain datetime (ISO 8601) + required: false + schema: + type: string + format: date-time + nullable: true + - name: orderBy + in: query + description: >- + Format of the string [field].[asc/desc]. Fields: id, timestamp, + name, userId, release, version, public, bookmarked, sessionId. + Example: timestamp.asc + required: false + schema: + type: string + nullable: true + - name: tags + in: query + description: Only traces that include all of these tags will be returned. + required: false + schema: + type: array + items: + type: string + nullable: true + - name: version + in: query + description: Optional filter to only include traces with a certain version. + required: false + schema: + type: string + nullable: true + - name: release + in: query + description: Optional filter to only include traces with a certain release. + required: false + schema: + type: string + nullable: true + - name: environment + in: query + description: >- + Optional filter for traces where the environment is one of the + provided values. + required: false + schema: + type: array + items: + type: string + nullable: true + - name: fields + in: query + description: >- + Comma-separated list of fields to include in the response. Available + field groups: 'core' (always included), 'io' (input, output, + metadata), 'scores', 'observations', 'metrics'. If not specified, + all fields are returned. Example: 'core,scores,metrics'. Note: + Excluded 'observations' or 'scores' fields return empty arrays; + excluded 'metrics' returns -1 for 'totalCost' and 'latency'. + required: false + schema: + type: string + nullable: true + - name: filter + in: query + description: >- + JSON string containing an array of filter conditions. When provided, + this takes precedence over query parameter filters (userId, name, + sessionId, tags, version, release, environment, fromTimestamp, + toTimestamp). + + + ## Filter Structure + + Each filter condition has the following structure: + + ```json + + [ + { + "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "booleanObject", "boolean", "null" + "column": string, // Required. Column to filter on (see available columns below) + "operator": string, // Required. Operator based on type: + // - datetime: ">", "<", ">=", "<=" + // - string: "=", "contains", "does not contain", "starts with", "ends with" + // - stringOptions: "any of", "none of" + // - categoryOptions: "any of", "none of" + // - arrayOptions: "any of", "none of", "all of" + // - number: "=", ">", "<", ">=", "<=" + // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set" + // - numberObject: "=", ">", "<", ">=", "<=" + // - booleanObject: "=", "<>" + // - boolean: "=", "<>" + // - null: "is null", "is not null" + "value": any, // Required (except for null type). Value to compare against. Type depends on filter type + "key": string // Required only for stringObject, numberObject, booleanObject, and categoryOptions types when filtering on nested fields like metadata or score names + } + ] + + ``` + + + ## Available Columns + + + ### Core Trace Fields + + - `id` (string) - Trace ID + + - `name` (string) - Trace name + + - `timestamp` (datetime) - Trace timestamp + + - `userId` (string) - User ID + + - `sessionId` (string) - Session ID + + - `environment` (string) - Environment tag + + - `version` (string) - Version tag + + - `release` (string) - Release tag + + - `tags` (arrayOptions) - Array of tags + + - `bookmarked` (boolean) - Bookmark status + + + ### Structured Data + + - `metadata` (stringObject/numberObject/categoryOptions) - Metadata + key-value pairs. Use `key` parameter to filter on specific metadata + keys. + + + ### Aggregated Metrics (from observations) + + These metrics are aggregated from all observations within the trace: + + - `latency` (number) - Latency in seconds (time from first + observation start to last observation end) + + - `inputTokens` (number) - Total input tokens across all + observations + + - `outputTokens` (number) - Total output tokens across all + observations + + - `totalTokens` (number) - Total tokens (alias: `tokens`) + + - `inputCost` (number) - Total input cost in USD + + - `outputCost` (number) - Total output cost in USD + + - `totalCost` (number) - Total cost in USD + + + ### Observation Level Aggregations + + These fields aggregate observation levels within the trace: + + - `level` (string) - Highest severity level (ERROR > WARNING > + DEFAULT > DEBUG) + + - `warningCount` (number) - Count of WARNING level observations + + - `errorCount` (number) - Count of ERROR level observations + + - `defaultCount` (number) - Count of DEFAULT level observations + + - `debugCount` (number) - Count of DEBUG level observations + + + ### Scores (requires join with scores table) + + - `scores_avg` (number) - Average of numeric scores (alias: + `scores`) + + - `score_categories` (categoryOptions) - Categorical score values + + - `score_booleans` (booleanObject) - Boolean score values. Use `key` + for the score name and a boolean `value`, e.g. `{"type": + "booleanObject", "column": "score_booleans", "key": "is_correct", + "operator": "=", "value": true}`. The `<>` operator also matches + traces without a score of that name. + + + ## Filter Examples + + ```json + + [ + { + "type": "datetime", + "column": "timestamp", + "operator": ">=", + "value": "2024-01-01T00:00:00Z" + }, + { + "type": "string", + "column": "userId", + "operator": "=", + "value": "user-123" + }, + { + "type": "number", + "column": "totalCost", + "operator": ">=", + "value": 0.01 + }, + { + "type": "arrayOptions", + "column": "tags", + "operator": "all of", + "value": ["production", "critical"] + }, + { + "type": "stringObject", + "column": "metadata", + "key": "customer_tier", + "operator": "=", + "value": "enterprise" + } + ] + + ``` + + + ## Performance Notes + + - Filtering on `userId`, `sessionId`, or `metadata` may enable skip + indexes for better query performance + + - Score filters require a join with the scores table and may impact + query performance + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/Traces' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + deprecated: true + delete: + description: Delete multiple traces + operationId: trace_deleteMultiple + tags: + - Trace + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteTraceResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + traceIds: + type: array + items: + type: string + description: List of trace IDs to delete + required: + - traceIds + /api/public/unstable/dashboard-widgets: + get: + description: |- + List dashboard widgets in the project, ordered by most recently + updated first. + + Responses may include legacy `traces` widgets created before this + API existed. New widgets cannot be created with `view: traces`. + operationId: unstable_dashboardWidgets_list + tags: + - UnstableDashboardWidgets + parameters: + - name: page + in: query + description: 1-based page number. Defaults to `1`. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: Maximum number of items per page. Defaults to `50`. + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardWidgetList' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + post: + description: >- + Create a dashboard widget (a standalone chart definition you place on + + any dashboard). + + + This endpoint creates the widget only; place it on a dashboard via + + `POST /dashboards/{dashboardId}/placements`. + + + Supported views are `observations`, `scores-numeric`, `scores-boolean`, + and `scores-categorical`. + + The legacy `traces` view is not supported by this unstable API. + + Widgets are created as v2 internally. + + + `chartConfig` is optional and defaults to the plain config for + + `chartType`; when `chartConfig.type` is given it must match + + `chartType`. + + + Unstable API note: + + - This surface may evolve while dashboard/widget APIs are being + finalized. + operationId: unstable_dashboardWidgets_create + tags: + - UnstableDashboardWidgets + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardWidget' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest' + /api/public/unstable/dashboard-widgets/{widgetId}: + get: + description: |- + Get a dashboard widget by id. + + The response may use `view: traces` for legacy widgets. + operationId: unstable_dashboardWidgets_get + tags: + - UnstableDashboardWidgets + parameters: + - name: widgetId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardWidget' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + patch: + description: |- + Update a dashboard widget. + + All fields are optional; at least one field is required. + Changing `chartType` without sending `chartConfig` resets the config + to the new chart type's defaults. When `chartConfig.type` is given + it must match the widget's (possibly updated) `chartType`. + + `view` cannot be changed to the legacy `traces` value. Existing + `traces` widgets may be updated on other fields. + operationId: unstable_dashboardWidgets_update + tags: + - UnstableDashboardWidgets + parameters: + - name: widgetId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardWidget' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest' + delete: + description: |- + Delete a dashboard widget. + + The API returns `409` while the widget is still placed on a dashboard. + Remove those placements first. + operationId: unstable_dashboardWidgets_delete + tags: + - UnstableDashboardWidgets + parameters: + - name: widgetId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/dashboards: + get: + description: |- + List dashboards in the project, ordered by most recently updated + first. + operationId: unstable_dashboards_list + tags: + - UnstableDashboards + parameters: + - name: page + in: query + description: 1-based page number. Defaults to `1`. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: Maximum number of items per page. Defaults to `50`. + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardList' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + post: + description: Create a dashboard. + operationId: unstable_dashboards_create + tags: + - UnstableDashboards + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboard' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateDashboardRequest' + /api/public/unstable/dashboards/{dashboardId}: + get: + description: Get a dashboard by id. + operationId: unstable_dashboards_get + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboard' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + patch: + description: Update a dashboard's name, description, definition, or filters. + operationId: unstable_dashboards_update + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboard' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateDashboardRequest' + delete: + description: Delete a dashboard. + operationId: unstable_dashboards_delete + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteDashboardResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/dashboards/{dashboardId}/placements: + post: + description: |- + Add a placement to a dashboard grid (see `DashboardPlacement` for + grid semantics). + + `id` and the position fields are optional: when omitted, the + placement gets a server-generated id and is appended below all + existing tiles as a 6x6 tile. Returns the created placement. + + The referenced widget must exist in the same project or be a + Langfuse-managed widget. The API returns `409` if a placement with + the same `id` already exists on the dashboard. + operationId: unstable_dashboards_addPlacement + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardPlacement' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateDashboardPlacementRequest' + /api/public/unstable/dashboards/{dashboardId}/placements/{placementId}: + patch: + description: |- + Move or resize a placement. All fields are optional; at least one is + required. Omitted fields keep their current value. The placement's + content (widget/preset reference) and id cannot change — delete and + re-add the placement to swap content. Returns the updated placement. + operationId: unstable_dashboards_updatePlacement + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + - name: placementId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardPlacement' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest' + delete: + description: >- + Remove a placement from a dashboard grid without deleting the referenced + widget. + operationId: unstable_dashboards_deletePlacement + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + - name: placementId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/skills: + get: + description: >- + List skills with metadata and timestamps from their latest version, + shared tags, and the version assigned to production when present. + operationId: unstable_skills_list + tags: + - UnstableSkills + parameters: + - name: name + in: query + description: Filter by exact skill name. + required: false + schema: + type: string + nullable: true + - name: search + in: query + description: >- + Case-insensitive search across skill names and latest-version + descriptions. + required: false + schema: + type: string + nullable: true + - name: tag + in: query + description: Filter by a shared skill tag. + required: false + schema: + type: string + nullable: true + - name: page + in: query + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + required: false + schema: + type: integer + nullable: true + - name: fromUpdatedAt + in: query + description: >- + Include skills whose latest version was updated at or after this + timestamp. + required: false + schema: + type: string + format: date-time + nullable: true + - name: toUpdatedAt + in: query + description: >- + Include skills whose latest version was updated before this + timestamp. + required: false + schema: + type: string + format: date-time + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillMetaListResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + post: + description: Create skill version + operationId: unstable_skills_createVersion + tags: + - UnstableSkills + parameters: [] + responses: + '201': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillVersion' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateSkillVersionRequest' + /api/public/unstable/skills/{skillName}: + get: + description: >- + Resolve a skill's metadata and file manifest by version or label. + Defaults to the production label. Use each file's sha256Hash with + getFileContents, individually or in batches across manifests. + operationId: unstable_skills_get + tags: + - UnstableSkills + parameters: + - name: skillName + in: path + required: true + schema: + type: string + - name: version + in: query + required: false + schema: + type: integer + nullable: true + - name: label + in: query + required: false + schema: + type: string + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillVersion' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + patch: + description: >- + Replace the shared tags across all versions of a skill. An empty tags + list clears all tags. Returns the latest skill version with the updated + tags. + operationId: unstable_skills_update + tags: + - UnstableSkills + parameters: + - name: skillName + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillVersion' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateSkillRequest' + /api/public/unstable/skills/files/content: + get: + description: >- + Read a batch of text contents by canonical base64-encoded SHA-256 hashes. + operationId: unstable_skills_getFileContents + tags: + - UnstableSkills + parameters: + - name: sha256Hashes + in: query + description: >- + Comma-separated list of one to 50 canonical base64-encoded SHA-256 + hashes from skill file manifests. URL-encode the value, including +, + /, and = characters. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillFileContentsResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + /api/public/unstable/skills/{skillName}/versions/{skillVersion}: + patch: + description: >- + Replace the labels on a skill version and atomically move them from + other versions. + operationId: unstable_skills_setLabels + tags: + - UnstableSkills + parameters: + - name: skillName + in: path + required: true + schema: + type: string + - name: skillVersion + in: path + required: true + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableSkillVersion' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateSkillLabelsRequest' + delete: + description: >- + Delete one immutable skill version. Unreferenced blobs are retained for + asynchronous cleanup. + operationId: unstable_skills_deleteVersion + tags: + - UnstableSkills + parameters: + - name: skillName + in: path + required: true + schema: + type: string + - name: skillVersion + in: path + required: true + schema: + type: integer + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteSkillVersionResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 +components: + schemas: + AnnotationQueueStatus: + title: AnnotationQueueStatus + type: string + enum: + - PENDING + - COMPLETED + AnnotationQueueObjectType: + title: AnnotationQueueObjectType + type: string + enum: + - TRACE + - OBSERVATION + - SESSION + AnnotationQueue: + title: AnnotationQueue + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + nullable: true + scoreConfigIds: + type: array + items: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - name + - description + - scoreConfigIds + - createdAt + - updatedAt + AnnotationQueueItem: + title: AnnotationQueueItem + type: object + properties: + id: + type: string + queueId: + type: string + objectId: + type: string + objectType: + $ref: '#/components/schemas/AnnotationQueueObjectType' + status: + $ref: '#/components/schemas/AnnotationQueueStatus' + completedAt: + type: string + format: date-time + nullable: true + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - queueId + - objectId + - objectType + - status + - createdAt + - updatedAt + PaginatedAnnotationQueues: + title: PaginatedAnnotationQueues + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/AnnotationQueue' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + PaginatedAnnotationQueueItems: + title: PaginatedAnnotationQueueItems + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/AnnotationQueueItem' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateAnnotationQueueRequest: + title: CreateAnnotationQueueRequest + type: object + properties: + name: + type: string + description: + type: string + nullable: true + scoreConfigIds: + type: array + items: + type: string + required: + - name + - scoreConfigIds + CreateAnnotationQueueItemRequest: + title: CreateAnnotationQueueItemRequest + type: object + properties: + objectId: + type: string + objectType: + $ref: '#/components/schemas/AnnotationQueueObjectType' + status: + $ref: '#/components/schemas/AnnotationQueueStatus' + nullable: true + description: Defaults to PENDING for new queue items + required: + - objectId + - objectType + UpdateAnnotationQueueItemRequest: + title: UpdateAnnotationQueueItemRequest + type: object + properties: + status: + $ref: '#/components/schemas/AnnotationQueueStatus' + nullable: true + DeleteAnnotationQueueItemResponse: + title: DeleteAnnotationQueueItemResponse + type: object + properties: + success: + type: boolean + message: + type: string + required: + - success + - message + AnnotationQueueAssignmentRequest: + title: AnnotationQueueAssignmentRequest + type: object + properties: + userId: + type: string + required: + - userId + DeleteAnnotationQueueAssignmentResponse: + title: DeleteAnnotationQueueAssignmentResponse + type: object + properties: + success: + type: boolean + required: + - success + CreateAnnotationQueueAssignmentResponse: + title: CreateAnnotationQueueAssignmentResponse + type: object + properties: + userId: + type: string + queueId: + type: string + projectId: + type: string + required: + - userId + - queueId + - projectId + BlobStorageIntegrationType: + title: BlobStorageIntegrationType + type: string + enum: + - S3 + - S3_COMPATIBLE + - AZURE_BLOB_STORAGE + BlobStorageIntegrationFileType: + title: BlobStorageIntegrationFileType + type: string + enum: + - JSON + - CSV + - JSONL + - PARQUET + description: >- + File format for exported data. `PARQUET` is a columnar binary format + encoded and compressed by the storage engine; gzip compression does not + apply to it. Note that the model-price columns (`input_price`, + `output_price`, `total_price`) are not included in Parquet observation + exports. + BlobStorageIntegrationFileTypeResponse: + title: BlobStorageIntegrationFileTypeResponse + type: string + enum: + - JSON + - CSV + - JSONL + - PARQUET + description: File type reported for an existing integration. + BlobStorageExportMode: + title: BlobStorageExportMode + type: string + enum: + - FULL_HISTORY + - FROM_TODAY + - FROM_CUSTOM_DATE + BlobStorageExportFrequency: + title: BlobStorageExportFrequency + type: string + enum: + - every_20_minutes + - hourly + - daily + - weekly + BlobStorageExportSource: + title: BlobStorageExportSource + type: string + enum: + - LEGACY_TRACES_OBSERVATIONS + - OBSERVATIONS_V2 + - LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS + description: >- + What data the integration exports. + + - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables. + Observation columns are controlled by `exportFieldGroups`; field groups + without a counterpart in this data model (e.g. `trace_context`) are + omitted. + + - `OBSERVATIONS_V2`: same data model as the + `/api/public/v2/observations` endpoint, plus scores. Columns are + controlled by `exportFieldGroups`. + + - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation + columns of both portions are controlled by `exportFieldGroups`. + + + **Note:** which sources a deployment accepts depends on how far it has + moved to the v4 data model. `OBSERVATIONS_V2` and the + enriched-observations portion of + `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations + table, so they require a deployment that already populates it. + `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of + `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and + observations tables, so they require a deployment that still populates + those. A deployment part-way through the migration populates both and + accepts every source. Selecting a source the deployment cannot serve is + rejected with `400`, rather than exporting an empty result. See + https://langfuse.com/docs/v4. + BlobStorageExportFieldGroup: + title: BlobStorageExportFieldGroup + type: string + enum: + - core + - basic + - time + - io + - metadata + - model + - usage + - prompt + - metrics + - tools + - trace_context + description: >- + Field group selecting which observation columns are included in the + export. Applies to all export sources; groups without a counterpart in + the legacy data model (e.g. `trace_context`) are omitted from the legacy + observations export. + CreateBlobStorageIntegrationRequest: + title: CreateBlobStorageIntegrationRequest + type: object + properties: + projectId: + type: string + description: ID of the project in which to configure the blob storage integration + type: + $ref: '#/components/schemas/BlobStorageIntegrationType' + bucketName: + type: string + description: >- + Name of the storage bucket. For AZURE_BLOB_STORAGE, must be a valid + Azure container name (3-63 chars, lowercase letters, numbers, and + hyphens only, must start and end with a letter or number, no + consecutive hyphens). + endpoint: + type: string + nullable: true + description: Custom endpoint URL (required for S3_COMPATIBLE type) + region: + type: string + description: >- + Storage region used by S3-compatible clients (AWS, GCS, Cloudflare + R2, MinIO, Azure location IDs such as eastus, OCI). Leading and + trailing whitespace is removed. The remaining value must be 1-63 + letters, numbers, or hyphens, and cannot start or end with a hyphen. + Examples: us-east-1, europe-west1, eastus, auto. + accessKeyId: + type: string + nullable: true + description: Access key ID for authentication + secretAccessKey: + type: string + nullable: true + description: Secret access key for authentication (will be encrypted when stored) + prefix: + type: string + nullable: true + description: >- + Path prefix for exported files (must end with forward slash if + provided) + exportFrequency: + $ref: '#/components/schemas/BlobStorageExportFrequency' + enabled: + type: boolean + description: Whether the integration is active + forcePathStyle: + type: boolean + description: Use path-style URLs for S3 requests + fileType: + $ref: '#/components/schemas/BlobStorageIntegrationFileType' + exportMode: + $ref: '#/components/schemas/BlobStorageExportMode' + exportStartDate: + type: string + format: date-time + nullable: true + description: >- + Custom start date for exports (required when exportMode is + FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for + timezone differences). + compressed: + type: boolean + nullable: true + description: >- + Enable gzip compression for exported files (.csv.gz, .json.gz, + .jsonl.gz). Defaults to true. + exportSource: + $ref: '#/components/schemas/BlobStorageExportSource' + nullable: true + description: >- + Data to export. When omitted on update, the existing value is + preserved. When omitted on create, the default is `OBSERVATIONS_V2` + on Langfuse Cloud, and on self-hosted deployments + `LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the + deployment no longer populates the legacy tables. The default is + never a source the deployment cannot serve. Required when + `exportFieldGroups` is provided. + + + **Cloud-only project deprecation gate (effective 2026-05-20):** For + projects created on or after 2026-05-20 on Langfuse Cloud, + `LEGACY_TRACES_OBSERVATIONS` and + `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP + 400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted + deployments are unaffected. + + + **Cloud-only integration deprecation gate (effective 2026-06-22):** + On Langfuse Cloud, legacy export sources are only accepted for blob + storage integrations created before 2026-06-22, regardless of + project age. Requests that would create a new integration with + `LEGACY_TRACES_OBSERVATIONS` or + `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP + 400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are + unaffected. + exportFieldGroups: + type: array + items: + $ref: '#/components/schemas/BlobStorageExportFieldGroup' + nullable: true + description: >- + Field groups to include in each exported observation row. Applies to + all export sources; must include `core` if provided. When omitted on + create, the column default (all groups) applies. When omitted on + update, the existing value is preserved. + + + `exportFieldGroups` requires `exportSource` to be provided in the + same request. + required: + - projectId + - type + - bucketName + - region + - exportFrequency + - enabled + - forcePathStyle + - fileType + - exportMode + BlobStorageIntegrationResponse: + title: BlobStorageIntegrationResponse + type: object + properties: + id: + type: string + projectId: + type: string + type: + $ref: '#/components/schemas/BlobStorageIntegrationType' + bucketName: + type: string + endpoint: + type: string + nullable: true + region: + type: string + accessKeyId: + type: string + nullable: true + prefix: + type: string + exportFrequency: + $ref: '#/components/schemas/BlobStorageExportFrequency' + enabled: + type: boolean + forcePathStyle: + type: boolean + fileType: + $ref: '#/components/schemas/BlobStorageIntegrationFileTypeResponse' + exportMode: + $ref: '#/components/schemas/BlobStorageExportMode' + exportStartDate: + type: string + format: date-time + nullable: true + compressed: + type: boolean + exportSource: + $ref: '#/components/schemas/BlobStorageExportSource' + exportFieldGroups: + type: array + items: + $ref: '#/components/schemas/BlobStorageExportFieldGroup' + nullable: true + description: >- + Field groups included in each exported observation row. An empty + list is treated as all groups during export. + nextSyncAt: + type: string + format: date-time + nullable: true + lastSyncAt: + type: string + format: date-time + nullable: true + lastError: + type: string + nullable: true + lastErrorAt: + type: string + format: date-time + nullable: true + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - projectId + - type + - bucketName + - endpoint + - region + - accessKeyId + - prefix + - exportFrequency + - enabled + - forcePathStyle + - fileType + - exportMode + - exportStartDate + - compressed + - exportSource + - exportFieldGroups + - nextSyncAt + - lastSyncAt + - lastError + - lastErrorAt + - createdAt + - updatedAt + BlobStorageIntegrationsResponse: + title: BlobStorageIntegrationsResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/BlobStorageIntegrationResponse' + required: + - data + BlobStorageSyncStatus: + title: BlobStorageSyncStatus + type: string + enum: + - idle + - running + - queued + - up_to_date + - disabled + - error + description: >- + Sync status of the blob storage integration: + + - `disabled` — integration is not enabled + + - `error` — last export failed (see `lastError` for details) + + - `running` — an export job is currently being processed + + - `queued` — next export is overdue (`nextSyncAt` is in the past) and + waiting to be picked up by the worker + + - `idle` — enabled but has never exported yet and no export is queued + + - `up_to_date` — all available data has been exported; next export is + scheduled for the future + + + **ETL usage**: poll this endpoint and check for `up_to_date` status. + Compare `lastSyncAt` against your + + ETL bookmark to determine if new data is available. Note that exports + run with a 20-minute lag buffer, + + so `lastSyncAt` will always be at least 20 minutes behind real-time. + BlobStorageIntegrationStatusResponse: + title: BlobStorageIntegrationStatusResponse + type: object + properties: + id: + type: string + projectId: + type: string + syncStatus: + $ref: '#/components/schemas/BlobStorageSyncStatus' + enabled: + type: boolean + lastSyncAt: + type: string + format: date-time + nullable: true + description: >- + End of the last successfully exported time window. Compare against + your ETL bookmark to determine if new data is available. Null if the + integration has never synced. + nextSyncAt: + type: string + format: date-time + nullable: true + description: When the next export is scheduled. Null if no sync has occurred yet. + lastError: + type: string + nullable: true + description: >- + Raw error message from the storage provider (S3/Azure/GCS) if the + last export failed. Cleared on successful export. + lastErrorAt: + type: string + format: date-time + nullable: true + description: When the last error occurred. Cleared on successful export. + required: + - id + - projectId + - syncStatus + - enabled + - lastSyncAt + - nextSyncAt + - lastError + - lastErrorAt + BlobStorageIntegrationDeletionResponse: + title: BlobStorageIntegrationDeletionResponse + type: object + properties: + message: + type: string + required: + - message + CreateCommentRequest: + title: CreateCommentRequest + type: object + properties: + projectId: + type: string + description: The id of the project to attach the comment to. + objectType: + type: string + description: >- + The type of the object to attach the comment to (trace, observation, + session, prompt). + objectId: + type: string + description: >- + The id of the object to attach the comment to. If this does not + reference a valid existing object, an error will be thrown. + content: + type: string + description: >- + The content of the comment. May include markdown. Currently limited + to 5000 characters. + authorUserId: + type: string + nullable: true + description: >- + The id of the user who created the comment. Must be a member of the + organization that owns the project, otherwise an error will be + thrown. + objectStartTime: + type: string + format: date-time + nullable: true + description: >- + The start time of the referenced object (for observations, the + observation's start time). Optional performance hint - when + provided, Langfuse narrows the lookup to validate the reference + faster. It only affects speed - an incorrect or omitted value never + changes the result. + required: + - projectId + - objectType + - objectId + - content + CreateCommentResponse: + title: CreateCommentResponse + type: object + properties: + id: + type: string + description: The id of the created object in Langfuse + required: + - id + GetCommentsResponse: + title: GetCommentsResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Comment' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + Deprecation: + title: Deprecation + type: object + description: >- + Migration signal returned by deprecated endpoints. Optional fields are + omitted when they have no value. + properties: + message: + type: string + description: >- + Human- and agent-readable summary of the deprecation and its + replacement. + replacement: + type: string + nullable: true + description: >- + The replacement endpoint, e.g. "GET /api/public/v2/observations". + Omitted when the endpoint is being removed without a direct + replacement. + docsUrl: + type: string + nullable: true + description: Link to the migration documentation (markdown), when available. + sunsetAt: + type: string + nullable: true + description: >- + ISO date after which the endpoint may stop working, when a removal + date is committed. + required: + - message + Trace: + title: Trace + type: object + properties: + id: + type: string + description: The unique identifier of a trace + timestamp: + type: string + format: date-time + description: The timestamp when the trace was created + name: + type: string + nullable: true + description: The name of the trace + input: + nullable: true + description: The input data of the trace. Can be any JSON. + output: + nullable: true + description: The output data of the trace. Can be any JSON. + sessionId: + type: string + nullable: true + description: The session identifier associated with the trace + release: + type: string + nullable: true + description: The release version of the application when the trace was created + version: + type: string + nullable: true + description: The version of the trace + userId: + type: string + nullable: true + description: The user identifier associated with the trace + metadata: + 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 + - name + - sessionId + - release + - version + - userId + - tags + - public + - environment + TraceWithDetails: + title: TraceWithDetails + type: object + properties: + htmlPath: + type: string + description: Path of trace in Langfuse UI + latency: + type: number + format: double + nullable: true + description: Latency of trace in seconds + totalCost: + type: number + format: double + nullable: true + description: Cost of trace in USD + observations: + type: array + items: + type: string + nullable: true + description: List of observation ids + scores: + type: array + items: + type: string + nullable: true + description: List of score ids + required: + - htmlPath + allOf: + - $ref: '#/components/schemas/Trace' + TraceWithFullDetails: + title: TraceWithFullDetails + type: object + properties: + htmlPath: + type: string + description: Path of trace in Langfuse UI + latency: + type: number + format: double + nullable: true + description: Latency of trace in seconds + totalCost: + type: number + format: double + nullable: true + description: Cost of trace in USD + observations: + type: array + items: + $ref: '#/components/schemas/ObservationsView' + description: List of observations + scores: + type: array + items: + $ref: '#/components/schemas/ScoreV1' + description: List of scores + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - htmlPath + - observations + - scores + allOf: + - $ref: '#/components/schemas/Trace' + Session: + title: Session + type: object + properties: + id: + type: string + createdAt: + type: string + format: date-time + projectId: + type: string + environment: + type: string + description: The environment from which this session originated. + required: + - id + - createdAt + - projectId + - environment + SessionWithTraces: + title: SessionWithTraces + type: object + properties: + traces: + type: array + items: + $ref: '#/components/schemas/Trace' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - traces + allOf: + - $ref: '#/components/schemas/Session' + Observation: + title: Observation + type: object + properties: + id: + type: string + description: The unique identifier of the observation + traceId: + type: string + nullable: true + description: The trace ID associated with the observation + type: + type: string + description: The type of the observation + name: + type: string + nullable: true + description: The name of the observation + startTime: + type: string + format: date-time + description: The start time of the observation + endTime: + type: string + format: date-time + nullable: true + description: The end time of the observation. + completionStartTime: + type: string + format: date-time + nullable: true + description: The completion start time of the observation + model: + type: string + nullable: true + description: The model used for the observation + modelParameters: + description: The parameters of the model used for the observation + input: + description: The input data of the observation + version: + type: string + nullable: true + description: The version of the observation + metadata: + description: Additional metadata of the observation + output: + description: The output data of the observation + usage: + $ref: '#/components/schemas/Usage' + description: >- + (Deprecated. Use usageDetails and costDetails instead.) The usage + data of the observation + level: + $ref: '#/components/schemas/ObservationLevel' + description: The level of the observation + statusMessage: + type: string + nullable: true + description: The status message of the observation + parentObservationId: + type: string + nullable: true + description: The parent observation ID + promptId: + type: string + nullable: true + description: The prompt ID associated with the observation + usageDetails: + type: object + additionalProperties: + type: integer + description: >- + The usage details of the observation. Key is the name of the usage + metric, value is the number of units consumed. The total key is the + sum of all (non-total) usage metrics or the total value ingested. + costDetails: + type: object + additionalProperties: + type: number + format: double + description: >- + The cost details of the observation. Key is the name of the cost + metric, value is the cost in USD. The total key is the sum of all + (non-total) cost metrics or the total value ingested. + environment: + type: string + description: >- + The environment from which this observation originated. Can be any + lowercase alphanumeric string with hyphens and underscores that does + not start with 'langfuse'. + required: + - id + - traceId + - type + - name + - startTime + - endTime + - completionStartTime + - model + - modelParameters + - input + - version + - metadata + - output + - usage + - level + - statusMessage + - parentObservationId + - promptId + - usageDetails + - costDetails + - environment + ObservationsView: + title: ObservationsView + type: object + properties: + promptName: + type: string + nullable: true + description: The name of the prompt associated with the observation + promptVersion: + type: integer + nullable: true + description: The version of the prompt associated with the observation + modelId: + type: string + nullable: true + description: The unique identifier of the model + inputPrice: + type: number + format: double + nullable: true + description: The price of the input in USD + outputPrice: + type: number + format: double + nullable: true + description: The price of the output in USD. + totalPrice: + type: number + format: double + nullable: true + description: The total price in USD. + calculatedInputCost: + type: number + format: double + nullable: true + description: >- + (Deprecated. Use usageDetails and costDetails instead.) The + calculated cost of the input in USD + calculatedOutputCost: + type: number + format: double + nullable: true + description: >- + (Deprecated. Use usageDetails and costDetails instead.) The + calculated cost of the output in USD + calculatedTotalCost: + type: number + format: double + nullable: true + description: >- + (Deprecated. Use usageDetails and costDetails instead.) The + calculated total cost in USD + latency: + type: number + format: double + nullable: true + description: The latency in seconds. + timeToFirstToken: + type: number + format: double + nullable: true + description: The time to the first token in seconds + required: + - promptName + - promptVersion + - modelId + - inputPrice + - outputPrice + - totalPrice + - calculatedInputCost + - calculatedOutputCost + - calculatedTotalCost + - latency + - timeToFirstToken + allOf: + - $ref: '#/components/schemas/Observation' + ObservationsViewSingle: + title: ObservationsViewSingle + type: object + properties: + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + allOf: + - $ref: '#/components/schemas/ObservationsView' + ObservationV2: + title: ObservationV2 + type: object + description: >- + An observation from the v2 API with field-group-based selection. + + Core fields are always present. Other fields are included only when + their field group is requested. + properties: + id: + type: string + description: The unique identifier of the observation + traceId: + type: string + nullable: true + description: The trace ID associated with the observation + startTime: + type: string + format: date-time + description: The start time of the observation + endTime: + type: string + format: date-time + nullable: true + description: The end time of the observation + projectId: + type: string + description: The project ID this observation belongs to + parentObservationId: + type: string + nullable: true + description: >- + The physical parent observation ID, if present. + + Observations marked as app roots by the SDK may retain a non-null + parent ID. + type: + type: string + description: The type of the observation (e.g. GENERATION, SPAN, EVENT) + isRootObservation: + type: boolean + nullable: true + description: >- + Whether this observation is a logical root. + + This is true for observations without a physical parent and + observations marked as app roots by the SDK. + name: + type: string + nullable: true + description: The name of the observation + level: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + description: The level of the observation + statusMessage: + type: string + nullable: true + description: The status message of the observation + version: + type: string + nullable: true + description: The version of the observation + environment: + type: string + nullable: true + description: The environment from which this observation originated + bookmarked: + type: boolean + nullable: true + description: Whether the observation is bookmarked + public: + type: boolean + nullable: true + description: Whether the observation is public + userId: + type: string + nullable: true + description: The user ID associated with the observation + sessionId: + type: string + nullable: true + description: The session ID associated with the observation + completionStartTime: + type: string + format: date-time + nullable: true + description: The completion start time of the observation + createdAt: + type: string + format: date-time + nullable: true + description: The creation timestamp of the observation + updatedAt: + type: string + format: date-time + nullable: true + description: The last update timestamp of the observation + input: + nullable: true + description: The input data of the observation + output: + nullable: true + description: The output data of the observation + metadata: + nullable: true + description: Additional metadata of the observation + model: + type: string + nullable: true + description: The model name as provided by the user + internalModelId: + type: string + nullable: true + description: The internal model ID matched by Langfuse + modelParameters: + nullable: true + description: The parameters of the model used for the observation + usageDetails: + type: object + additionalProperties: + type: integer + nullable: true + description: >- + The usage details of the observation. Key is the usage metric name, + value is the number of units consumed. + costDetails: + type: object + additionalProperties: + type: number + format: double + nullable: true + description: >- + The cost details of the observation. Key is the cost metric name, + value is the cost in USD. + totalCost: + type: number + format: double + nullable: true + description: The total cost of the observation in USD + usagePricingTierName: + type: string + nullable: true + description: >- + The name of the pricing tier applied to this observation's usage + costs + promptId: + type: string + nullable: true + description: The prompt ID associated with the observation + promptName: + type: string + nullable: true + description: The prompt name associated with the observation + promptVersion: + type: integer + nullable: true + description: The prompt version associated with the observation + latency: + type: number + format: double + nullable: true + description: The latency in seconds + timeToFirstToken: + type: number + format: double + nullable: true + description: The time to first token in seconds + modelId: + type: string + nullable: true + description: >- + The matched model ID. Null when the `model` field group is not + requested. + inputPrice: + type: string + nullable: true + description: >- + The input token price (USD per unit) from the matched model, + serialized as a decimal string (e.g. "0.0001"). Null when the + `model` field group is not requested. + outputPrice: + type: string + nullable: true + description: >- + The output token price (USD per unit) from the matched model, + serialized as a decimal string (e.g. "0.0001"). Null when the + `model` field group is not requested. + totalPrice: + type: string + nullable: true + description: >- + The total token price (USD per unit) from the matched model, + serialized as a decimal string (e.g. "0.0001"). Null when the + `model` field group is not requested. + traceName: + type: string + nullable: true + description: The name of the parent trace + tags: + type: array + items: + type: string + nullable: true + description: Tags from the parent trace (denormalized onto the observation) + release: + type: string + nullable: true + description: The release version of the parent trace + required: + - id + - traceId + - startTime + - endTime + - projectId + - parentObservationId + - type + - modelId + - inputPrice + - outputPrice + - totalPrice + Usage: + title: Usage + type: object + description: >- + (Deprecated. Use usageDetails and costDetails instead.) Standard + interface for usage and cost + properties: + input: + type: integer + description: Number of input units (e.g. tokens) + output: + type: integer + description: Number of output units (e.g. tokens) + total: + type: integer + description: Defaults to input+output if not set + unit: + type: string + nullable: true + description: Unit of measurement + inputCost: + type: number + format: double + nullable: true + description: USD input cost + outputCost: + type: number + format: double + nullable: true + description: USD output cost + totalCost: + type: number + format: double + nullable: true + description: USD total cost, defaults to input+output + required: + - input + - output + - total + - unit + ScoreConfig: + title: ScoreConfig + type: object + description: Configuration for a score + properties: + id: + type: string + name: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + projectId: + type: string + dataType: + $ref: '#/components/schemas/ScoreConfigDataType' + isArchived: + type: boolean + description: Whether the score config is archived. Defaults to false + minValue: + type: number + format: double + nullable: true + description: >- + Sets minimum value for numerical scores. If not set, the minimum + value defaults to -∞ + maxValue: + type: number + format: double + nullable: true + description: >- + Sets maximum value for numerical scores. If not set, the maximum + value defaults to +∞ + categories: + type: array + items: + $ref: '#/components/schemas/ConfigCategory' + nullable: true + description: Configures custom categories for categorical scores + description: + type: string + nullable: true + description: Description of the score config + required: + - id + - name + - createdAt + - updatedAt + - projectId + - dataType + - isArchived + ConfigCategory: + title: ConfigCategory + type: object + properties: + value: + type: number + format: double + label: + type: string + required: + - value + - label + BaseScoreV1: + title: BaseScoreV1 + type: object + properties: + id: + type: string + traceId: + type: string + name: + type: string + source: + $ref: '#/components/schemas/ScoreSource' + observationId: + type: string + nullable: true + description: The observation ID associated with the score + timestamp: + type: string + format: date-time + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + authorUserId: + type: string + nullable: true + description: The user ID of the author + comment: + type: string + nullable: true + description: Comment on the score + metadata: + description: Metadata associated with the score + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. When set, config and score name + must be equal and value must comply to optionally defined numerical + range + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + environment: + type: string + description: >- + The environment from which this score originated. Can be any + lowercase alphanumeric string with hyphens and underscores that does + not start with 'langfuse'. + required: + - id + - traceId + - name + - source + - timestamp + - createdAt + - updatedAt + - authorUserId + - comment + - metadata + - configId + - queueId + - environment + NumericScoreV1: + title: NumericScoreV1 + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + BooleanScoreV1: + title: BooleanScoreV1 + type: object + properties: + value: + type: number + format: double + description: >- + The numeric value of the score. Equals 1 for "True" and 0 for "False" + stringValue: + type: string + description: >- + The string representation of the score value. Is inferred from the + numeric value and equals "True" or "False" + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + CategoricalScoreV1: + title: CategoricalScoreV1 + type: object + properties: + value: + type: number + format: double + description: >- + Represents the numeric category mapping of the stringValue. If no + config is linked, defaults to 0. + stringValue: + type: string + description: >- + The string representation of the score value. If no config is + linked, can be any string. Otherwise, must map to a config category + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + TextScoreV1: + title: TextScoreV1 + type: object + properties: + stringValue: + type: string + description: The text content of the score (1-500 characters) + required: + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + ScoreV1: + title: ScoreV1 + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/NumericScoreV1' + required: + - dataType + title: NumericScoreV1 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/CategoricalScoreV1' + required: + - dataType + title: CategoricalScoreV1 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/BooleanScoreV1' + required: + - dataType + title: BooleanScoreV1 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - TEXT + - $ref: '#/components/schemas/TextScoreV1' + required: + - dataType + title: TextScoreV1 + BaseScore: + title: BaseScore + type: object + properties: + id: + type: string + traceId: + type: string + nullable: true + description: The trace ID associated with the score + sessionId: + type: string + nullable: true + description: The session ID associated with the score + observationId: + type: string + nullable: true + description: The observation ID associated with the score + datasetRunId: + type: string + nullable: true + description: The dataset run ID associated with the score + name: + type: string + source: + $ref: '#/components/schemas/ScoreSource' + timestamp: + type: string + format: date-time + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + authorUserId: + type: string + nullable: true + description: The user ID of the author + comment: + type: string + nullable: true + description: Comment on the score + metadata: + description: Metadata associated with the score + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. When set, config and score name + must be equal and value must comply to optionally defined numerical + range + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + environment: + type: string + description: >- + The environment from which this score originated. Can be any + lowercase alphanumeric string with hyphens and underscores that does + not start with 'langfuse'. + required: + - id + - name + - source + - timestamp + - createdAt + - updatedAt + - authorUserId + - comment + - metadata + - configId + - queueId + - environment + NumericScore: + title: NumericScore + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScore' + BooleanScore: + title: BooleanScore + type: object + properties: + value: + type: number + format: double + description: >- + The numeric value of the score. Equals 1 for "True" and 0 for "False" + stringValue: + type: string + description: >- + The string representation of the score value. Is inferred from the + numeric value and equals "True" or "False" + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScore' + CategoricalScore: + title: CategoricalScore + type: object + properties: + value: + type: number + format: double + description: >- + Represents the numeric category mapping of the stringValue. If no + config is linked, defaults to 0. + stringValue: + type: string + description: >- + The string representation of the score value. If no config is + linked, can be any string. Otherwise, must map to a config category + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScore' + CorrectionScore: + title: CorrectionScore + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score. Always 0 for correction scores. + stringValue: + type: string + description: The string representation of the correction content + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScore' + TextScore: + title: TextScore + type: object + properties: + stringValue: + type: string + description: The text content of the score (1-500 characters) + required: + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScore' + Score: + title: Score + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/NumericScore' + required: + - dataType + title: NumericScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/CategoricalScore' + required: + - dataType + title: CategoricalScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/BooleanScore' + required: + - dataType + title: BooleanScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CORRECTION + - $ref: '#/components/schemas/CorrectionScore' + required: + - dataType + title: CorrectionScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - TEXT + - $ref: '#/components/schemas/TextScore' + required: + - dataType + title: TextScore + properties: + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + CreateScoreValue: + title: CreateScoreValue + oneOf: + - type: number + format: double + title: DoubleNumber + - type: string + title: String + description: >- + The value of the score. Must be passed as string for categorical and + text scores, and numeric for boolean and numeric scores + Comment: + title: Comment + type: object + properties: + id: + type: string + projectId: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + objectType: + $ref: '#/components/schemas/CommentObjectType' + objectId: + type: string + content: + type: string + authorUserId: + type: string + nullable: true + description: The user ID of the comment author + required: + - id + - projectId + - createdAt + - updatedAt + - objectType + - objectId + - content + Dataset: + title: Dataset + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + nullable: true + description: Description of the dataset + metadata: + description: Metadata associated with the dataset + inputSchema: + type: object + additionalProperties: true + nullable: true + description: JSON Schema for validating dataset item inputs + expectedOutputSchema: + type: object + additionalProperties: true + nullable: true + description: JSON Schema for validating dataset item expected outputs + projectId: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - name + - description + - metadata + - inputSchema + - expectedOutputSchema + - projectId + - createdAt + - updatedAt + DatasetItem: + title: DatasetItem + type: object + properties: + id: + type: string + status: + $ref: '#/components/schemas/DatasetStatus' + input: + description: Input data for the dataset item + expectedOutput: + description: Expected output for the dataset item + metadata: + description: Metadata associated with the dataset item + sourceTraceId: + type: string + nullable: true + description: The trace ID that sourced this dataset item + sourceObservationId: + type: string + nullable: true + description: The observation ID that sourced this dataset item + datasetId: + type: string + datasetName: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + mediaReferences: + type: array + items: + $ref: '#/components/schemas/DatasetItemMediaReference' + description: >- + Resolved Langfuse media references found in input, expectedOutput, + and metadata. + required: + - id + - status + - input + - expectedOutput + - metadata + - sourceTraceId + - sourceObservationId + - datasetId + - datasetName + - createdAt + - updatedAt + - mediaReferences + DatasetItemMediaReference: + title: DatasetItemMediaReference + type: object + properties: + field: + $ref: '#/components/schemas/DatasetItemMediaReferenceField' + description: The dataset item field containing the reference + referenceString: + type: string + description: >- + The Langfuse media reference string, e.g. + `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@` + jsonPath: + type: string + description: >- + JSONPath of the string holding the reference within the field, e.g. + `$['image']` + media: + $ref: '#/components/schemas/DatasetItemMediaReferenceMedia' + description: The resolved media record. + required: + - field + - referenceString + - jsonPath + - media + DatasetItemMediaReferenceField: + title: DatasetItemMediaReferenceField + type: string + enum: + - input + - expectedOutput + - metadata + DatasetItemMediaReferenceMedia: + title: DatasetItemMediaReferenceMedia + type: object + properties: + mediaId: + type: string + description: The unique langfuse identifier of the media record + contentType: + type: string + description: The MIME type of the media record + contentLength: + type: integer + description: The size of the media record in bytes + url: + type: string + description: The signed download URL of the media record + urlExpiry: + type: string + description: The expiry date and time of the download URL + required: + - mediaId + - contentType + - contentLength + - url + - urlExpiry + DatasetRunItem: + title: DatasetRunItem + type: object + properties: + id: + type: string + datasetRunId: + type: string + datasetRunName: + type: string + datasetItemId: + type: string + traceId: + type: string + observationId: + type: string + nullable: true + description: The observation ID associated with this run item + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - datasetRunId + - datasetRunName + - datasetItemId + - traceId + - observationId + - createdAt + - updatedAt + DatasetRun: + title: DatasetRun + type: object + properties: + id: + type: string + description: Unique identifier of the dataset run + name: + type: string + description: Name of the dataset run + description: + type: string + nullable: true + description: Description of the run + metadata: + description: Metadata of the dataset run + datasetId: + type: string + description: Id of the associated dataset + datasetName: + type: string + description: Name of the associated dataset + createdAt: + type: string + format: date-time + description: The date and time when the dataset run was created + updatedAt: + type: string + format: date-time + description: The date and time when the dataset run was last updated + required: + - id + - name + - description + - metadata + - datasetId + - datasetName + - createdAt + - updatedAt + DatasetRunWithItems: + title: DatasetRunWithItems + type: object + properties: + datasetRunItems: + type: array + items: + $ref: '#/components/schemas/DatasetRunItem' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - datasetRunItems + allOf: + - $ref: '#/components/schemas/DatasetRun' + Model: + title: Model + type: object + description: >- + Model definition used for transforming usage into USD cost and/or + tokenization. + + + Models can have either simple flat pricing or tiered pricing: + + - Flat pricing: Single price per usage type (legacy, but still + supported) + + - Tiered pricing: Multiple pricing tiers with conditional matching based + on usage patterns or observation attributes + + + The pricing tiers approach is recommended for models with usage-based + pricing variations. + + When using tiered pricing, the flat price fields (inputPrice, + outputPrice, prices) are populated + + from the default tier for backward compatibility. + properties: + id: + type: string + modelName: + type: string + description: >- + Name of the model definition. If multiple with the same name exist, + they are applied in the following order: (1) custom over built-in, + (2) newest according to startTime where + model.startTime- + Regex pattern which matches this model definition to + generation.model. Useful in case of fine-tuned models. If you want + to exact match, use `(?i)^modelname$` + startDate: + type: string + format: date-time + nullable: true + description: Apply only to generations which are newer than this ISO date. + unit: + $ref: '#/components/schemas/ModelUsageUnit' + nullable: true + description: Unit used by this model. + inputPrice: + type: number + format: double + nullable: true + description: Deprecated. See 'prices' instead. Price (USD) per input unit + outputPrice: + type: number + format: double + nullable: true + description: Deprecated. See 'prices' instead. Price (USD) per output unit + totalPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot + be set if input or output price is set. + tokenizerId: + type: string + nullable: true + description: >- + Optional. Tokenizer to be applied to observations which match to + this model. See docs for more details. + tokenizerConfig: + description: >- + Optional. Configuration for the selected tokenizer. Needs to be + JSON. See docs for more details. + isLangfuseManaged: + type: boolean + createdAt: + type: string + format: date-time + description: Timestamp when the model was created + prices: + type: object + additionalProperties: + $ref: '#/components/schemas/ModelPrice' + description: >- + Deprecated. Use 'pricingTiers' instead for models with usage-based + pricing variations. + + + This field shows prices by usage type from the default pricing tier. + Maintained for backward compatibility. + + If the model uses tiered pricing, this field will be populated from + the default tier's prices. + pricingTiers: + type: array + items: + $ref: '#/components/schemas/PricingTier' + description: >- + Array of pricing tiers with conditional pricing based on usage + thresholds or observation attributes. + + + Pricing tiers enable accurate cost tracking for models that charge + different rates based on usage patterns + + or request attributes (e.g., high-volume usage, large context + windows, cached tokens, or service tiers). + + + Each model must have exactly one default tier (isDefault=true, + priority=0) that serves as a fallback. + + Additional conditional tiers can be defined with specific matching + criteria. + + + If this array is empty, the model uses legacy flat pricing from the + inputPrice/outputPrice/totalPrice fields. + required: + - id + - modelName + - matchPattern + - startDate + - inputPrice + - outputPrice + - totalPrice + - tokenizerId + - tokenizerConfig + - isLangfuseManaged + - createdAt + - prices + - pricingTiers + ModelPrice: + title: ModelPrice + type: object + properties: + price: + type: number + format: double + required: + - price + PricingTierCondition: + title: PricingTierCondition + oneOf: + - $ref: '#/components/schemas/PricingTierUsageCondition' + - $ref: '#/components/schemas/PricingTierAttributeCondition' + description: >- + Condition for matching a pricing tier against usage details or + observation attributes. + + + Usage-detail conditions treat usageDetailPattern as a regex, sum all + matching usage values, and compare the sum to the numeric value. + Model-parameter and metadata conditions match an exact top-level key + against one or more string values. + PricingTierUsageCondition: + title: PricingTierUsageCondition + type: object + description: Condition that sums usage details whose keys match a regex. + properties: + usageDetailPattern: + type: string + description: Regex pattern matched against usage detail keys. + operator: + $ref: '#/components/schemas/PricingTierOperator' + value: + type: number + format: double + description: Numeric threshold for the summed matching usage values. + caseSensitive: + type: boolean + description: Whether the usage-detail regex is case-sensitive. + required: + - usageDetailPattern + - operator + - value + - caseSensitive + PricingTierAttributeCondition: + title: PricingTierAttributeCondition + type: object + description: >- + Condition that matches any configured value for a top-level observation + attribute. + properties: + source: + $ref: '#/components/schemas/PricingTierAttributeSource' + description: Observation attribute object evaluated by this condition. + key: + type: string + description: Exact top-level attribute key. + operator: + type: string + const: in + description: Membership operator. + values: + type: array + items: + type: string + description: Accepted string attribute values. At least one value is required. + required: + - source + - key + - operator + - values + PricingTierAttributeSource: + title: PricingTierAttributeSource + type: string + enum: + - model_parameters + - metadata + PricingTierConditionInput: + title: PricingTierConditionInput + oneOf: + - $ref: '#/components/schemas/PricingTierUsageConditionInput' + - $ref: '#/components/schemas/PricingTierAttributeCondition' + description: Condition input for matching a pricing tier. + PricingTierUsageConditionInput: + title: PricingTierUsageConditionInput + type: object + description: Input condition that sums usage details whose keys match a regex. + properties: + usageDetailPattern: + type: string + description: Regex pattern matched against usage detail keys. + operator: + $ref: '#/components/schemas/PricingTierOperator' + value: + type: number + format: double + description: Numeric threshold for the summed matching usage values. + caseSensitive: + type: boolean + nullable: true + description: Whether the usage-detail regex is case-sensitive. Defaults to false. + required: + - usageDetailPattern + - operator + - value + PricingTier: + title: PricingTier + type: object + description: >- + Pricing tier definition with conditional pricing based on usage + thresholds or observation attributes. + + + Pricing tiers enable accurate cost tracking for LLM providers that + charge different rates based on usage patterns or request attributes. + + For example, some providers charge higher rates when context size + exceeds certain thresholds or when an accelerated service tier is + selected. + + + How tier matching works: + + 1. Tiers are evaluated in ascending priority order (priority 1 before + priority 2, etc.) + + 2. The first tier where ALL conditions match is selected + + 3. If no conditional tiers match, the default tier is used as a fallback + + 4. The default tier has priority 0 and no conditions + + + Why priorities matter: + + - Lower priority numbers are evaluated first, allowing you to define + specific cases before general ones + + - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for + "medium usage" (>100K tokens), Priority 0 for default + + - Without proper ordering, a less specific condition might match before + a more specific one + + + Every model must have exactly one default tier to ensure cost + calculation always succeeds. + properties: + id: + type: string + description: Unique identifier for the pricing tier + name: + type: string + description: >- + Name of the pricing tier for display and identification purposes. + + + Examples: "Standard", "High Volume Tier", "Large Context", "Extended + Context Tier" + isDefault: + type: boolean + description: >- + Whether this is the default tier. Every model must have exactly one + default tier with priority 0 and no conditions. + + + The default tier serves as a fallback when no conditional tiers + match, ensuring cost calculation always succeeds. + + It typically represents the base pricing for standard usage + patterns. + priority: + type: integer + description: >- + Priority for tier matching evaluation. Lower numbers = higher + priority (evaluated first). + + + The default tier must always have priority 0. Conditional tiers + should have priority 1, 2, 3, etc. + + + Example ordering: + + - Priority 0: Default tier (no conditions, always matches as + fallback) + + - Priority 1: High usage tier (e.g., >200K tokens) + + - Priority 2: Medium usage tier (e.g., >100K tokens) + + + This ensures more specific conditions are checked before general + ones. + conditions: + type: array + items: + $ref: '#/components/schemas/PricingTierCondition' + description: >- + Array of conditions that must ALL be met for this tier to match (AND + logic). + + + The default tier must have an empty conditions array. Conditional + tiers should have one or more conditions + + that define when this tier's pricing applies. + + + Multiple conditions enable complex matching scenarios (e.g., "high + input tokens AND low output tokens"). + prices: + type: object + additionalProperties: + type: number + format: double + description: >- + Prices (USD) by usage type for this tier. + + + Common usage types: "input", "output", "total", "request", "image" + + Prices are specified in USD per unit (e.g., per token, per request, + per second). + + + Example: {"input": 0.000003, "output": 0.000015} means $3 per + million input tokens and $15 per million output tokens. + required: + - id + - name + - isDefault + - priority + - conditions + - prices + PricingTierInput: + title: PricingTierInput + type: object + description: >- + Input schema for creating a pricing tier. The tier ID will be + automatically generated server-side. + + + When creating a model with pricing tiers: + + - Exactly one tier must have isDefault=true (the fallback tier) + + - The default tier must have priority=0 and conditions=[] + + - All tier names and priorities must be unique within the model + + - Each tier must define at least one price + + + See PricingTier for detailed information about how tiers work and why + they're useful. + properties: + name: + type: string + description: >- + Name of the pricing tier for display and identification purposes. + + + Must be unique within the model. Common patterns: "Standard", "High + Volume Tier", "Extended Context" + isDefault: + type: boolean + nullable: true + description: >- + Whether this is the default tier. Exactly one tier per model must be + marked as default. + + + Requirements for default tier: + + - Must have isDefault=true + + - Must have priority=0 + + - Must have empty conditions array (conditions=[]) + + + The default tier acts as a fallback when no conditional tiers match. + Defaults to false when omitted. + priority: + type: integer + description: >- + Priority for tier matching evaluation. Lower numbers = higher + priority (evaluated first). + + + Must be unique within the model. The default tier must have + priority=0. + + Conditional tiers should use priority 1, 2, 3, etc. based on their + specificity. + conditions: + type: array + items: + $ref: '#/components/schemas/PricingTierConditionInput' + description: >- + Array of conditions that must ALL be met for this tier to match (AND + logic). + + + The default tier must have an empty array (conditions=[]). + + Conditional tiers should define one or more conditions that specify + when this tier's pricing applies. + + + Conditions can compare summed matching usage details to a numeric + threshold, or exactly match a top-level model parameter or metadata + value. + prices: + type: object + additionalProperties: + type: number + format: double + description: >- + Prices (USD) by usage type for this tier. At least one price must be + defined. + + + Common usage types: "input", "output", "total", "request", "image" + + Prices are in USD per unit (e.g., per token). + + + Example: {"input": 0.000003, "output": 0.000015} represents $3 per + million input tokens and $15 per million output tokens. + required: + - name + - priority + - conditions + - prices + PricingTierOperator: + title: PricingTierOperator + type: string + enum: + - gt + - gte + - lt + - lte + - eq + - neq + description: Comparison operators for pricing tier conditions + ModelUsageUnit: + title: ModelUsageUnit + type: string + enum: + - CHARACTERS + - TOKENS + - MILLISECONDS + - SECONDS + - IMAGES + - REQUESTS + description: Unit of usage in Langfuse + ObservationLevel: + title: ObservationLevel + type: string + enum: + - DEBUG + - DEFAULT + - WARNING + - ERROR + MapValue: + title: MapValue + oneOf: + - type: string + nullable: true + title: String + - type: integer + nullable: true + title: Integer + - type: number + format: float + nullable: true + title: FloatNumber + - type: boolean + nullable: true + title: Boolean + - type: array + items: + type: string + nullable: true + title: Array + CommentObjectType: + title: CommentObjectType + type: string + enum: + - TRACE + - OBSERVATION + - SESSION + - PROMPT + DatasetStatus: + title: DatasetStatus + type: string + enum: + - ACTIVE + - ARCHIVED + ScoreSource: + title: ScoreSource + type: string + enum: + - ANNOTATION + - API + - EVAL + ScoreConfigDataType: + title: ScoreConfigDataType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + - TEXT + ScoreDataType: + title: ScoreDataType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + - CORRECTION + - TEXT + DeleteDatasetItemResponse: + title: DeleteDatasetItemResponse + type: object + properties: + message: + type: string + description: Success message after deletion + required: + - message + CreateDatasetItemRequest: + title: CreateDatasetItemRequest + type: object + properties: + datasetName: + type: string + input: + nullable: true + expectedOutput: + nullable: true + metadata: + nullable: true + sourceTraceId: + type: string + nullable: true + sourceObservationId: + type: string + nullable: true + id: + type: string + nullable: true + description: >- + Dataset items are upserted on their id. Id needs to be unique + (project-level), cannot be reused across datasets, and must be at + most 255 characters. + status: + $ref: '#/components/schemas/DatasetStatus' + nullable: true + description: Defaults to ACTIVE for newly created items + required: + - datasetName + PaginatedDatasetItems: + title: PaginatedDatasetItems + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/DatasetItem' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateDatasetRunItemRequest: + title: CreateDatasetRunItemRequest + type: object + properties: + runName: + type: string + runDescription: + type: string + nullable: true + description: Description of the run. If run exists, description will be updated. + metadata: + nullable: true + description: Metadata of the dataset run, updates run if run already exists + datasetItemId: + type: string + observationId: + type: string + nullable: true + traceId: + type: string + nullable: true + description: >- + traceId should always be provided. For compatibility with older SDK + versions it can also be inferred from the provided observationId. + datasetVersion: + type: string + format: date-time + nullable: true + description: >- + ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g., + "2026-01-21T14:35:42Z"). + + Specifies the dataset version to use for this experiment run. + + If provided, the experiment will use dataset items as they existed + at or before this timestamp. + + If not provided, uses the latest version of dataset items. + createdAt: + type: string + format: date-time + nullable: true + description: >- + Optional timestamp to set the createdAt field of the dataset run + item. If not provided or null, defaults to current timestamp. + required: + - runName + - datasetItemId + PaginatedDatasetRunItems: + title: PaginatedDatasetRunItems + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/DatasetRunItem' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + PaginatedDatasets: + title: PaginatedDatasets + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Dataset' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateDatasetRequest: + title: CreateDatasetRequest + type: object + properties: + name: + type: string + description: + type: string + nullable: true + metadata: + nullable: true + inputSchema: + type: object + additionalProperties: true + nullable: true + description: >- + JSON Schema for validating dataset item inputs. When set, all new + and existing dataset items will be validated against this schema. + expectedOutputSchema: + type: object + additionalProperties: true + nullable: true + description: >- + JSON Schema for validating dataset item expected outputs. When set, + all new and existing dataset items will be validated against this + schema. + required: + - name + PaginatedDatasetRuns: + title: PaginatedDatasetRuns + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/DatasetRun' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + DeleteDatasetRunResponse: + title: DeleteDatasetRunResponse + type: object + properties: + message: + type: string + required: + - message + EvaluatorType: + title: EvaluatorType + type: string + enum: + - llm_as_judge + - code + description: |- + The evaluator type. + + The public API supports LLM-as-a-judge and code evaluators. + CodeEvaluatorSourceCodeLanguage: + title: CodeEvaluatorSourceCodeLanguage + type: string + enum: + - PYTHON + - TYPESCRIPT + description: Code evaluator runtime language. + PromptVariableMappingSource: + title: PromptVariableMappingSource + type: string + enum: + - input + - output + - metadata + - tool_calls + - expected_output + - experiment_item_metadata + description: >- + Source field used to populate a prompt variable. + + + Use these values when mapping evaluator prompt variables to live data. + + + Source semantics: + + - `input`: the observation input payload + + - `output`: the observation output payload + + - `metadata`: the observation metadata object. Combine with `jsonPath` + when you need one nested field instead of the whole object. + + - `tool_calls`: the tool calls recorded on the observation, as an array + of `{id, name, arguments, type, index}` objects in the order the model + emitted them. Combine with `jsonPath` (for example `$[*].name`) to + select parts of each call. + + - `expected_output`: the experiment item's expected output when the + observation belongs to an experiment. + + - `experiment_item_metadata`: the experiment item's metadata when the + observation belongs to an experiment. + EvaluatorOutputScoreType: + title: EvaluatorOutputScoreType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + description: >- + Structured score type returned by an evaluator. + + + This controls the type of score value Langfuse stores for evaluation + results: + + - `NUMERIC`: a numeric score such as `0.82` + + - `BOOLEAN`: a boolean score such as `true` + + - `CATEGORICAL`: one or more category labels from a fixed list + EvaluatorOutputDefinition: + title: EvaluatorOutputDefinition + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/PublicEvaluatorNumericScore' + required: + - dataType + title: PublicEvaluatorNumericScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/PublicEvaluatorBooleanScore' + required: + - dataType + title: PublicEvaluatorBooleanScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore' + required: + - dataType + title: PublicEvaluatorCategoricalScore + description: >- + Flat structured output definition used when creating or updating an + evaluator. + + + - `dataType` is required. + + - `scoreReasoningInstructions` and `scoreValueInstructions` are optional + instructions. + + - `minValue` and `maxValue` apply only to `NUMERIC` outputs. If both are + set, `minValue` must not exceed `maxValue`. + + - `categories` and `shouldAllowMultipleMatches` apply only to + `CATEGORICAL` outputs. + + - Do not send `version`; that is an internal storage detail. + EvaluatorOutputDefinitionBase: + title: EvaluatorOutputDefinitionBase + type: object + properties: + scoreReasoningInstructions: + type: string + nullable: true + description: >- + Optional instructions for deriving the reasoning returned with the + score. + scoreValueInstructions: + type: string + nullable: true + description: Optional instructions for deriving the score value. + PublicEvaluatorNumericScore: + title: PublicEvaluatorNumericScore + type: object + properties: + dataType: + type: string + const: NUMERIC + description: Numeric score output. + minValue: + type: number + format: double + nullable: true + description: Optional inclusive minimum value. + maxValue: + type: number + format: double + nullable: true + description: Optional inclusive maximum value. + required: + - dataType + allOf: + - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase' + PublicEvaluatorBooleanScore: + title: PublicEvaluatorBooleanScore + type: object + properties: + dataType: + type: string + const: BOOLEAN + description: Boolean score output. + required: + - dataType + allOf: + - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase' + PublicEvaluatorCategoricalScore: + title: PublicEvaluatorCategoricalScore + type: object + properties: + dataType: + type: string + const: CATEGORICAL + description: Categorical score output. + categories: + type: array + items: + type: string + description: Allowed category values. At least two unique values are required. + shouldAllowMultipleMatches: + type: boolean + description: Whether the evaluator may return more than one category. + required: + - dataType + - categories + - shouldAllowMultipleMatches + allOf: + - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase' + PublicEvaluatorOutputDefinition: + title: PublicEvaluatorOutputDefinition + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/PublicEvaluatorNumericScore' + required: + - dataType + title: PublicEvaluatorNumericScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/PublicEvaluatorBooleanScore' + required: + - dataType + title: PublicEvaluatorBooleanScore + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore' + required: + - dataType + title: PublicEvaluatorCategoricalScore + description: >- + Flat evaluator output definition returned by the public API. + + + This response always includes `dataType` and never includes an internal + output-definition `version`. + + Optional empty descriptions from legacy definitions are omitted. + EvaluationRuleStringFilterOperator: + title: EvaluationRuleStringFilterOperator + type: string + enum: + - '=' + - contains + - does not contain + - starts with + - ends with + EvaluationRuleNumberFilterOperator: + title: EvaluationRuleNumberFilterOperator + type: string + enum: + - '=' + - '>' + - < + - '>=' + - <= + EvaluationRuleOptionsFilterOperator: + title: EvaluationRuleOptionsFilterOperator + type: string + enum: + - any of + - none of + EvaluationRuleArrayOptionsFilterOperator: + title: EvaluationRuleArrayOptionsFilterOperator + type: string + enum: + - any of + - none of + - all of + EvaluationRuleBooleanFilterOperator: + title: EvaluationRuleBooleanFilterOperator + type: string + enum: + - '=' + - <> + EvaluationRuleNullFilterOperator: + title: EvaluationRuleNullFilterOperator + type: string + enum: + - is null + - is not null + DateTimeEvaluationRuleFilter: + title: DateTimeEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator' + description: Comparison operator for datetime values. + value: + type: string + format: date-time + description: Datetime value to compare against. + required: + - column + - operator + - value + StringEvaluationRuleFilter: + title: StringEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleStringFilterOperator' + value: + type: string + required: + - column + - operator + - value + NumberEvaluationRuleFilter: + title: NumberEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator' + value: + type: number + format: double + required: + - column + - operator + - value + StringOptionsEvaluationRuleFilter: + title: StringOptionsEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator' + value: + type: array + items: + type: string + description: One or more allowed string values. + required: + - column + - operator + - value + ArrayOptionsEvaluationRuleFilter: + title: ArrayOptionsEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleArrayOptionsFilterOperator' + value: + type: array + items: + type: string + description: One or more array elements to match. + required: + - column + - operator + - value + StringObjectEvaluationRuleFilter: + title: StringObjectEvaluationRuleFilter + type: object + properties: + column: + type: string + description: >- + Object-valued column to filter on. Currently only `metadata` is + supported. + key: + type: string + description: Top-level key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleStringFilterOperator' + value: + type: string + required: + - column + - key + - operator + - value + NumberObjectEvaluationRuleFilter: + title: NumberObjectEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Object-valued column to filter on. + key: + type: string + description: Key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator' + value: + type: number + format: double + required: + - column + - key + - operator + - value + CategoryOptionsEvaluationRuleFilter: + title: CategoryOptionsEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Object-valued column to filter on. + key: + type: string + description: Key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator' + value: + type: array + items: + type: string + required: + - column + - key + - operator + - value + BooleanEvaluationRuleFilter: + title: BooleanEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/EvaluationRuleBooleanFilterOperator' + value: + type: boolean + required: + - column + - operator + - value + NullEvaluationRuleFilter: + title: NullEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on, for example `parentObservationId`. + operator: + $ref: '#/components/schemas/EvaluationRuleNullFilterOperator' + value: + type: string + const: '' + description: >- + Required empty-string placeholder used by the runtime filter + contract. + required: + - column + - operator + - value + PromptVariableMappingInput: + title: PromptVariableMappingInput + type: object + description: >- + Connects one prompt variable to data from an observation or experiment. + + + Manual mappings are used for `llm_as_judge` evaluators. `code` + evaluators use a fixed runtime mapping managed by Langfuse. + + + How to build a valid mapping list: + + 1. Create the evaluator or fetch it with `GET /evaluators/{id}`. + + 2. Read the evaluator `variables` array. + + 3. Add exactly one mapping object for each variable in that array. + + 4. Use the variable name exactly as returned, without braces such as + `{{` or `}}`. + + 5. Choose the source field that should populate the variable. + + + `jsonPath` is optional. Use it only when the selected source is a JSON + object and you want to extract one nested field before inserting it into + the evaluator prompt. + + + Invalid, missing, or duplicate mappings return a validation error. + Malformed JSONPath expressions are also rejected. + properties: + variable: + type: string + description: >- + Prompt variable name without braces. + + + Example: for the prompt `Judge {{input}} against {{output}}`, use + `input` and `output`. + source: + $ref: '#/components/schemas/PromptVariableMappingSource' + description: >- + Source field that should populate the prompt variable. + + + Available sources are `input`, `output`, `metadata`, `tool_calls`, + `expected_output`, and `experiment_item_metadata`. + jsonPath: + type: string + nullable: true + description: >- + Optional JSONPath selector applied to the selected source before it + is passed to the evaluator prompt. + + + Requirements: + + - Must start with `$` + + - Must be a syntactically valid JSONPath expression + + - Most useful with `source=metadata` + required: + - variable + - source + PromptVariableMappingRead: + title: PromptVariableMappingRead + type: object + description: |- + Connects one prompt variable to source data. + + `source` is `null` when the mapping is incomplete. + properties: + variable: + type: string + description: Prompt variable name without braces. + source: + type: string + nullable: true + description: >- + Stored source field populating the variable, or `null` when the + mapping is incomplete. + jsonPath: + type: string + nullable: true + description: Optional JSONPath selector applied to the selected source. + required: + - variable + - source + PromptVariableMapping: + title: PromptVariableMapping + oneOf: + - $ref: '#/components/schemas/PromptVariableMappingRead' + - $ref: '#/components/schemas/LegacyPromptVariableMapping' + description: Connects one prompt variable to source data. + LegacyPromptVariableMapping: + title: LegacyPromptVariableMapping + type: object + description: >- + **Deprecated:** Connects one prompt variable to data from a legacy trace + or dataset evaluation rule. + + + `langfuseObject` selects the object kind. `objectName` separately + selects a named observation and is `null` for trace and dataset-item + mappings. + properties: + mappingType: + type: string + const: legacy + description: Explicitly marks this as a legacy mapping. + variable: + type: string + description: Prompt variable name without braces. + langfuseObject: + $ref: '#/components/schemas/LegacyEvaluationObject' + description: Legacy object kind selected as the mapping source. + objectName: + type: string + nullable: true + description: >- + Observation name to match, or `null` when `langfuseObject` is + `trace` or `dataset_item`. + source: + type: string + description: Field selected from the legacy object. + jsonPath: + type: string + nullable: true + description: Optional JSONPath selector applied to the selected field. + required: + - mappingType + - variable + - langfuseObject + - objectName + - source + LegacyEvaluationObject: + title: LegacyEvaluationObject + type: string + enum: + - trace + - span + - generation + - event + - agent + - tool + - chain + - retriever + - evaluator + - embedding + - guardrail + - dataset_item + description: >- + **Deprecated:** Legacy Langfuse object kind used by trace and dataset + evaluation rules. + EvaluationRuleFilter: + title: EvaluationRuleFilter + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - datetime + - $ref: '#/components/schemas/DateTimeEvaluationRuleFilter' + required: + - type + title: DateTimeEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - string + - $ref: '#/components/schemas/StringEvaluationRuleFilter' + required: + - type + title: StringEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - number + - $ref: '#/components/schemas/NumberEvaluationRuleFilter' + required: + - type + title: NumberEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - stringOptions + - $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter' + required: + - type + title: StringOptionsEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - categoryOptions + - $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter' + required: + - type + title: CategoryOptionsEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - arrayOptions + - $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter' + required: + - type + title: ArrayOptionsEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - stringObject + - $ref: '#/components/schemas/StringObjectEvaluationRuleFilter' + required: + - type + title: StringObjectEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - numberObject + - $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter' + required: + - type + title: NumberObjectEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - boolean + - $ref: '#/components/schemas/BooleanEvaluationRuleFilter' + required: + - type + title: BooleanEvaluationRuleFilter + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - 'null' + - $ref: '#/components/schemas/NullEvaluationRuleFilter' + required: + - type + title: NullEvaluationRuleFilter + description: >- + One filter condition used to decide whether a live-ingested observation + should be evaluated. + + + All filters must be satisfied for the rule to run. Experiment scope is + expressed with filters rather than a separate target field: + + - `isExperimentItemRootSpan = true` limits execution to experiment item + roots. + + - `datasetId` limits execution to experiments for the selected datasets. + Use dataset IDs from `GET /api/public/v2/datasets`. + + + Pick the filter `type` first, as it determines the required fields and + value shape. Use `key` only for object filters such as `metadata`. + + + Operator quick reference by filter `type`: + + - `string`: `"="`, `contains`, `does not contain`, `starts with`, `ends + with` + + - `number`: `"="`, `">"`, `"<"`, `">="`, `"<="` + + - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="` + + - `stringOptions`: `any of`, `none of` + + - `arrayOptions`: `any of`, `none of`, `all of` + + - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`, + `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key + presence; an empty value for `contains`, `starts with`, or `ends with` + is treated as `is set`) + + - `boolean`: `"="`, `"<>"` + + - `null`: `is null`, `is not null` + + + Supported columns. Each column accepts exactly one filter `type`; + sending a column with a different `type` is rejected with `400`. + + - `type`: `stringOptions`, values `SPAN`, `EVENT`, `GENERATION`, + `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`, + `GUARDRAIL` + + - `name`: `stringOptions` + + - `environment`: `stringOptions` + + - `level`: `stringOptions`, values `DEBUG`, `DEFAULT`, `WARNING`, + `ERROR` + + - `version`: `string` + + - `traceName`: `stringOptions` + + - `userId`: `string` + + - `sessionId`: `string` + + - `tags`: `arrayOptions` + + - `metadata`: `stringObject`, requires `key` + + - `isRootObservation`: `boolean`; true when the observation has no + parent or is explicitly marked as an application root + + - `parentObservationId`: `null` + + - `experimentId`: `stringOptions` + + - `isExperimentItemRootSpan`: `boolean` + + - `calledToolNames`: `arrayOptions` + + - `toolCalls`: `number`, the number of tool calls on the observation + + - `datasetId`: `stringOptions`. Use dataset `id` values from `GET + /api/public/v2/datasets`, not dataset names. + EvaluationRuleReadFilterBase: + title: EvaluationRuleReadFilterBase + type: object + description: Stored filter returned verbatim by evaluation-rule read endpoints. + properties: + type: + type: string + description: >- + Stored filter type. This is not broken down into separate public + response types. + column: + type: string + operator: + type: string + value: + nullable: true + description: Stored filter value. Its shape depends on the filter type. + required: + - type + - column + - operator + EvaluationRuleReadFilterWithKey: + title: EvaluationRuleReadFilterWithKey + type: object + properties: + key: + type: string + description: Stored object or legacy filter key. + required: + - key + allOf: + - $ref: '#/components/schemas/EvaluationRuleReadFilterBase' + EvaluationRuleReadFilter: + title: EvaluationRuleReadFilter + oneOf: + - $ref: '#/components/schemas/EvaluationRuleReadFilterWithKey' + - $ref: '#/components/schemas/EvaluationRuleReadFilterBase' + description: >- + Filter returned verbatim by evaluation-rule read endpoints. + + + Filters with a stored `key` use the keyed shape. All other filters use + the base shape. Response filters are intentionally not broken down by + their internal `type` value. + PublicApiErrorCode: + title: PublicApiErrorCode + type: string + enum: + - authentication_failed + - access_denied + - invalid_request + - invalid_query + - invalid_body + - resource_not_found + - conflict + - rate_limited + - method_not_allowed + - internal_error + description: >- + Stable machine-readable error code returned by the evaluators and + evaluation-rules API. + PublicApiValidationIssue: + title: PublicApiValidationIssue + type: object + description: One request validation issue. + properties: + code: + type: string + description: Validator issue code. + message: + type: string + description: Human-readable explanation. + path: + type: array + items: {} + description: Path to the invalid request field. + required: + - code + - message + - path + PublicApiErrorDetails: + title: PublicApiErrorDetails + type: object + description: Optional structured context for validation and rate-limit errors. + properties: + issues: + type: array + items: + $ref: '#/components/schemas/PublicApiValidationIssue' + nullable: true + description: Validation issues for an invalid request body or query. + retryAfterSeconds: + type: integer + nullable: true + description: Number of seconds to wait before retrying a rate-limited request. + limit: + type: integer + nullable: true + description: Rate-limit request allowance. + remaining: + type: integer + nullable: true + description: Remaining requests in the current rate-limit window. + resetAt: + type: string + format: date-time + nullable: true + description: Time when the current rate-limit window resets. + PublicApiError: + title: PublicApiError + type: object + description: >- + Standard error response for the stable evaluators and evaluation-rules + API. + + + Use the HTTP status for the broad failure class and `code` for + programmatic handling. `details` is included when field-level validation + or retry information is available. + properties: + message: + type: string + description: Human-readable description of the failure. + code: + $ref: '#/components/schemas/PublicApiErrorCode' + description: Stable machine-readable error code. + details: + $ref: '#/components/schemas/PublicApiErrorDetails' + nullable: true + description: Optional structured validation or rate-limit context. + required: + - message + - code + EvaluationRuleEvaluatorAssignmentInput: + title: EvaluationRuleEvaluatorAssignmentInput + type: object + properties: + evaluatorId: + type: string + description: >- + Stable evaluator identifier. The rule automatically uses that + evaluator's latest version. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMappingInput' + nullable: true + description: >- + Rule-specific prompt-variable mapping. + + + Set to `null` or omit to inherit the evaluator's latest default + mapping. Code evaluators use the fixed runtime mapping and should + use `null`. + required: + - evaluatorId + EvaluatorAssignment: + title: EvaluatorAssignment + type: object + properties: + evaluatorId: + type: string + description: Stable identifier of the evaluator associated with this rule. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMapping' + nullable: true + description: >- + Stored rule-specific override, or `null` when the evaluator's latest + default mapping is inherited. Legacy mappings are returned as an + explicit `legacy` variant. + required: + - evaluatorId + - variableMapping + EvaluationRule: + title: EvaluationRule + type: object + description: >- + Live evaluation rule for incoming observations. + + + A rule determines which evaluators should be used, which observations + should trigger scoring, how often scoring should run, and which + observation fields should populate prompt variables. + properties: + id: + type: string + description: Stable evaluation-rule identifier. + name: + type: string + description: >- + Human-readable rule name. This is independent from evaluator names + and does not need to be unique. + createdBy: + $ref: '#/components/schemas/Creator' + nullable: true + description: User who created this rule, or `null` when no user can be resolved. + enabled: + type: boolean + description: Whether live execution is enabled for this rule. + sampling: + type: number + format: double + description: |- + Fraction of matching observations that should be evaluated. + + Must be between `0` and `1`. + - `1` evaluates every matching observation. + - `0.25` evaluates approximately 25% of matching observations. + filter: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleReadFilter' + description: >- + List of stored filter conditions returned verbatim. Filters with a + `key` use the keyed response shape; all others use the base shape. + These response shapes are not broken down by internal filter type. + An empty list matches every incoming object. + evaluatorAssignments: + type: array + items: + $ref: '#/components/schemas/EvaluatorAssignment' + description: Evaluators attached to this rule in deterministic assignment order. + createdAt: + type: string + format: date-time + description: Timestamp when the evaluation rule was created. + updatedAt: + type: string + format: date-time + description: Timestamp when the evaluation rule was last updated. + required: + - id + - name + - createdBy + - enabled + - sampling + - filter + - evaluatorAssignments + - createdAt + - updatedAt + CreateEvaluationRuleRequest: + title: CreateEvaluationRuleRequest + type: object + properties: + name: + type: string + description: >- + Human-readable rule name. Names are not identifiers and do not need + to be unique. + enabled: + type: boolean + description: >- + Whether live execution should start immediately. Enabled rules + require at least one evaluator assignment. + sampling: + type: number + format: double + nullable: true + description: >- + Fraction of matching observations to evaluate. Omit this field to + use the default of `1`, which evaluates every match. `null` is not + accepted. + filter: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleFilter' + nullable: true + description: >- + Conditions used to select observations. Defaults to an empty list, + which matches every incoming observation. + evaluatorAssignments: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput' + description: >- + Evaluators to attach to this rule. Disabled rules may use an empty + list as a draft. + required: + - name + - enabled + - evaluatorAssignments + UpdateEvaluationRuleRequest: + title: UpdateEvaluationRuleRequest + type: object + description: At least one field must be provided. + properties: + name: + type: string + nullable: true + description: New human-readable rule name. + enabled: + type: boolean + nullable: true + description: New desired live-execution state. + sampling: + type: number + format: double + nullable: true + description: >- + New fraction of matching observations to evaluate. Omit to keep the + current value. + filter: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleFilter' + nullable: true + description: >- + Complete replacement filter list. An empty list matches every + incoming observation. + evaluatorAssignments: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput' + nullable: true + description: >- + Complete replacement assignment list. An empty list disables the + rule. + EvaluationRulesPage: + title: EvaluationRulesPage + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/EvaluationRule' + description: Evaluation rules for this page. + meta: + $ref: '#/components/schemas/CursorMeta' + description: Cursor pagination metadata. + required: + - data + - meta + DeletedEvaluationRule: + title: DeletedEvaluationRule + type: object + description: Confirmation returned after successful evaluation-rule deletion. + properties: + id: + type: string + description: Identifier of the deleted evaluation rule. + required: + - id + Creator: + title: Creator + type: object + description: User who created the resource, or `null` when no user can be resolved. + properties: + id: + type: string + description: User identifier. + name: + type: string + nullable: true + description: User name, or `null` when unavailable. + required: + - id + - name + EvaluatorModelConfig: + title: EvaluatorModelConfig + type: object + description: >- + Explicit model configuration for an evaluator. + + + If the complete `modelConfig` is `null`, Langfuse uses the project's + default evaluation model. + + If provided, the model must be available to the project when the + evaluator or evaluation rule is enabled. + properties: + provider: + type: string + description: >- + Provider identifier, for example `openai` or `anthropic`. + + + To discover valid values for the current project, call `GET + /api/public/llm-connections` and use one of the returned `provider` + values. + model: + type: string + description: >- + Model identifier exposed by the provider, for example `gpt-4.1-mini`. + required: + - provider + - model + EvaluatorChatMessageRole: + title: EvaluatorChatMessageRole + type: string + enum: + - system + - user + - assistant + description: Role of an evaluator prompt message. + EvaluatorChatMessage: + title: EvaluatorChatMessage + type: object + description: One chat message in an evaluator prompt. + properties: + role: + $ref: '#/components/schemas/EvaluatorChatMessageRole' + content: + type: string + description: Message content. Evaluator variables use `{{variable}}` syntax. + required: + - role + - content + EvaluatorChatPrompt: + title: EvaluatorChatPrompt + type: array + items: + $ref: '#/components/schemas/EvaluatorChatMessage' + description: >- + An ordered list of chat messages. A system message is only allowed as + the first message. + EvaluatorChatPromptInput: + title: EvaluatorChatPromptInput + oneOf: + - type: string + title: String + - $ref: '#/components/schemas/EvaluatorChatPrompt' + description: A user prompt string shortcut, or an ordered list of chat messages. + EvaluatorVersionBase: + title: EvaluatorVersionBase + type: object + properties: + id: + type: string + description: Stable identifier of this evaluator version. + version: + type: integer + description: Monotonically increasing evaluator version number. + createdAt: + type: string + format: date-time + description: Timestamp when this evaluator version was created. + createdBy: + $ref: '#/components/schemas/Creator' + nullable: true + description: >- + User who created this version, or `null` when no user can be + resolved. + required: + - id + - version + - createdAt + - createdBy + LlmAsJudgeEvaluatorVersion: + title: LlmAsJudgeEvaluatorVersion + type: object + properties: + type: + type: string + const: llm_as_judge + description: Evaluator type. + prompt: + $ref: '#/components/schemas/EvaluatorChatPrompt' + description: Ordered chat messages used during evaluation. + variables: + type: array + items: + type: string + description: >- + Variables extracted from the prompt and available for + evaluation-rule mappings. + + + Every variable must be mapped exactly once when a rule provides an + explicit mapping. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMappingRead' + nullable: true + description: >- + Default variable mapping for this evaluator version, or `null` when + no default is configured. + modelConfig: + $ref: '#/components/schemas/EvaluatorModelConfig' + nullable: true + description: >- + Explicit model configuration, or `null` when the project's default + evaluation model is used. + outputDefinition: + $ref: '#/components/schemas/PublicEvaluatorOutputDefinition' + description: >- + Structured output schema returned by this evaluator. + + + Responses include `dataType` and omit the internal output-definition + persistence version. + required: + - type + - prompt + - variables + - variableMapping + - modelConfig + - outputDefinition + allOf: + - $ref: '#/components/schemas/EvaluatorVersionBase' + CodeEvaluatorVersion: + title: CodeEvaluatorVersion + type: object + properties: + type: + type: string + const: code + description: Evaluator type. + sourceCode: + type: string + description: Source code executed for each matched observation. + sourceCodeLanguage: + $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage' + description: Runtime language used to execute the source code. + required: + - type + - sourceCode + - sourceCodeLanguage + allOf: + - $ref: '#/components/schemas/EvaluatorVersionBase' + EvaluatorVersion: + title: EvaluatorVersion + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - llm_as_judge + - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion' + required: + - type + title: LlmAsJudgeEvaluatorVersion + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - code + - $ref: '#/components/schemas/CodeEvaluatorVersion' + required: + - type + title: CodeEvaluatorVersion + EvaluationRuleAssignment: + title: EvaluationRuleAssignment + type: object + description: Evaluation-rule assignment associated with this evaluator. + properties: + evaluationRuleId: + type: string + description: Stable identifier of the assigned evaluation rule. + variableMappingOverride: + type: array + items: + $ref: '#/components/schemas/PromptVariableMapping' + nullable: true + description: >- + Rule-specific variable mapping override. Omitted when the + evaluator's latest default mapping is inherited. Legacy mappings use + the explicit `legacy` variant. + required: + - evaluationRuleId + EvaluatorBase: + title: EvaluatorBase + type: object + properties: + id: + type: string + description: Stable identifier of this evaluator across all versions. + name: + type: string + description: >- + Human-readable evaluator name. Names are not identifiers and do not + need to be unique. + description: + type: string + nullable: true + description: Optional human-readable evaluator description. + createdBy: + $ref: '#/components/schemas/Creator' + nullable: true + description: >- + User who created this evaluator, or `null` when no user can be + resolved. + status: + $ref: '#/components/schemas/EvaluatorStatus' + description: >- + Effective evaluator status after Langfuse validates its runtime + configuration. + pausedAt: + type: string + format: date-time + nullable: true + description: Timestamp when the evaluator was paused, otherwise `null`. + pausedReason: + type: string + nullable: true + description: Machine-readable reason when `status=paused`, otherwise `null`. + pausedMessage: + type: string + nullable: true + description: Human-readable explanation when `status=paused`, otherwise `null`. + evaluationRuleAssignments: + type: array + items: + $ref: '#/components/schemas/EvaluationRuleAssignment' + description: >- + All modern and legacy evaluation-rule assignments in + newest-assignment-first order. Rule-specific mappings are exposed as + `variableMappingOverride`; inherited defaults are omitted. + createdAt: + type: string + format: date-time + description: Timestamp when the evaluator was created. + updatedAt: + type: string + format: date-time + description: Timestamp when the evaluator was last updated. + versionId: + type: string + description: Stable identifier of the latest evaluator version. + version: + type: integer + description: Monotonically increasing latest evaluator version number. + versionCreatedAt: + type: string + format: date-time + description: Timestamp when the latest evaluator version was created. + versionCreatedBy: + $ref: '#/components/schemas/Creator' + nullable: true + description: >- + User who created the latest evaluator version, or `null` when no + user can be resolved. + required: + - id + - name + - description + - createdBy + - status + - pausedAt + - pausedReason + - pausedMessage + - evaluationRuleAssignments + - createdAt + - updatedAt + - versionId + - version + - versionCreatedAt + - versionCreatedBy + LlmAsJudgeEvaluator: + title: LlmAsJudgeEvaluator + type: object + properties: + type: + type: string + const: llm_as_judge + description: Evaluator type. + prompt: + $ref: '#/components/schemas/EvaluatorChatPrompt' + description: Ordered chat messages used by the latest evaluator version. + variables: + type: array + items: + type: string + description: >- + Variables extracted from the latest prompt and available for + evaluation-rule mappings. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMappingRead' + nullable: true + description: >- + Default variable mapping for the latest version, or `null` when no + default is configured. + modelConfig: + $ref: '#/components/schemas/EvaluatorModelConfig' + nullable: true + description: >- + Explicit model configuration for the latest version, or `null` when + the project's default evaluation model is used. + outputDefinition: + $ref: '#/components/schemas/PublicEvaluatorOutputDefinition' + description: Structured output schema returned by the latest evaluator version. + required: + - type + - prompt + - variables + - variableMapping + - modelConfig + - outputDefinition + allOf: + - $ref: '#/components/schemas/EvaluatorBase' + CodeEvaluator: + title: CodeEvaluator + type: object + properties: + type: + type: string + const: code + description: Evaluator type. + sourceCode: + type: string + description: Source code executed by the latest evaluator version. + sourceCodeLanguage: + $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage' + description: Runtime language used to execute the latest source code. + required: + - type + - sourceCode + - sourceCodeLanguage + allOf: + - $ref: '#/components/schemas/EvaluatorBase' + Evaluator: + title: Evaluator + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - llm_as_judge + - $ref: '#/components/schemas/LlmAsJudgeEvaluator' + required: + - type + title: LlmAsJudgeEvaluator + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - code + - $ref: '#/components/schemas/CodeEvaluator' + required: + - type + title: CodeEvaluator + description: >- + One evaluator that can be used for scoring. + + + An evaluator describes **how** to score data. Associated evaluation + rules describe **which** live objects should be evaluated. + EvaluatorStatus: + title: EvaluatorStatus + type: string + enum: + - active + - paused + description: >- + Effective evaluator runtime status. + + + - `active`: the evaluator can run. + + - `paused`: Langfuse paused execution until the underlying issue is + resolved. + CreateLlmAsJudgeEvaluatorRequest: + title: CreateLlmAsJudgeEvaluatorRequest + type: object + properties: + name: + type: string + description: >- + Human-readable evaluator name. Names are not identifiers and do not + need to be unique. + description: + type: string + nullable: true + description: Optional human-readable evaluator description. + type: + type: string + const: llm_as_judge + description: Evaluator type. + prompt: + $ref: '#/components/schemas/EvaluatorChatPromptInput' + description: User prompt string shortcut or an ordered list of chat messages. + modelConfig: + $ref: '#/components/schemas/EvaluatorModelConfig' + nullable: true + description: >- + Explicit model configuration. Set to `null` or omit to use the + project's default evaluation model. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMappingInput' + nullable: true + description: >- + Default prompt-variable mapping, or `null` when no default is + configured. + outputDefinition: + $ref: '#/components/schemas/EvaluatorOutputDefinition' + description: >- + Structured output schema returned by this evaluator. Do not include + an internal persistence version. + required: + - name + - type + - prompt + - outputDefinition + CreateCodeEvaluatorRequest: + title: CreateCodeEvaluatorRequest + type: object + properties: + name: + type: string + description: >- + Human-readable evaluator name. Names are not identifiers and do not + need to be unique. + description: + type: string + nullable: true + description: Optional human-readable evaluator description. + type: + type: string + const: code + description: Evaluator type. + sourceCode: + type: string + description: Source code executed for each matched observation. + sourceCodeLanguage: + $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage' + description: Runtime language used to execute the source code. + required: + - name + - type + - sourceCode + - sourceCodeLanguage + CreateEvaluatorRequest: + title: CreateEvaluatorRequest + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - llm_as_judge + - $ref: '#/components/schemas/CreateLlmAsJudgeEvaluatorRequest' + required: + - type + title: CreateLlmAsJudgeEvaluatorRequest + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - code + - $ref: '#/components/schemas/CreateCodeEvaluatorRequest' + required: + - type + title: CreateCodeEvaluatorRequest + description: >- + Initial evaluator definition with metadata and definition fields at the + same level. The returned evaluator starts at version `1`. + UpdateEvaluatorMetadataRequest: + title: UpdateEvaluatorMetadataRequest + type: object + description: Metadata-only update. At least one field must be provided. + properties: + name: + type: string + nullable: true + description: New human-readable evaluator name. + description: + type: string + nullable: true + description: New description. Set to `null` to clear it. + UpdateLlmAsJudgeEvaluatorRequest: + title: UpdateLlmAsJudgeEvaluatorRequest + type: object + properties: + name: + type: string + nullable: true + description: New human-readable evaluator name. + description: + type: string + nullable: true + description: New description. Set to `null` to clear it. + type: + type: string + const: llm_as_judge + description: Evaluator type. The type of an existing evaluator cannot change. + prompt: + $ref: '#/components/schemas/EvaluatorChatPromptInput' + description: >- + Complete replacement user prompt string or an ordered list of chat + messages. + modelConfig: + $ref: '#/components/schemas/EvaluatorModelConfig' + nullable: true + description: >- + Explicit model configuration. Set to `null` or omit to use the + project's default evaluation model. + variableMapping: + type: array + items: + $ref: '#/components/schemas/PromptVariableMappingInput' + nullable: true + description: >- + Complete replacement default variable mapping, or `null` when no + default is configured. + outputDefinition: + $ref: '#/components/schemas/EvaluatorOutputDefinition' + description: >- + Complete replacement output schema. Do not include an internal + persistence version. + required: + - type + - prompt + - outputDefinition + UpdateCodeEvaluatorRequest: + title: UpdateCodeEvaluatorRequest + type: object + properties: + name: + type: string + nullable: true + description: New human-readable evaluator name. + description: + type: string + nullable: true + description: New description. Set to `null` to clear it. + type: + type: string + const: code + description: Evaluator type. The type of an existing evaluator cannot change. + sourceCode: + type: string + description: Complete replacement source code. + sourceCodeLanguage: + $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage' + description: Runtime language used to execute the source code. + required: + - type + - sourceCode + - sourceCodeLanguage + UpdateEvaluatorRequest: + title: UpdateEvaluatorRequest + oneOf: + - $ref: '#/components/schemas/UpdateEvaluatorMetadataRequest' + - $ref: '#/components/schemas/UpdateLlmAsJudgeEvaluatorRequest' + - $ref: '#/components/schemas/UpdateCodeEvaluatorRequest' + description: >- + Metadata-only update or complete flattened definition replacement. At + least one field must be provided. + EvaluatorsPage: + title: EvaluatorsPage + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Evaluator' + description: Evaluators for this page. + meta: + $ref: '#/components/schemas/CursorMeta' + description: Cursor pagination metadata. + required: + - data + - meta + EvaluatorVersionsPage: + title: EvaluatorVersionsPage + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/EvaluatorVersion' + description: Evaluator versions for this page in newest-first order. + meta: + $ref: '#/components/schemas/CursorMeta' + description: Cursor pagination metadata. + required: + - data + - meta + CursorMeta: + title: CursorMeta + type: object + description: Cursor pagination metadata. + properties: {} + allOf: + - $ref: '#/components/schemas/utilsCursorMetaResponse' + DeletedEvaluator: + title: DeletedEvaluator + type: object + description: Confirmation returned after successful evaluator deletion. + properties: + id: + type: string + description: Identifier of the deleted evaluator. + required: + - id + ExperimentsResponse: + title: ExperimentsResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Experiment' + meta: + $ref: '#/components/schemas/ExperimentsResponseMeta' + required: + - data + - meta + ExperimentsResponseMeta: + title: ExperimentsResponseMeta + type: object + description: Metadata for cursor-based pagination. + properties: {} + allOf: + - $ref: '#/components/schemas/utilsCursorMetaResponse' + Experiment: + title: Experiment + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + nullable: true + startTime: + type: string + format: date-time + description: |- + Start of the experiment, i.e. the earliest event within the + requested time range. Clipped to `fromStartTime` when the + experiment started before the requested range. + endTime: + type: string + format: date-time + description: |- + End of the experiment, i.e. the latest event end within the + requested time range. + itemCount: + type: integer + description: Number of experiment items within the requested time range. + datasetId: + type: string + nullable: true + description: Null when the experiment is not associated with a dataset. + metadata: + type: object + additionalProperties: true + nullable: true + description: Included only when `fields=metadata` is requested. + scores: + type: array + items: + $ref: '#/components/schemas/ScoreV3' + nullable: true + description: >- + Included only when `fields=scores` is requested. Contains scores + directly attached to the experiment. + required: + - id + - name + - description + - startTime + - endTime + - itemCount + - datasetId + ExperimentItemsResponse: + title: ExperimentItemsResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ExperimentItem' + meta: + $ref: '#/components/schemas/ExperimentsResponseMeta' + required: + - data + - meta + ExperimentItem: + title: ExperimentItem + type: object + properties: + id: + type: string + traceId: + type: string + startTime: + type: string + format: date-time + endTime: + type: string + format: date-time + nullable: true + level: + $ref: '#/components/schemas/ObservationLevel' + environment: + type: string + experimentId: + type: string + experimentName: + type: string + experimentItemId: + type: string + experimentDatasetId: + type: string + nullable: true + description: Included when `fields=dataset` is requested. + experimentItemVersion: + type: string + format: date-time + nullable: true + description: Included when `fields=dataset` is requested. + input: + nullable: true + description: Included when `fields=io` is requested. + output: + nullable: true + description: Included when `fields=io` is requested. + expectedOutput: + nullable: true + description: Included when `fields=io` is requested. + metadata: + type: object + additionalProperties: true + nullable: true + description: Included when `fields=metadata` is requested. + experimentItemMetadata: + type: object + additionalProperties: true + nullable: true + description: Included when `fields=itemMetadata` is requested. + experimentMetadata: + type: object + additionalProperties: true + nullable: true + description: Included when `fields=experimentMetadata` is requested. + experimentDescription: + type: string + nullable: true + description: Included when `fields=experimentMetadata` is requested. + scores: + type: array + items: + $ref: '#/components/schemas/ScoreV3' + nullable: true + description: >- + Included only when `fields=scores` is requested. Contains item and + trace scores only; experiment-level scores are returned by the + experiments endpoint. + required: + - id + - traceId + - startTime + - endTime + - level + - environment + - experimentId + - experimentName + - experimentItemId + FeedbackTargetType: + title: FeedbackTargetType + type: string + enum: + - skill + - mcp-tool + - cli + - docs + - public-api + - other + SubmitFeedbackRequest: + title: SubmitFeedbackRequest + type: object + properties: + targetType: + $ref: '#/components/schemas/FeedbackTargetType' + description: Category of the thing the feedback is about. + target: + type: string + description: >- + The specific instance within targetType: the skill name, MCP tool + name, CLI command, API endpoint path, or docs page path (e.g. + 'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be + between 1 and 200 characters. + feedback: + type: string + description: >- + Concise feedback text approved by the user. Must be between 1 and + 3000 characters. + goal: + type: string + nullable: true + description: >- + Optional user-approved goal or use case they were trying to achieve. + Must be between 1 and 1500 characters when provided. Do not include + secrets, customer data, trace payloads, or broad unrelated context. + referenceUrl: + type: string + nullable: true + description: >- + Optional HTTP(S) reference URL. Langfuse stores it as text for + triage and does not fetch it. + required: + - targetType + - target + - feedback + SubmitFeedbackResponse: + title: SubmitFeedbackResponse + type: object + properties: + id: + type: string + description: Correlation ID for the submitted feedback. + required: + - id + HealthResponse: + title: HealthResponse + type: object + properties: + version: + type: string + description: Langfuse server version + status: + type: string + required: + - version + - status + IngestionEvent: + title: IngestionEvent + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - trace-create + - $ref: '#/components/schemas/TraceEvent' + required: + - type + title: TraceEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - score-create + - $ref: '#/components/schemas/ScoreEvent' + required: + - type + title: ScoreEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - span-create + - $ref: '#/components/schemas/CreateSpanEvent' + required: + - type + title: CreateSpanEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - span-update + - $ref: '#/components/schemas/UpdateSpanEvent' + required: + - type + title: UpdateSpanEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - generation-create + - $ref: '#/components/schemas/CreateGenerationEvent' + required: + - type + title: CreateGenerationEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - generation-update + - $ref: '#/components/schemas/UpdateGenerationEvent' + required: + - type + title: UpdateGenerationEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - event-create + - $ref: '#/components/schemas/CreateEventEvent' + required: + - type + title: CreateEventEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - observation-create + - $ref: '#/components/schemas/CreateObservationEvent' + required: + - type + title: CreateObservationEvent + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - observation-update + - $ref: '#/components/schemas/UpdateObservationEvent' + required: + - type + title: UpdateObservationEvent + ObservationType: + title: ObservationType + type: string + enum: + - SPAN + - GENERATION + - EVENT + - AGENT + - TOOL + - CHAIN + - RETRIEVER + - EVALUATOR + - EMBEDDING + - GUARDRAIL + IngestionUsage: + title: IngestionUsage + oneOf: + - $ref: '#/components/schemas/Usage' + - $ref: '#/components/schemas/OpenAIUsage' + OpenAIUsage: + title: OpenAIUsage + type: object + description: Usage interface of OpenAI for improved compatibility. + properties: + promptTokens: + type: integer + nullable: true + completionTokens: + type: integer + nullable: true + totalTokens: + type: integer + nullable: true + OptionalObservationBody: + title: OptionalObservationBody + type: object + properties: + traceId: + type: string + nullable: true + name: + type: string + nullable: true + startTime: + type: string + format: date-time + nullable: true + metadata: + nullable: true + input: + nullable: true + output: + nullable: true + level: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + statusMessage: + type: string + nullable: true + parentObservationId: + type: string + nullable: true + version: + type: string + nullable: true + environment: + type: string + nullable: true + CreateEventBody: + title: CreateEventBody + type: object + properties: + id: + type: string + nullable: true + allOf: + - $ref: '#/components/schemas/OptionalObservationBody' + UpdateEventBody: + title: UpdateEventBody + type: object + properties: + id: + type: string + required: + - id + allOf: + - $ref: '#/components/schemas/OptionalObservationBody' + CreateSpanBody: + title: CreateSpanBody + type: object + properties: + endTime: + type: string + format: date-time + nullable: true + allOf: + - $ref: '#/components/schemas/CreateEventBody' + UpdateSpanBody: + title: UpdateSpanBody + type: object + properties: + endTime: + type: string + format: date-time + nullable: true + allOf: + - $ref: '#/components/schemas/UpdateEventBody' + CreateGenerationBody: + title: CreateGenerationBody + type: object + properties: + completionStartTime: + type: string + format: date-time + nullable: true + model: + type: string + nullable: true + modelParameters: + type: object + additionalProperties: + $ref: '#/components/schemas/MapValue' + nullable: true + usage: + $ref: '#/components/schemas/IngestionUsage' + nullable: true + usageDetails: + $ref: '#/components/schemas/UsageDetails' + nullable: true + costDetails: + type: object + additionalProperties: + type: number + format: double + nullable: true + promptName: + type: string + nullable: true + promptVersion: + type: integer + nullable: true + allOf: + - $ref: '#/components/schemas/CreateSpanBody' + UpdateGenerationBody: + title: UpdateGenerationBody + type: object + properties: + completionStartTime: + type: string + format: date-time + nullable: true + model: + type: string + nullable: true + modelParameters: + type: object + additionalProperties: + $ref: '#/components/schemas/MapValue' + nullable: true + usage: + $ref: '#/components/schemas/IngestionUsage' + nullable: true + promptName: + type: string + nullable: true + usageDetails: + $ref: '#/components/schemas/UsageDetails' + nullable: true + costDetails: + type: object + additionalProperties: + type: number + format: double + nullable: true + promptVersion: + type: integer + nullable: true + allOf: + - $ref: '#/components/schemas/UpdateSpanBody' + ObservationBody: + title: ObservationBody + type: object + properties: + id: + type: string + nullable: true + traceId: + type: string + nullable: true + type: + $ref: '#/components/schemas/ObservationType' + name: + type: string + nullable: true + startTime: + type: string + format: date-time + nullable: true + endTime: + type: string + format: date-time + nullable: true + completionStartTime: + type: string + format: date-time + nullable: true + model: + type: string + nullable: true + modelParameters: + type: object + additionalProperties: + $ref: '#/components/schemas/MapValue' + nullable: true + input: + nullable: true + version: + type: string + nullable: true + metadata: + nullable: true + output: + nullable: true + usage: + $ref: '#/components/schemas/Usage' + nullable: true + level: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + statusMessage: + type: string + nullable: true + parentObservationId: + type: string + nullable: true + environment: + type: string + nullable: true + required: + - type + TraceBody: + title: TraceBody + type: object + properties: + id: + type: string + nullable: true + timestamp: + type: string + format: date-time + nullable: true + name: + type: string + nullable: true + userId: + type: string + nullable: true + input: + nullable: true + output: + nullable: true + sessionId: + type: string + nullable: true + release: + type: string + nullable: true + version: + type: string + nullable: true + metadata: + nullable: true + tags: + type: array + items: + type: string + nullable: true + environment: + type: string + nullable: true + public: + type: boolean + nullable: true + description: Make trace publicly accessible via url + ScoreBody: + title: ScoreBody + type: object + properties: + id: + type: string + nullable: true + traceId: + type: string + nullable: true + sessionId: + type: string + nullable: true + observationId: + type: string + nullable: true + datasetRunId: + type: string + nullable: true + name: + type: string + description: >- + The name of the score. Always overrides "output" for correction + scores. + environment: + type: string + nullable: true + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + value: + $ref: '#/components/schemas/CreateScoreValue' + description: >- + The value of the score. Must be passed as string for categorical and + text scores, and numeric for boolean and numeric scores. Boolean + score values must equal either 1 or 0 (true or false). Text score + values must be between 1 and 500 characters. + comment: + type: string + nullable: true + metadata: + nullable: true + dataType: + $ref: '#/components/schemas/ScoreDataType' + nullable: true + description: >- + When set, must match the score value's type. If not set, will be + inferred from the score value or config + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. When set, the score name must + equal the config name and scores must comply with the config's range + and data type. For categorical scores, the value must map to a + config category. Numeric scores might be constrained by the score + config's max and min values + required: + - name + - value + BaseEvent: + title: BaseEvent + type: object + properties: + id: + type: string + description: UUID v4 that identifies the event + timestamp: + type: string + description: >- + Datetime (ISO 8601) of event creation in client. Should be as close + to actual event creation in client as possible, this timestamp will + be used for ordering of events in future release. Resolution: + milliseconds (required), microseconds (optimal). + metadata: + nullable: true + description: Optional. Metadata field used by the Langfuse SDKs for debugging. + required: + - id + - timestamp + TraceEvent: + title: TraceEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/TraceBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateObservationEvent: + title: CreateObservationEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/ObservationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateObservationEvent: + title: UpdateObservationEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/ObservationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + ScoreEvent: + title: ScoreEvent + type: object + properties: + body: + $ref: '#/components/schemas/ScoreBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateGenerationEvent: + title: CreateGenerationEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/CreateGenerationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateGenerationEvent: + title: UpdateGenerationEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/UpdateGenerationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateSpanEvent: + title: CreateSpanEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/CreateSpanBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateSpanEvent: + title: UpdateSpanEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/UpdateSpanBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateEventEvent: + title: CreateEventEvent + type: object + description: >- + Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is + shut down on November 16, 2026, except for score events: from that date + it accepts only `score-create` events and rejects all other event types, + including this one. To write scores, prefer `POST /api/public/scores`; + see the [Scores API + docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api). + To write traces and observations, always prefer upgrading to the current + Python and JS SDKs. If you use custom auto-instrumentation, send them to + the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for + example with curl; see the [OpenTelemetry integration + docs](https://langfuse.com/integrations/native/opentelemetry). To read + data back, use the v4 read APIs; see the [Observations API + docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api) + and the [Metrics API + docs](https://langfuse.com/docs/metrics/features/metrics-api). The only + path to live data is OpenTelemetry ingestion combined with `GET + /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other + public APIs may have data delays of several minutes. + properties: + body: + $ref: '#/components/schemas/CreateEventBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + IngestionSuccess: + title: IngestionSuccess + type: object + properties: + id: + type: string + status: + type: integer + required: + - id + - status + IngestionError: + title: IngestionError + type: object + properties: + id: + type: string + status: + type: integer + message: + type: string + nullable: true + error: + nullable: true + required: + - id + - status + IngestionResponse: + title: IngestionResponse + type: object + properties: + successes: + type: array + items: + $ref: '#/components/schemas/IngestionSuccess' + errors: + type: array + items: + $ref: '#/components/schemas/IngestionError' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - successes + - errors + OpenAICompletionUsageSchema: + title: OpenAICompletionUsageSchema + type: object + description: OpenAI Usage schema from (Chat-)Completion APIs + properties: + prompt_tokens: + type: integer + completion_tokens: + type: integer + total_tokens: + type: integer + prompt_tokens_details: + type: object + additionalProperties: + type: integer + nullable: true + nullable: true + completion_tokens_details: + type: object + additionalProperties: + type: integer + nullable: true + nullable: true + required: + - prompt_tokens + - completion_tokens + - total_tokens + OpenAIResponseUsageSchema: + title: OpenAIResponseUsageSchema + type: object + description: OpenAI Usage schema from Response API + properties: + input_tokens: + type: integer + output_tokens: + type: integer + total_tokens: + type: integer + input_tokens_details: + type: object + additionalProperties: + type: integer + nullable: true + nullable: true + output_tokens_details: + type: object + additionalProperties: + type: integer + nullable: true + nullable: true + required: + - input_tokens + - output_tokens + - total_tokens + UsageDetails: + title: UsageDetails + oneOf: + - type: object + additionalProperties: + type: integer + title: Object + - $ref: '#/components/schemas/OpenAICompletionUsageSchema' + - $ref: '#/components/schemas/OpenAIResponseUsageSchema' + legacyMetricsResponse: + title: legacyMetricsResponse + type: object + properties: + data: + type: array + items: + type: object + additionalProperties: true + description: >- + The metrics data. Each item in the list contains the metric values + and dimensions requested in the query. + + Format varies based on the query parameters. + + Histograms will return an array with [lower, upper, height] tuples. + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + legacyObservations: + title: legacyObservations + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Observation' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + legacyObservationsViews: + title: legacyObservationsViews + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ObservationsView' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + LlmConnection: + title: LlmConnection + type: object + description: LLM API connection configuration (secrets excluded) + properties: + id: + type: string + provider: + type: string + description: >- + Provider name (e.g., 'openai', 'my-gateway'). Must be unique in + project, used for upserting. + adapter: + type: string + description: The adapter used to interface with the LLM + displaySecretKey: + type: string + description: Masked version of the secret key for display purposes + baseURL: + type: string + nullable: true + description: Custom base URL for the LLM API + customModels: + type: array + items: + type: string + description: List of custom model names available for this connection + withDefaultModels: + type: boolean + description: Whether to include default models for this adapter + extraHeaderKeys: + type: array + items: + type: string + description: >- + Keys of extra headers sent with requests (values excluded for + security) + config: + type: object + additionalProperties: true + nullable: true + description: >- + Adapter-specific configuration. Required for Bedrock + (`{"region":"us-east-1"}`), optional for OpenAI + (`{"useResponsesApi":true}`), optional for VertexAI + (`{"location":"us-central1"}`), not used by other adapters. + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - provider + - adapter + - displaySecretKey + - customModels + - withDefaultModels + - extraHeaderKeys + - createdAt + - updatedAt + PaginatedLlmConnections: + title: PaginatedLlmConnections + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LlmConnection' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + UpsertLlmConnectionRequest: + title: UpsertLlmConnectionRequest + type: object + description: Request to create or update an LLM connection (upsert) + properties: + provider: + type: string + description: >- + Provider name (e.g., 'openai', 'my-gateway'). Must be unique in + project, used for upserting. + adapter: + $ref: '#/components/schemas/LlmAdapter' + description: The adapter used to interface with the LLM + secretKey: + type: string + description: Secret key for the LLM API. + baseURL: + type: string + nullable: true + description: Custom base URL for the LLM API + customModels: + type: array + items: + type: string + nullable: true + description: List of custom model names + withDefaultModels: + type: boolean + nullable: true + description: Whether to include default models. Default is true. + extraHeaders: + type: object + additionalProperties: + type: string + nullable: true + description: Extra headers to send with requests + config: + type: object + additionalProperties: true + nullable: true + description: >- + Adapter-specific configuration. Validation rules: - **Bedrock**: + Required. Must be `{"region": ""}` (e.g., + `{"region":"us-east-1"}`) - **OpenAI**: Optional. If provided, must + be `{"useResponsesApi": }` to control whether Langfuse + routes calls through OpenAI's Responses API. - **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 + description: >- + Request a presigned media upload URL. Provide exactly one context: a + trace (traceId, optionally observationId) or a dataset item (datasetId + + datasetItemId). field is required and must match the chosen context. + properties: + traceId: + type: string + nullable: true + description: >- + The trace the media is associated with. Null for dataset item media + uploads. + observationId: + type: string + nullable: true + description: >- + The observation ID associated with the media record. If the media + record is associated directly with a trace, this will be null. + datasetId: + type: string + nullable: true + description: >- + The dataset the media belongs to. Null for trace/observation media + uploads. + datasetItemId: + type: string + nullable: true + description: >- + The dataset item the media is associated with (need not exist yet). + Null for trace/observation media uploads. + contentType: + $ref: '#/components/schemas/MediaContentType' + contentLength: + type: integer + description: The size of the media record in bytes + sha256Hash: + type: string + description: The SHA-256 hash of the media record + field: + type: string + description: >- + The item field the media is in: `input`/`output`/`metadata` (trace) + or `input`/`expectedOutput`/`metadata` (dataset item). + required: + - contentType + - contentLength + - sha256Hash + - field + GetMediaUploadUrlResponse: + title: GetMediaUploadUrlResponse + type: object + properties: + uploadUrl: + type: string + nullable: true + description: >- + The presigned upload URL. If the asset is already uploaded, this + will be null + mediaId: + type: string + description: The unique langfuse identifier of a media record + required: + - mediaId + MediaContentType: + title: MediaContentType + type: string + enum: + - image/png + - image/jpeg + - image/jpg + - image/webp + - image/gif + - image/svg+xml + - image/tiff + - image/bmp + - image/avif + - image/heic + - audio/mpeg + - audio/mp3 + - audio/wav + - audio/ogg + - audio/oga + - audio/aac + - audio/mp4 + - audio/flac + - audio/opus + - audio/webm + - video/mp4 + - video/webm + - video/ogg + - video/mpeg + - video/quicktime + - video/x-msvideo + - video/x-matroska + - text/plain + - text/html + - text/css + - text/csv + - text/markdown + - text/x-python + - application/javascript + - text/x-typescript + - application/x-yaml + - application/pdf + - application/msword + - application/vnd.ms-excel + - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet + - application/zip + - application/json + - application/xml + - application/octet-stream + - >- + application/vnd.openxmlformats-officedocument.wordprocessingml.document + - >- + application/vnd.openxmlformats-officedocument.presentationml.presentation + - application/rtf + - application/x-ndjson + - application/vnd.apache.parquet + - application/gzip + - application/x-tar + - application/x-7z-compressed + description: The MIME type of the media record + MetricsV2Response: + title: MetricsV2Response + type: object + properties: + data: + type: array + items: + type: object + additionalProperties: true + description: >- + The metrics data. Each item in the list contains the metric values + and dimensions requested in the query. + + Format varies based on the query parameters. + + Histograms will return an array with [lower, upper, height] tuples. + required: + - data + ModelTokenizerId: + title: ModelTokenizerId + type: string + enum: + - openai + - claude + description: Tokenizer supported by Langfuse for model usage inference. + PaginatedModels: + title: PaginatedModels + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Model' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateModelRequest: + title: CreateModelRequest + type: object + properties: + modelName: + type: string + description: >- + Name of the model definition. If multiple with the same name exist, + they are applied in the following order: (1) custom over built-in, + (2) newest according to startTime where + model.startTime- + Regex pattern which matches this model definition to + generation.model. Useful in case of fine-tuned models. If you want + to exact match, use `(?i)^modelname$` + startDate: + type: string + format: date-time + nullable: true + description: Apply only to generations which are newer than this ISO date. + unit: + $ref: '#/components/schemas/ModelUsageUnit' + description: Unit used by this model. + inputPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit. + Creates a default tier if pricingTiers not provided. + outputPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit. + Creates a default tier if pricingTiers not provided. + totalPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per total units. + Cannot be set if input or output price is set. Creates a default + tier if pricingTiers not provided. + pricingTiers: + type: array + items: + $ref: '#/components/schemas/PricingTierInput' + nullable: true + description: >- + Optional. Array of pricing tiers for this model. + + + Use pricing tiers for all models - both those with threshold-based + pricing variations and those with simple flat pricing: + + + - For models with standard flat pricing: Create a single default + tier with your prices + (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices) + + - For models with threshold-based pricing: Create a default tier + plus additional conditional tiers + (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds) + + Requirements: + + - Cannot be provided with flat prices + (inputPrice/outputPrice/totalPrice) - use one approach or the other + + - Must include exactly one default tier with isDefault=true, + priority=0, and conditions=[] + + - All tier names and priorities must be unique within the model + + - Each tier must define at least one price + + + If omitted, you must provide flat prices instead + (inputPrice/outputPrice/totalPrice), + + which will automatically create a single default tier named + "Standard". + tokenizerId: + $ref: '#/components/schemas/ModelTokenizerId' + nullable: true + description: >- + Optional. Tokenizer to be applied to observations which match to + this model. See docs for more details. + tokenizerConfig: + nullable: true + description: >- + Optional. Configuration for the selected tokenizer. Needs to be + JSON. See docs for more details. + required: + - modelName + - matchPattern + - unit + ObservationsV2Response: + title: ObservationsV2Response + type: object + description: >- + Response containing observations with field-group-based filtering and + cursor-based pagination. + + + The `data` array contains observation objects with only the requested + field groups included. + + Use the `cursor` in `meta` to retrieve the next page of results. + properties: + data: + type: array + items: + $ref: '#/components/schemas/ObservationV2' + description: >- + Array of observation objects. Fields included depend on the `fields` + parameter in the request. + meta: + $ref: '#/components/schemas/ObservationsV2Meta' + required: + - data + - meta + ObservationsV2Meta: + title: ObservationsV2Meta + type: object + description: Metadata for cursor-based pagination. + properties: {} + allOf: + - $ref: '#/components/schemas/utilsCursorMetaResponse' + OtelResourceSpan: + title: OtelResourceSpan + type: object + description: >- + Represents a collection of spans from a single resource as per OTLP + specification + properties: + resource: + $ref: '#/components/schemas/OtelResource' + nullable: true + description: Resource information + scopeSpans: + type: array + items: + $ref: '#/components/schemas/OtelScopeSpan' + nullable: true + description: Array of scope spans + OtelResource: + title: OtelResource + type: object + description: Resource attributes identifying the source of telemetry + properties: + attributes: + type: array + items: + $ref: '#/components/schemas/OtelAttribute' + nullable: true + description: Resource attributes like service.name, service.version, etc. + OtelScopeSpan: + title: OtelScopeSpan + type: object + description: Collection of spans from a single instrumentation scope + properties: + scope: + $ref: '#/components/schemas/OtelScope' + nullable: true + description: Instrumentation scope information + spans: + type: array + items: + $ref: '#/components/schemas/OtelSpan' + nullable: true + description: Array of spans + OtelScope: + title: OtelScope + type: object + description: Instrumentation scope information + properties: + name: + type: string + nullable: true + description: Instrumentation scope name + version: + type: string + nullable: true + description: Instrumentation scope version + attributes: + type: array + items: + $ref: '#/components/schemas/OtelAttribute' + nullable: true + description: Additional scope attributes + OtelSpan: + title: OtelSpan + type: object + description: Individual span representing a unit of work or operation + properties: + traceId: + nullable: true + description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary) + spanId: + nullable: true + description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary) + parentSpanId: + nullable: true + description: Parent span ID if this is a child span + name: + type: string + nullable: true + description: Span name describing the operation + kind: + type: integer + nullable: true + description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER) + startTimeUnixNano: + nullable: true + description: Start time in nanoseconds since Unix epoch + endTimeUnixNano: + nullable: true + description: End time in nanoseconds since Unix epoch + attributes: + type: array + items: + $ref: '#/components/schemas/OtelAttribute' + nullable: true + description: >- + Span attributes including Langfuse-specific attributes + (langfuse.observation.*) + status: + type: object + additionalProperties: true + nullable: true + description: Span status object + OtelAttribute: + title: OtelAttribute + type: object + description: Key-value attribute pair for resources, scopes, or spans + properties: + key: + type: string + nullable: true + description: Attribute key (e.g., "service.name", "langfuse.observation.type") + value: + $ref: '#/components/schemas/OtelAttributeValue' + nullable: true + description: Attribute value + OtelAttributeValue: + title: OtelAttributeValue + type: object + description: Attribute value wrapper supporting different value types + properties: + stringValue: + type: string + nullable: true + description: String value + intValue: + type: integer + nullable: true + description: Integer value + doubleValue: + type: number + format: double + nullable: true + description: Double value + boolValue: + type: boolean + nullable: true + description: Boolean value + OtelTraceResponse: + title: OtelTraceResponse + type: object + description: Response from trace export request. Empty object indicates success. + properties: {} + MembershipRole: + title: MembershipRole + type: string + enum: + - OWNER + - ADMIN + - MEMBER + - VIEWER + MembershipRequest: + title: MembershipRequest + type: object + properties: + userId: + type: string + role: + $ref: '#/components/schemas/MembershipRole' + required: + - userId + - role + DeleteMembershipRequest: + title: DeleteMembershipRequest + type: object + properties: + userId: + type: string + required: + - userId + MembershipResponse: + title: MembershipResponse + type: object + properties: + userId: + type: string + role: + $ref: '#/components/schemas/MembershipRole' + email: + type: string + name: + type: string + required: + - userId + - role + - email + - name + MembershipDeletionResponse: + title: MembershipDeletionResponse + type: object + properties: + message: + type: string + userId: + type: string + required: + - message + - userId + MembershipsResponse: + title: MembershipsResponse + type: object + properties: + memberships: + type: array + items: + $ref: '#/components/schemas/MembershipResponse' + required: + - memberships + OrganizationProject: + title: OrganizationProject + type: object + properties: + id: + type: string + name: + type: string + metadata: + type: object + additionalProperties: true + nullable: true + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - name + - createdAt + - updatedAt + OrganizationProjectsResponse: + title: OrganizationProjectsResponse + type: object + properties: + projects: + type: array + items: + $ref: '#/components/schemas/OrganizationProject' + required: + - projects + OrganizationApiKey: + title: OrganizationApiKey + type: object + properties: + id: + type: string + createdAt: + type: string + format: date-time + expiresAt: + type: string + format: date-time + nullable: true + lastUsedAt: + type: string + format: date-time + nullable: true + note: + type: string + nullable: true + publicKey: + type: string + displaySecretKey: + type: string + required: + - id + - createdAt + - publicKey + - displaySecretKey + OrganizationApiKeysResponse: + title: OrganizationApiKeysResponse + type: object + properties: + apiKeys: + type: array + items: + $ref: '#/components/schemas/OrganizationApiKey' + required: + - apiKeys + Projects: + title: Projects + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Project' + required: + - data + Organization: + title: Organization + type: object + properties: + id: + type: string + description: The unique identifier of the organization + name: + type: string + description: The name of the organization + required: + - id + - name + Project: + title: Project + type: object + properties: + id: + type: string + name: + type: string + organization: + $ref: '#/components/schemas/Organization' + description: The organization this project belongs to + metadata: + type: object + additionalProperties: true + description: Metadata for the project + retentionDays: + type: integer + nullable: true + description: >- + Number of days to retain data. Null or 0 means no retention. Omitted + if no retention is configured. + required: + - id + - name + - organization + - metadata + ProjectDeletionResponse: + title: ProjectDeletionResponse + type: object + properties: + success: + type: boolean + message: + type: string + required: + - success + - message + ApiKeyList: + title: ApiKeyList + type: object + description: List of API keys for a project + properties: + apiKeys: + type: array + items: + $ref: '#/components/schemas/ApiKeySummary' + required: + - apiKeys + ApiKeySummary: + title: ApiKeySummary + type: object + description: Summary of an API key + properties: + id: + type: string + createdAt: + type: string + format: date-time + expiresAt: + type: string + format: date-time + nullable: true + lastUsedAt: + type: string + format: date-time + nullable: true + note: + type: string + nullable: true + publicKey: + type: string + displaySecretKey: + type: string + required: + - id + - createdAt + - publicKey + - displaySecretKey + ApiKeyResponse: + title: ApiKeyResponse + type: object + description: Response for API key creation + properties: + id: + type: string + createdAt: + type: string + format: date-time + publicKey: + type: string + secretKey: + type: string + displaySecretKey: + type: string + note: + type: string + nullable: true + required: + - id + - createdAt + - publicKey + - secretKey + - displaySecretKey + ApiKeyDeletionResponse: + title: ApiKeyDeletionResponse + type: object + description: Response for API key deletion + properties: + success: + type: boolean + required: + - success + PromptMetaListResponse: + title: PromptMetaListResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/PromptMeta' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + PromptMeta: + title: PromptMeta + type: object + properties: + name: + type: string + type: + $ref: '#/components/schemas/PromptType' + description: Indicates whether the prompt is a text or chat prompt. + versions: + type: array + items: + type: integer + labels: + type: array + items: + type: string + tags: + type: array + items: + type: string + lastUpdatedAt: + type: string + format: date-time + lastConfig: + description: >- + Config object of the most recent prompt version that matches the + filters (if any are provided) + required: + - name + - type + - versions + - labels + - tags + - lastUpdatedAt + - lastConfig + CreatePromptRequest: + title: CreatePromptRequest + oneOf: + - $ref: '#/components/schemas/CreateChatPromptRequest' + - $ref: '#/components/schemas/CreateTextPromptRequest' + CreateChatPromptRequest: + title: CreateChatPromptRequest + type: object + properties: + name: + type: string + prompt: + type: array + items: + $ref: '#/components/schemas/ChatMessageWithPlaceholders' + config: + nullable: true + type: + $ref: '#/components/schemas/CreateChatPromptType' + labels: + type: array + items: + type: string + nullable: true + description: List of deployment labels of this prompt version. + tags: + type: array + items: + type: string + nullable: true + description: List of tags to apply to all versions of this prompt. + commitMessage: + type: string + nullable: true + description: Commit message for this prompt version. + required: + - name + - prompt + - type + CreateTextPromptRequest: + title: CreateTextPromptRequest + type: object + properties: + name: + type: string + prompt: + type: string + config: + nullable: true + type: + $ref: '#/components/schemas/CreateTextPromptType' + nullable: true + labels: + type: array + items: + type: string + nullable: true + description: List of deployment labels of this prompt version. + tags: + type: array + items: + type: string + nullable: true + description: List of tags to apply to all versions of this prompt. + commitMessage: + type: string + nullable: true + description: Commit message for this prompt version. + required: + - name + - prompt + Prompt: + title: Prompt + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - chat + - $ref: '#/components/schemas/ChatPrompt' + required: + - type + title: ChatPrompt + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - text + - $ref: '#/components/schemas/TextPrompt' + required: + - type + title: TextPrompt + PromptType: + title: PromptType + type: string + enum: + - chat + - text + BasePrompt: + title: BasePrompt + type: object + properties: + name: + type: string + version: + type: integer + config: {} + labels: + type: array + items: + type: string + description: List of deployment labels of this prompt version. + tags: + type: array + items: + type: string + description: >- + List of tags. Used to filter via UI and API. The same across + versions of a prompt. + commitMessage: + type: string + nullable: true + description: Commit message for this prompt version. + resolutionGraph: + type: object + additionalProperties: true + nullable: true + description: >- + The dependency resolution graph for the current prompt. Null if the + prompt has no dependencies or if `resolve=false` was used. + required: + - name + - version + - config + - labels + - tags + ChatMessageWithPlaceholders: + title: ChatMessageWithPlaceholders + oneOf: + - $ref: '#/components/schemas/ChatMessage' + - $ref: '#/components/schemas/PlaceholderMessage' + ChatMessage: + title: ChatMessage + type: object + properties: + role: + type: string + content: + type: string + type: + $ref: '#/components/schemas/ChatMessageType' + nullable: true + required: + - role + - content + ChatMessageType: + title: ChatMessageType + type: string + enum: + - chatmessage + PlaceholderMessage: + title: PlaceholderMessage + type: object + properties: + name: + type: string + type: + $ref: '#/components/schemas/PlaceholderMessageType' + nullable: true + required: + - name + PlaceholderMessageType: + title: PlaceholderMessageType + type: string + enum: + - placeholder + TextPrompt: + title: TextPrompt + type: object + properties: + prompt: + type: string + required: + - prompt + allOf: + - $ref: '#/components/schemas/BasePrompt' + ChatPrompt: + title: ChatPrompt + type: object + properties: + prompt: + type: array + items: + $ref: '#/components/schemas/ChatMessageWithPlaceholders' + required: + - prompt + allOf: + - $ref: '#/components/schemas/BasePrompt' + CreateChatPromptType: + title: CreateChatPromptType + type: string + enum: + - chat + CreateTextPromptType: + title: CreateTextPromptType + type: string + enum: + - text + ServiceProviderConfig: + title: ServiceProviderConfig + type: object + properties: + schemas: + type: array + items: + type: string + documentationUri: + type: string + patch: + $ref: '#/components/schemas/ScimFeatureSupport' + bulk: + $ref: '#/components/schemas/BulkConfig' + filter: + $ref: '#/components/schemas/FilterConfig' + changePassword: + $ref: '#/components/schemas/ScimFeatureSupport' + sort: + $ref: '#/components/schemas/ScimFeatureSupport' + etag: + $ref: '#/components/schemas/ScimFeatureSupport' + authenticationSchemes: + type: array + items: + $ref: '#/components/schemas/AuthenticationScheme' + meta: + $ref: '#/components/schemas/ResourceMeta' + required: + - schemas + - documentationUri + - patch + - bulk + - filter + - changePassword + - sort + - etag + - authenticationSchemes + - meta + ScimFeatureSupport: + title: ScimFeatureSupport + type: object + properties: + supported: + type: boolean + required: + - supported + BulkConfig: + title: BulkConfig + type: object + properties: + supported: + type: boolean + maxOperations: + type: integer + maxPayloadSize: + type: integer + required: + - supported + - maxOperations + - maxPayloadSize + FilterConfig: + title: FilterConfig + type: object + properties: + supported: + type: boolean + maxResults: + type: integer + required: + - supported + - maxResults + ResourceMeta: + title: ResourceMeta + type: object + properties: + resourceType: + type: string + location: + type: string + required: + - resourceType + - location + AuthenticationScheme: + title: AuthenticationScheme + type: object + properties: + name: + type: string + description: + type: string + specUri: + type: string + type: + type: string + primary: + type: boolean + required: + - name + - description + - specUri + - type + - primary + ResourceTypesResponse: + title: ResourceTypesResponse + type: object + properties: + schemas: + type: array + items: + type: string + totalResults: + type: integer + Resources: + type: array + items: + $ref: '#/components/schemas/ResourceType' + required: + - schemas + - totalResults + - Resources + ResourceType: + title: ResourceType + type: object + properties: + schemas: + type: array + items: + type: string + nullable: true + id: + type: string + name: + type: string + endpoint: + type: string + description: + type: string + schema: + type: string + schemaExtensions: + type: array + items: + $ref: '#/components/schemas/SchemaExtension' + meta: + $ref: '#/components/schemas/ResourceMeta' + required: + - id + - name + - endpoint + - description + - schema + - schemaExtensions + - meta + SchemaExtension: + title: SchemaExtension + type: object + properties: + schema: + type: string + required: + type: boolean + required: + - schema + - required + SchemasResponse: + title: SchemasResponse + type: object + properties: + schemas: + type: array + items: + type: string + totalResults: + type: integer + Resources: + type: array + items: + $ref: '#/components/schemas/SchemaResource' + required: + - schemas + - totalResults + - Resources + SchemaResource: + title: SchemaResource + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + attributes: + type: array + items: {} + meta: + $ref: '#/components/schemas/ResourceMeta' + required: + - id + - name + - description + - attributes + - meta + ScimUsersListResponse: + title: ScimUsersListResponse + type: object + properties: + schemas: + type: array + items: + type: string + totalResults: + type: integer + startIndex: + type: integer + itemsPerPage: + type: integer + Resources: + type: array + items: + $ref: '#/components/schemas/ScimUser' + required: + - schemas + - totalResults + - startIndex + - itemsPerPage + - Resources + ScimUser: + title: ScimUser + type: object + properties: + schemas: + type: array + items: + type: string + id: + type: string + userName: + type: string + name: + $ref: '#/components/schemas/ScimName' + emails: + type: array + items: + $ref: '#/components/schemas/ScimEmail' + meta: + $ref: '#/components/schemas/UserMeta' + required: + - schemas + - id + - userName + - name + - emails + - meta + UserMeta: + title: UserMeta + type: object + properties: + resourceType: + type: string + created: + type: string + nullable: true + lastModified: + type: string + nullable: true + required: + - resourceType + ScimName: + title: ScimName + type: object + properties: + formatted: + type: string + nullable: true + ScimEmail: + title: ScimEmail + type: object + properties: + primary: + type: boolean + value: + type: string + type: + type: string + required: + - primary + - value + - type + EmptyResponse: + title: EmptyResponse + type: object + description: Empty response for 204 No Content responses + properties: {} + ScoreConfigs: + title: ScoreConfigs + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ScoreConfig' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateScoreConfigRequest: + title: CreateScoreConfigRequest + type: object + properties: + name: + type: string + description: >- + Name of the score config. Max 35 characters. Only letters, numbers, + underscores, spaces, periods, parentheses, and hyphens are allowed. + dataType: + $ref: '#/components/schemas/ScoreConfigDataType' + categories: + type: array + items: + $ref: '#/components/schemas/ConfigCategory' + nullable: true + description: >- + Configure custom categories for categorical scores. Pass a list of + objects with `label` and `value` properties. Categories are + autogenerated for boolean configs and cannot be passed + minValue: + type: number + format: double + nullable: true + description: >- + Configure a minimum value for numerical scores. If not set, the + minimum value defaults to -∞ + maxValue: + type: number + format: double + nullable: true + description: >- + Configure a maximum value for numerical scores. If not set, the + maximum value defaults to +∞ + description: + type: string + nullable: true + description: >- + Description is shown across the Langfuse UI and can be used to e.g. + explain the config categories in detail, why a numeric range was + set, or provide additional context on config name or usage + required: + - name + - dataType + UpdateScoreConfigRequest: + title: UpdateScoreConfigRequest + type: object + properties: + isArchived: + type: boolean + nullable: true + description: The status of the score config showing if it is archived or not + name: + type: string + nullable: true + description: >- + Name of the score config. Max 35 characters. Only letters, numbers, + underscores, spaces, periods, parentheses, and hyphens are allowed. + categories: + type: array + items: + $ref: '#/components/schemas/ConfigCategory' + nullable: true + description: >- + Configure custom categories for categorical scores. Pass a list of + objects with `label` and `value` properties. Categories are + autogenerated for boolean configs and cannot be passed + minValue: + type: number + format: double + nullable: true + description: >- + Configure a minimum value for numerical scores. If not set, the + minimum value defaults to -∞ + maxValue: + type: number + format: double + nullable: true + description: >- + Configure a maximum value for numerical scores. If not set, the + maximum value defaults to +∞ + description: + type: string + nullable: true + description: >- + Description is shown across the Langfuse UI and can be used to e.g. + explain the config categories in detail, why a numeric range was + set, or provide additional context on config name or usage + ScoreSubjectTraceV3: + title: ScoreSubjectTraceV3 + type: object + properties: + id: + type: string + description: The trace ID. + required: + - id + ScoreSubjectObservationV3: + title: ScoreSubjectObservationV3 + type: object + properties: + id: + type: string + description: The observation ID. + traceId: + type: string + nullable: true + description: The parent trace ID, if available. + required: + - id + ScoreSubjectSessionV3: + title: ScoreSubjectSessionV3 + type: object + properties: + id: + type: string + description: The session ID. + required: + - id + ScoreSubjectExperimentV3: + title: ScoreSubjectExperimentV3 + type: object + properties: + id: + type: string + description: The dataset run ID (experiment ID). + required: + - id + ScoreSubjectV3: + title: ScoreSubjectV3 + oneOf: + - type: object + allOf: + - type: object + properties: + kind: + type: string + enum: + - trace + - $ref: '#/components/schemas/ScoreSubjectTraceV3' + required: + - kind + title: ScoreSubjectTraceV3 + - type: object + allOf: + - type: object + properties: + kind: + type: string + enum: + - observation + - $ref: '#/components/schemas/ScoreSubjectObservationV3' + required: + - kind + title: ScoreSubjectObservationV3 + - type: object + allOf: + - type: object + properties: + kind: + type: string + enum: + - session + - $ref: '#/components/schemas/ScoreSubjectSessionV3' + required: + - kind + title: ScoreSubjectSessionV3 + - type: object + allOf: + - type: object + properties: + kind: + type: string + enum: + - experiment + - $ref: '#/components/schemas/ScoreSubjectExperimentV3' + required: + - kind + title: ScoreSubjectExperimentV3 + description: >- + A reference to the entity this score is attached to. Discriminated by + "kind" — one of trace, observation, session, or experiment. + BaseScoreV3: + title: BaseScoreV3 + type: object + properties: + id: + type: string + projectId: + type: string + name: + type: string + source: + $ref: '#/components/schemas/ScoreSource' + timestamp: + type: string + format: date-time + environment: + type: string + description: The environment from which this score originated. + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + comment: + type: string + nullable: true + description: >- + Optional comment attached to the score. Present when "details" is + included in the fields parameter. + configId: + type: string + nullable: true + description: >- + The score config ID, if this score was created from a config. + Present when "details" is included in the fields parameter. + metadata: + type: object + additionalProperties: true + nullable: true + description: >- + Arbitrary metadata attached to the score. Present when "details" is + included in the fields parameter. + authorUserId: + type: string + nullable: true + description: >- + The user who created this score, if available. Present when + "annotation" is included in the fields parameter. + queueId: + type: string + nullable: true + description: >- + The annotation queue this score belongs to, if any. Present when + "annotation" is included in the fields parameter. + subject: + $ref: '#/components/schemas/ScoreSubjectV3' + nullable: true + description: >- + The entity this score is attached to (trace, observation, session, + or experiment). Present when "subject" is included in the fields + parameter. + required: + - id + - projectId + - name + - source + - timestamp + - environment + - createdAt + - updatedAt + NumericScoreV3: + title: NumericScoreV3 + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + BooleanScoreV3: + title: BooleanScoreV3 + type: object + properties: + value: + type: boolean + description: The boolean value of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + CategoricalScoreV3: + title: CategoricalScoreV3 + type: object + properties: + value: + type: string + description: The string category value of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + TextScoreV3: + title: TextScoreV3 + type: object + properties: + value: + type: string + description: The text content of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + CorrectionScoreV3: + title: CorrectionScoreV3 + type: object + properties: + value: + type: string + description: The correction content of the score. Empty string if not set. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + ScoreV3: + title: ScoreV3 + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/NumericScoreV3' + required: + - dataType + title: NumericScoreV3 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/BooleanScoreV3' + required: + - dataType + title: BooleanScoreV3 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/CategoricalScoreV3' + required: + - dataType + title: CategoricalScoreV3 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - TEXT + - $ref: '#/components/schemas/TextScoreV3' + required: + - dataType + title: TextScoreV3 + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CORRECTION + - $ref: '#/components/schemas/CorrectionScoreV3' + required: + - dataType + title: CorrectionScoreV3 + GetScoresV3Meta: + title: GetScoresV3Meta + type: object + properties: + limit: + type: integer + required: + - limit + allOf: + - $ref: '#/components/schemas/utilsCursorMetaResponse' + GetScoresV3Response: + title: GetScoresV3Response + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ScoreV3' + meta: + $ref: '#/components/schemas/GetScoresV3Meta' + required: + - data + - meta + CreateScoreRequest: + title: CreateScoreRequest + type: object + properties: + id: + type: string + nullable: true + traceId: + type: string + nullable: true + sessionId: + type: string + nullable: true + observationId: + type: string + nullable: true + datasetRunId: + type: string + nullable: true + name: + type: string + value: + $ref: '#/components/schemas/CreateScoreValue' + description: >- + The value of the score. Must be passed as string for categorical and + text scores, and numeric for boolean and numeric scores. Boolean + score values must equal either 1 or 0 (true or false). Text score + values must be between 1 and 500 characters. + comment: + type: string + nullable: true + metadata: + type: object + additionalProperties: true + nullable: true + environment: + type: string + nullable: true + description: >- + The environment of the score. Can be any lowercase alphanumeric + string with hyphens and underscores that does not start with + 'langfuse'. + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + dataType: + $ref: '#/components/schemas/ScoreDataType' + nullable: true + description: >- + The data type of the score. When passing a configId this field is + inferred. Otherwise, this field must be passed or will default to + numeric. + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. The unique langfuse identifier + of a score config. When passing this field, the dataType and + stringValue fields are automatically populated. + source: + $ref: '#/components/schemas/CreateScoreSource' + nullable: true + description: >- + The source of the score. Defaults to API. Set to ANNOTATION to + prefill scores (e.g. from an LLM) for a human reviewer to verify in + an annotation queue. When source is ANNOTATION, a configId is + required unless dataType is CORRECTION. EVAL is reserved for + internal evaluator outputs and is not accepted on this endpoint. + required: + - name + - value + CreateScoreSource: + title: CreateScoreSource + type: string + enum: + - API + - ANNOTATION + description: |- + Source values accepted when creating a score via the public REST API. + EVAL is reserved for internal evaluator outputs and is intentionally not + exposed here — use commons.ScoreSource when reading scores. + CreateScoreResponse: + title: CreateScoreResponse + type: object + properties: + id: + type: string + description: The id of the created object in Langfuse + required: + - id + GetScoresResponseTraceData: + title: GetScoresResponseTraceData + type: object + properties: + userId: + type: string + nullable: true + description: The user ID associated with the trace referenced by score + tags: + type: array + items: + type: string + nullable: true + description: A list of tags associated with the trace referenced by score + environment: + type: string + nullable: true + description: The environment of the trace referenced by score + sessionId: + type: string + nullable: true + description: The session ID associated with the trace referenced by score + GetScoresResponseDataNumeric: + title: GetScoresResponseDataNumeric + type: object + properties: + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' + nullable: true + allOf: + - $ref: '#/components/schemas/NumericScore' + GetScoresResponseDataCategorical: + title: GetScoresResponseDataCategorical + type: object + properties: + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' + nullable: true + allOf: + - $ref: '#/components/schemas/CategoricalScore' + GetScoresResponseDataBoolean: + title: GetScoresResponseDataBoolean + type: object + properties: + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' + nullable: true + allOf: + - $ref: '#/components/schemas/BooleanScore' + GetScoresResponseDataCorrection: + title: GetScoresResponseDataCorrection + type: object + properties: + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' + nullable: true + allOf: + - $ref: '#/components/schemas/CorrectionScore' + GetScoresResponseDataText: + title: GetScoresResponseDataText + type: object + properties: + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' + nullable: true + allOf: + - $ref: '#/components/schemas/TextScore' + GetScoresResponseData: + title: GetScoresResponseData + oneOf: + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - $ref: '#/components/schemas/GetScoresResponseDataNumeric' + required: + - dataType + title: GetScoresResponseDataNumeric + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CATEGORICAL + - $ref: '#/components/schemas/GetScoresResponseDataCategorical' + required: + - dataType + title: GetScoresResponseDataCategorical + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - BOOLEAN + - $ref: '#/components/schemas/GetScoresResponseDataBoolean' + required: + - dataType + title: GetScoresResponseDataBoolean + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - CORRECTION + - $ref: '#/components/schemas/GetScoresResponseDataCorrection' + required: + - dataType + title: GetScoresResponseDataCorrection + - type: object + allOf: + - type: object + properties: + dataType: + type: string + enum: + - TEXT + - $ref: '#/components/schemas/GetScoresResponseDataText' + required: + - dataType + title: GetScoresResponseDataText + GetScoresResponse: + title: GetScoresResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/GetScoresResponseData' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + PaginatedSessions: + title: PaginatedSessions + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Session' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + Traces: + title: Traces + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/TraceWithDetails' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + required: + - data + - meta + DeleteTraceResponse: + title: DeleteTraceResponse + type: object + properties: + message: + type: string + required: + - message + Sort: + title: Sort + type: object + properties: + id: + type: string + required: + - id + unstableDashboardWidgetView: + title: unstableDashboardWidgetView + type: string + enum: + - observations + - scores-numeric + - scores-boolean + - scores-categorical + unstableDashboardWidgetViewWithLegacy: + title: unstableDashboardWidgetViewWithLegacy + type: string + enum: + - observations + - scores-numeric + - scores-boolean + - scores-categorical + - traces + description: |- + Widget data view. Responses may include the legacy `traces` value for + widgets created before this API existed. + unstableDashboardWidgetChartType: + title: unstableDashboardWidgetChartType + type: string + enum: + - LINE_TIME_SERIES + - AREA_TIME_SERIES + - BAR_TIME_SERIES + - HORIZONTAL_BAR + - VERTICAL_BAR + - PIE + - NUMBER + - HISTOGRAM + - PIVOT_TABLE + unstableDashboardWidgetMetricAggregation: + title: unstableDashboardWidgetMetricAggregation + type: string + enum: + - sum + - avg + - count + - max + - min + - p50 + - p75 + - p90 + - p95 + - p99 + - histogram + - uniq + unstableDashboardWidgetDimension: + title: unstableDashboardWidgetDimension + type: object + properties: + field: + type: string + required: + - field + unstableDashboardWidgetMetric: + title: unstableDashboardWidgetMetric + type: object + properties: + measure: + type: string + agg: + $ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation' + required: + - measure + - agg + unstableDashboardWidgetFilter: + title: unstableDashboardWidgetFilter + type: object + description: >- + A filter in Langfuse filter-state shape. The `value` shape and the + + allowed operators depend on `type`: + + + | `type` | `value` | operators | + + |---|---|---| + + | `string` | string | `=`, `contains`, `does not contain`, `starts + with`, `ends with` | + + | `number` | number | `=`, `>`, `<`, `>=`, `<=` | + + | `datetime` | ISO datetime string | `>`, `<`, `>=`, `<=` | + + | `boolean` | boolean | `=`, `<>` | + + | `null` | `""` | `is null`, `is not null` | + + | `stringOptions` | list of strings | `any of`, `none of` | + + | `arrayOptions` | list of strings | `any of`, `none of`, `all of` | + + | `categoryOptions` | list of strings (requires `key`) | `any of`, `none + of` | + + | `stringObject` | string (requires `key`, e.g. a metadata key) | same + as `string` | + + | `numberObject` | number (requires `key`, e.g. a score name) | same as + `number` | + + | `booleanObject` | boolean (requires `key`) | `=`, `<>` | + properties: + column: + type: string + operator: + type: string + type: + type: string + value: + nullable: true + key: + type: string + nullable: true + required: + - column + - operator + - type + unstableDashboardWidgetChartConfig: + title: unstableDashboardWidgetChartConfig + type: object + description: |- + Chart-specific widget configuration. + + `type` must match the top-level `chartType`. + `row_limit` applies to total-value charts and pivot tables. + `bins` applies to histograms. + `defaultSort` applies to pivot tables. + properties: + type: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + row_limit: + type: integer + nullable: true + show_value_labels: + type: boolean + nullable: true + bins: + type: integer + nullable: true + defaultSort: + $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort' + nullable: true + required: + - type + unstableDashboardWidgetDefaultSort: + title: unstableDashboardWidgetDefaultSort + type: object + properties: + column: + type: string + order: + $ref: '#/components/schemas/unstableDashboardWidgetSortOrder' + required: + - column + - order + unstableDashboardWidgetSortOrder: + title: unstableDashboardWidgetSortOrder + type: string + enum: + - ASC + - DESC + unstableDashboardWidgetChartConfigInput: + title: unstableDashboardWidgetChartConfigInput + type: object + description: |- + Input-side chart config. `type` is optional and defaults to the + widget's `chartType`; when given it must match. + properties: + type: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + nullable: true + row_limit: + type: integer + nullable: true + show_value_labels: + type: boolean + nullable: true + bins: + type: integer + nullable: true + defaultSort: + $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort' + nullable: true + unstableCreateDashboardWidgetRequest: + title: unstableCreateDashboardWidgetRequest + type: object + properties: + name: + type: string + description: + type: string + nullable: true + description: Defaults to an empty string. + view: + $ref: '#/components/schemas/unstableDashboardWidgetView' + dimensions: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput' + nullable: true + description: Defaults to the plain config for `chartType`. + required: + - name + - view + - dimensions + - metrics + - filters + - chartType + unstableUpdateDashboardWidgetRequest: + title: unstableUpdateDashboardWidgetRequest + type: object + properties: + name: + type: string + nullable: true + description: + type: string + nullable: true + view: + $ref: '#/components/schemas/unstableDashboardWidgetView' + nullable: true + dimensions: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + nullable: true + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + nullable: true + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput' + nullable: true + unstableDashboardWidgetList: + title: unstableDashboardWidgetList + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidget' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + unstableDeleteDashboardWidgetResponse: + title: unstableDeleteDashboardWidgetResponse + type: object + properties: + message: + type: string + required: + - message + unstableDashboardWidget: + title: unstableDashboardWidget + type: object + properties: + id: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + name: + type: string + description: + type: string + view: + $ref: '#/components/schemas/unstableDashboardWidgetViewWithLegacy' + dimensions: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfig' + required: + - id + - createdAt + - updatedAt + - name + - description + - view + - dimensions + - metrics + - filters + - chartType + - chartConfig + unstableDashboardPlacement: + title: unstableDashboardPlacement + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - widget + - $ref: '#/components/schemas/unstableWidgetPlacement' + required: + - type + title: UnstableWidgetPlacement + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - preset + - $ref: '#/components/schemas/unstablePresetPlacement' + required: + - type + title: UnstablePresetPlacement + description: |- + A tile on the dashboard's 12-column grid. `x`/`y` are the tile's + top-left cell (0-based; `y` grows downward), `width`/`height` its size + in cells. The UI default tile is 6x6 (half width). Overlapping tiles + are not rejected; prefer appending below existing tiles (or omit the + position on create to let the server do it). + unstableWidgetPlacement: + title: unstableWidgetPlacement + type: object + properties: + id: + type: string + widgetId: + type: string + x: + type: integer + 'y': + type: integer + width: + type: integer + height: + type: integer + required: + - id + - widgetId + - x + - 'y' + - width + - height + unstablePresetPlacement: + title: unstablePresetPlacement + type: object + properties: + id: + type: string + presetId: + type: string + x: + type: integer + 'y': + type: integer + width: + type: integer + height: + type: integer + required: + - id + - presetId + - x + - 'y' + - width + - height + unstableCreateDashboardPlacementRequest: + title: unstableCreateDashboardPlacementRequest + oneOf: + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - widget + - $ref: '#/components/schemas/unstableCreateWidgetPlacement' + required: + - type + title: UnstableCreateWidgetPlacement + - type: object + allOf: + - type: object + properties: + type: + type: string + enum: + - preset + - $ref: '#/components/schemas/unstableCreatePresetPlacement' + required: + - type + title: UnstableCreatePresetPlacement + unstableCreateWidgetPlacement: + title: unstableCreateWidgetPlacement + type: object + properties: + id: + type: string + nullable: true + description: Server-generated when omitted. + widgetId: + type: string + x: + type: integer + nullable: true + description: Grid column (12-column grid). Defaults to `0`. + 'y': + type: integer + nullable: true + description: Grid row. Defaults to the first row below all existing tiles. + width: + type: integer + nullable: true + description: Width in grid columns. Defaults to `6`. + height: + type: integer + nullable: true + description: Height in grid rows. Defaults to `6`. + required: + - widgetId + unstableCreatePresetPlacement: + title: unstableCreatePresetPlacement + type: object + properties: + id: + type: string + nullable: true + description: Server-generated when omitted. + presetId: + type: string + x: + type: integer + nullable: true + description: Grid column (12-column grid). Defaults to `0`. + 'y': + type: integer + nullable: true + description: Grid row. Defaults to the first row below all existing tiles. + width: + type: integer + nullable: true + description: Width in grid columns. Defaults to `6`. + height: + type: integer + nullable: true + description: Height in grid rows. Defaults to `6`. + required: + - presetId + unstableUpdateDashboardPlacementRequest: + title: unstableUpdateDashboardPlacementRequest + type: object + properties: + x: + type: integer + nullable: true + description: Grid column (12-column grid). + 'y': + type: integer + nullable: true + description: Grid row. + width: + type: integer + nullable: true + description: Width in grid columns. + height: + type: integer + nullable: true + description: Height in grid rows. + unstableDeleteDashboardPlacementResponse: + title: unstableDeleteDashboardPlacementResponse + type: object + properties: + message: + type: string + required: + - message + unstableDashboardDefinition: + title: unstableDashboardDefinition + type: object + properties: + widgets: + type: array + items: + $ref: '#/components/schemas/unstableDashboardPlacement' + required: + - widgets + unstableDashboard: + title: unstableDashboard + type: object + properties: + id: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + name: + type: string + description: + type: string + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + description: Dashboard-level filters applied to all widgets on the dashboard. + required: + - id + - createdAt + - updatedAt + - name + - description + - definition + - filters + unstableDashboardList: + title: unstableDashboardList + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableDashboard' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + unstableCreateDashboardRequest: + title: unstableCreateDashboardRequest + type: object + properties: + name: + type: string + description: + type: string + nullable: true + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + required: + - name + unstableUpdateDashboardRequest: + title: unstableUpdateDashboardRequest + type: object + properties: + name: + type: string + nullable: true + description: + type: string + nullable: true + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + unstableDeleteDashboardResponse: + title: unstableDeleteDashboardResponse + type: object + properties: + message: + type: string + required: + - message + unstablePublicApiErrorCode: + title: unstablePublicApiErrorCode + type: string + enum: + - authentication_failed + - access_denied + - invalid_request + - invalid_query + - invalid_body + - resource_not_found + - conflict + - rate_limited + - method_not_allowed + - internal_error + description: Machine-readable error code returned by unstable public API endpoints. + unstablePublicApiValidationIssue: + title: unstablePublicApiValidationIssue + type: object + description: >- + A validation issue returned for malformed request bodies or query + parameters. + properties: + code: + type: string + message: + type: string + path: + type: array + items: {} + required: + - code + - message + - path + unstablePublicApiErrorDetails: + title: unstablePublicApiErrorDetails + type: object + description: Optional structured context attached to an error. + properties: + issues: + type: array + items: + $ref: '#/components/schemas/unstablePublicApiValidationIssue' + nullable: true + field: + type: string + nullable: true + column: + type: string + nullable: true + invalidValues: + type: array + items: + type: string + nullable: true + allowedValues: + type: array + items: + type: string + nullable: true + value: + type: string + nullable: true + retryAfterSeconds: + type: integer + nullable: true + limit: + type: integer + nullable: true + remaining: + type: integer + nullable: true + resetAt: + type: string + nullable: true + unstablePublicApiError: + title: unstablePublicApiError + type: object + description: Standard error envelope for unstable public API endpoints. + properties: + message: + type: string + description: Human-readable description of the failure. + code: + $ref: '#/components/schemas/unstablePublicApiErrorCode' + description: Machine-readable error code. + details: + $ref: '#/components/schemas/unstablePublicApiErrorDetails' + nullable: true + description: Optional structured error context. + required: + - message + - code + unstableSkillMetaListResponse: + title: unstableSkillMetaListResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableSkillMeta' + meta: + $ref: '#/components/schemas/unstableSkillListPagination' + required: + - data + - meta + unstableSkillListPagination: + title: unstableSkillListPagination + type: object + properties: + hasNextPage: + type: boolean + required: + - hasNextPage + allOf: + - $ref: '#/components/schemas/utilsMetaResponse' + unstableSkillMeta: + title: unstableSkillMeta + type: object + properties: + name: + type: string + description: + type: string + tags: + type: array + items: + type: string + latestVersion: + type: integer + latestVersionCreatedAt: + type: string + format: date-time + latestVersionLastUpdatedAt: + type: string + format: date-time + productionVersion: + type: integer + nullable: true + description: >- + Version assigned the production label, or null when no version is + assigned. + required: + - name + - description + - tags + - latestVersion + - latestVersionCreatedAt + - latestVersionLastUpdatedAt + - productionVersion + unstableSkillVersionFileInput: + title: unstableSkillVersionFileInput + type: object + properties: + path: + type: string + content: + type: string + description: UTF-8 text content. The server computes the hash and byte length. + required: + - path + - content + unstableSkillVersionFileReference: + title: unstableSkillVersionFileReference + type: object + properties: + path: + type: string + sha256Hash: + type: string + description: >- + Canonical base64-encoded SHA-256 from a skill file manifest. The + content must already exist in this project. + required: + - path + - sha256Hash + unstableSkillVersionFileCreateInput: + title: unstableSkillVersionFileCreateInput + oneOf: + - $ref: '#/components/schemas/unstableSkillVersionFileInput' + - $ref: '#/components/schemas/unstableSkillVersionFileReference' + description: Provide exactly one of content or sha256Hash for each path. + unstableCreateSkillVersionRequest: + title: unstableCreateSkillVersionRequest + type: object + properties: + files: + type: array + items: + $ref: '#/components/schemas/unstableSkillVersionFileCreateInput' + commitMessage: + type: string + nullable: true + required: + - files + unstableSkillFile: + title: unstableSkillFile + type: object + properties: + id: + type: string + path: + type: string + blobId: + type: string + sha256Hash: + type: string + contentType: + type: string + contentLength: + type: integer + format: int64 + required: + - id + - path + - blobId + - sha256Hash + - contentType + - contentLength + unstableSkillFileContentsResponse: + title: unstableSkillFileContentsResponse + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableSkillFileContent' + required: + - data + unstableSkillFileContent: + title: unstableSkillFileContent + type: object + properties: + sha256Hash: + type: string + content: + type: string + required: + - sha256Hash + - content + unstableSkillVersion: + title: unstableSkillVersion + type: object + properties: + id: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + projectId: + type: string + createdBy: + type: string + name: + type: string + description: + type: string + frontmatter: {} + version: + type: integer + tags: + type: array + items: + type: string + labels: + type: array + items: + type: string + commitMessage: + type: string + nullable: true + files: + type: array + items: + $ref: '#/components/schemas/unstableSkillFile' + required: + - id + - createdAt + - updatedAt + - projectId + - createdBy + - name + - description + - frontmatter + - version + - tags + - labels + - commitMessage + - files + unstableUpdateSkillRequest: + title: unstableUpdateSkillRequest + type: object + properties: + tags: + type: array + items: + type: string + description: >- + The complete set of tags to apply to every version of the skill. + Pass an empty list to clear all tags. + required: + - tags + unstableUpdateSkillLabelsRequest: + title: unstableUpdateSkillLabelsRequest + type: object + properties: + labels: + type: array + items: + type: string + required: + - labels + unstableDeleteSkillVersionResponse: + title: unstableDeleteSkillVersionResponse + type: object + properties: + deleted: + type: boolean + required: + - deleted + utilsMetaResponse: + title: utilsMetaResponse + type: object + properties: + page: + type: integer + description: current page number + limit: + type: integer + description: number of items per page + totalItems: + type: integer + description: number of total items given the current filters/selection (if any) + totalPages: + type: integer + description: number of total pages given the current limit + required: + - page + - limit + - totalItems + - totalPages + utilsCursorMetaResponse: + title: utilsCursorMetaResponse + type: object + description: Metadata for cursor-based pagination. + properties: + cursor: + type: string + nullable: true + description: Opaque cursor for the next page. Omitted when there is no next page. + securitySchemes: + BasicAuth: + type: http + scheme: basic diff --git a/package.json b/package.json index 1b0fee4..222fa73 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,8 @@ "ajv-formats": "^3.0.1", "semver": "^7.8.5", "typescript": "^7.0.2", - "yaml": "^2.9.0" + "yaml": "^2.9.0", + "zod": "^4.6.5" }, "overrides": { "ajv": "8.17.1" diff --git a/src/cli.test.ts b/src/cli.test.ts index 6e20d12..204ea58 100644 --- a/src/cli.test.ts +++ b/src/cli.test.ts @@ -1,7 +1,8 @@ import { describe, expect, test } from "bun:test"; -import { mkdtemp, rm } from "node:fs/promises"; +import { createHash } from "node:crypto"; +import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from "node:fs/promises"; import { tmpdir } from "node:os"; -import { join } from "node:path"; +import { join, relative } from "node:path"; import { assertOperationCallable, @@ -20,6 +21,270 @@ import { CliError } from "./errors"; import { compileApiContract } from "./contracts/compiler"; import type { ApiOperation } from "./contracts/types"; +function skillManifest(name: string, contents: Record, version = 1) { + return { + name, version, labels: ["production"], + files: Object.entries(contents).map(([path, content]) => ({ + path, + sha256Hash: createHash("sha256").update(content).digest("base64"), + contentLength: Buffer.byteLength(content), + })), + }; +} + +async function withSkillsFixture(fn: (fixture: { + directory: string; + manifests: Map>; + contents: Map; + command: (args: string[]) => Promise<{ stdout: string; stderr: string; exitCode: number }>; +}) => Promise) { + const directory = await mkdtemp(join(tmpdir(), "langfuse-cli-skills-")); + const previousCwd = process.cwd(); + const previousFetch = globalThis.fetch; + const previousExitCode = process.exitCode; + const manifests = new Map>(); + const contents = new Map(); + try { + process.chdir(directory); + globalThis.fetch = (async (input: string | URL | Request) => { + const url = new URL(input instanceof Request ? input.url : input.toString()); + if (url.pathname.endsWith("/files/content")) { + return Response.json({ data: url.searchParams.get("sha256Hashes")!.split(",").map((sha256Hash) => ({ + sha256Hash, content: contents.get(sha256Hash), + })) }); + } + return Response.json(manifests.get(url.pathname.split("/").at(-1)!)); + }) as typeof fetch; + await fn({ directory, manifests, contents, command: async (args) => { + process.exitCode = 0; + const output = await captureOutput(() => run([ + "node", "langfuse", "--public-key", "test", "--secret-key", "test", + "--host", "https://example.invalid", "--json", "skills", ...args, + ])); + return { ...output, exitCode: Number(process.exitCode ?? 0) }; + } }); + } finally { + process.chdir(previousCwd); + globalThis.fetch = previousFetch; + process.exitCode = previousExitCode ?? 0; + await rm(directory, { recursive: true, force: true }); + } +} + +describe("hosted skills commands", () => { + for (const kind of ["absolute", "relative", "symlink"] as const) { + test(`rejects an external lockfile destination through ${kind} paths before requests`, async () => { + await withSkillsFixture(async ({ directory, manifests, contents, command }) => { + const outside = await mkdtemp(join(tmpdir(), "langfuse-cli-outside-")); + try { + let path = join(outside, "example"); + if (kind === "relative") path = relative(directory, path); + if (kind === "symlink") { + await symlink(outside, "alias", "dir"); + path = "alias/example"; + } + const manifest = skillManifest("example", { "SKILL.md": "example" }); + manifests.set("example", manifest); + contents.set(manifest.files[0].sha256Hash, "example"); + const lock = JSON.stringify({ lockVersion: 1, skills: { + [path]: { name: "example", selector: { label: "production" }, version: 1 }, + } }); + await writeFile("langfuse-skills-lock.json", lock); + let requests = 0; + const originalFetch = globalThis.fetch; + globalThis.fetch = (async (...args: Parameters) => { + requests++; + return originalFetch(...args); + }) as typeof fetch; + for (const action of ["install", "update"]) { + const result = await command([action]); + expect(result.exitCode).toBe(6); + expect(requests).toBe(0); + expect(await readFile(join(outside, "example/SKILL.md"), "utf8").catch(() => null)).toBeNull(); + expect(await readFile("langfuse-skills-lock.json", "utf8")).toBe(lock); + } + } finally { + await rm(outside, { recursive: true, force: true }); + } + }); + }); + } + + test("requires an explicit unlocked install for an external directory", async () => { + await withSkillsFixture(async ({ manifests, contents, command }) => { + const outside = await mkdtemp(join(tmpdir(), "langfuse-cli-outside-")); + try { + const manifest = skillManifest("example", { "SKILL.md": "example" }); + manifests.set("example", manifest); + contents.set(manifest.files[0].sha256Hash, "example"); + const result = await command(["install", "example", "--directory", outside]); + expect(result.exitCode).toBe(6); + expect(await readFile(join(outside, "example/SKILL.md"), "utf8").catch(() => null)).toBeNull(); + await writeFile("langfuse-skills-lock.json", "invalid lock"); + const unlocked = await command(["install", "example", "--directory", outside, "--no-lockfile"]); + expect(unlocked.exitCode).toBe(0); + expect(await readFile(join(outside, "example/SKILL.md"), "utf8")).toBe("example"); + expect(await readFile("langfuse-skills-lock.json", "utf8")).toBe("invalid lock"); + } finally { + await rm(outside, { recursive: true, force: true }); + } + }); + }); + + test("rejects a lock entry targeting the project directory itself", async () => { + await withSkillsFixture(async ({ manifests, contents, command }) => { + await mkdir("example"); + process.chdir("example"); + await writeFile("SKILL.md", "original"); + await writeFile("langfuse-skills-lock.json", JSON.stringify({ lockVersion: 1, skills: { + ".": { name: "example", selector: { label: "production" }, version: 1 }, + } })); + const manifest = skillManifest("example", { "SKILL.md": "replacement" }); + manifests.set("example", manifest); + contents.set(manifest.files[0].sha256Hash, "replacement"); + const result = await command(["install", "--force"]); + expect(result.exitCode).toBe(6); + expect(await readFile("SKILL.md", "utf8")).toBe("original"); + }); + }); + + test("bounds tag pagination and accepts a final page at the limit", async () => { + await withSkillsFixture(async ({ command }) => { + for (const terminates of [false, true]) { + let requests = 0; + globalThis.fetch = (async (input: string | URL | Request) => { + const url = new URL(input instanceof Request ? input.url : input.toString()); + expect(Number(url.searchParams.get("page"))).toBe(++requests); + if (requests > 100) throw new Error("Unbounded pagination"); + return Response.json({ data: [], meta: { hasNextPage: !terminates || requests < 100 } }); + }) as typeof fetch; + const result = await command(["install", "--tag", "example"]); + expect(result.exitCode).toBe(terminates ? 0 : 7); + expect(requests).toBe(100); + expect(result.stdout).toBe(terminates ? "[]\n" : ""); + } + }); + }); + + for (const paths of [["scripts/A.txt", "scripts/a.txt"], ["Scripts/a.txt", "scripts/b.txt"]]) { + test(`handles filesystem aliases without losing files: ${paths.join(", ")}`, async () => { + await withSkillsFixture(async ({ directory, manifests, contents, command }) => { + await writeFile("CaseProbe", "probe"); + const caseInsensitive = await readFile("caseprobe", "utf8").then(() => true, () => false); + const destination = join(directory, ".agents/skills/example"); + await mkdir(destination, { recursive: true }); + await writeFile(join(destination, "SKILL.md"), "original"); + const files = { "SKILL.md": "replacement", [paths[0]]: "first", [paths[1]]: "second" }; + const manifest = skillManifest("example", files); + manifests.set("example", manifest); + for (const [path, content] of Object.entries(files)) { + contents.set(manifest.files.find((file) => file.path === path)!.sha256Hash, content); + } + const result = await command(["install", "example", "--force", "--no-lockfile"]); + if (caseInsensitive) { + expect(result.exitCode).toBe(7); + expect(await readFile(join(destination, "SKILL.md"), "utf8")).toBe("original"); + } else { + expect(result.exitCode).toBe(0); + for (const [path, content] of Object.entries(files)) { + expect(await readFile(join(destination, path), "utf8")).toBe(content); + } + } + }); + }); + } + + for (const args of [["update", "--force"], ["update", "parent", "--force"], ["install", "parent", "--force"]]) { + test(`preserves nested recorded installations on ${args.join(" ")}`, async () => { + await withSkillsFixture(async ({ directory, manifests, contents, command }) => { + const parent = ".agents/skills/parent"; + const child = `${parent}/references/child`; + await mkdir(child, { recursive: true }); + await writeFile(`${parent}/SKILL.md`, "parent original"); + await writeFile(`${child}/SKILL.md`, "child original"); + const lock = JSON.stringify({ lockVersion: 1, skills: Object.fromEntries([ + [parent, { name: "parent", selector: { label: "production" }, version: 1 }], + [child, { name: "child", selector: { label: "production" }, version: 1 }], + ]) }); + await writeFile("langfuse-skills-lock.json", lock); + for (const name of ["parent", "child"]) { + const manifest = skillManifest(name, { "SKILL.md": `${name} replacement` }, 2); + manifests.set(name, manifest); + contents.set(manifest.files[0].sha256Hash, `${name} replacement`); + } + const result = await command(args); + expect(result.exitCode).toBe(6); + expect(await readFile(join(directory, parent, "SKILL.md"), "utf8")).toBe("parent original"); + expect(await readFile(join(directory, child, "SKILL.md"), "utf8")).toBe("child original"); + expect(await readFile("langfuse-skills-lock.json", "utf8")).toBe(lock); + }); + }); + } + + test("rejects a nested install through a symlink to a recorded parent", async () => { + await withSkillsFixture(async ({ directory, manifests, contents, command }) => { + const parent = ".agents/skills/parent"; + await mkdir(parent, { recursive: true }); + await writeFile(`${parent}/SKILL.md`, "original"); + await symlink(join(directory, parent), "alias", "dir"); + await writeFile("langfuse-skills-lock.json", JSON.stringify({ lockVersion: 1, skills: { + [parent]: { name: "parent", selector: { label: "production" }, version: 1 }, + } })); + const manifest = skillManifest("child", { "SKILL.md": "child" }); + manifests.set("child", manifest); + contents.set(manifest.files[0].sha256Hash, "child"); + const result = await command(["install", "child", "--directory", "alias/references"]); + expect(result.exitCode).toBe(6); + expect(result.stderr).toContain("overlap"); + expect(await readFile(`${parent}/SKILL.md`, "utf8")).toBe("original"); + }); + }); + + test("installs and updates a skill named help", async () => { + await withSkillsFixture(async ({ manifests, contents, command }) => { + for (const version of [1, 2]) { + const content = `help version ${version}`; + const manifest = skillManifest("help", { "SKILL.md": content }, version); + manifests.set("help", manifest); + contents.set(manifest.files[0].sha256Hash, content); + const result = await command(version === 1 ? ["install", "help"] : ["update", "help", "--force"]); + expect(result.exitCode).toBe(0); + expect(await readFile(".agents/skills/help/SKILL.md", "utf8")).toBe(content); + } + const result = await command(["install", "help"]); + expect(JSON.parse(result.stdout).status).toBe("unchanged"); + expect((await command(["install", "--help"])).stdout).toContain("Usage:"); + }); + }); + + test("distinguishes invalid successful responses from HTTP errors", async () => { + await withSkillsFixture(async ({ command }) => { + for (const [response, expected] of [ + [new Response("not-json", { status: 200 }), 7], + [Response.json({ name: "example", files: [] }), 7], + [Response.json({ message: "missing" }, { status: 404 }), 5], + ] as const) { + globalThis.fetch = (async () => response) as typeof fetch; + expect((await command(["install", "example", "--no-lockfile"])).exitCode).toBe(expected); + } + }); + }); + + test("preserves installed content when a download fails its checksum", async () => { + await withSkillsFixture(async ({ manifests, contents, command }) => { + await mkdir(".agents/skills/example", { recursive: true }); + await writeFile(".agents/skills/example/SKILL.md", "original"); + const manifest = skillManifest("example", { "SKILL.md": "correct" }); + manifests.set("example", manifest); + contents.set(manifest.files[0].sha256Hash, "wrong!!"); + const result = await command(["install", "example", "--force", "--no-lockfile"]); + expect(result.exitCode).toBe(7); + expect(result.stderr).toContain("checksum mismatch"); + expect(await readFile(".agents/skills/example/SKILL.md", "utf8")).toBe("original"); + }); + }); +}); + async function captureOutput( fn: () => Promise, ): Promise<{ stdout: string; stderr: string }> { diff --git a/src/cli.ts b/src/cli.ts index 234fd7c..919e3a8 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -12,6 +12,7 @@ import { EXIT_NETWORK, } from "./errors"; import { GLOBAL_BOOLEAN_FLAG_NAMES, GLOBAL_VALUE_FLAG_NAMES } from "./flags"; +import { runSkillsCommand } from "./skills"; import { loadApiContract, loadContractCatalog, @@ -186,6 +187,8 @@ Usage: langfuse [options] Commands: api Interact with the Langfuse REST API + skills install Install Langfuse-hosted skills by name or tag + skills update Update locked skills using their saved selectors get-skill Print the latest Langfuse skill from GitHub Options: @@ -199,13 +202,57 @@ Options: --version Show CLI version Exit codes: - 0 success · 2 usage · 3 configuration · 4 network · 5 HTTP error · 6 local file + 0 success · 2 usage · 3 configuration · 4 network · 5 HTTP error · 6 local file · 7 invalid response Examples: langfuse api help langfuse api prompts list langfuse api prompts create --body-json '{"name":"my-prompt","type":"text","prompt":"Hello"}' langfuse api observations list --limit 20 + langfuse skills install support-triage + langfuse skills install support-triage@staging + langfuse skills install support-triage@3 + langfuse skills install --tag support + langfuse skills install + langfuse skills update +`); +} + +function printSkillsHelp(): void { + process.stdout.write(`Usage: langfuse skills install [name[@selector]] [options] + langfuse skills install --tag [options] + langfuse skills update [name] [--force] [--json] + +Install a named skill or all skills with a tag. Defaults to the production label. +Use name@production or name@staging for a label, and name@3 for an exact version. +An all-digit suffix selects a version; use --label for numeric labels. A suffix +cannot be combined with --label or --version. +Without a name or tag, install restores the versions and directories in the lock. +Update follows saved labels and keeps explicit versions pinned. An optional name +limits updates to that skill. Local edits require --force to replace. +If verification needs an unavailable previous version, update stops before writing. +--force skips the historical check and allows replacing local files. +With the lockfile enabled, installation directories must stay within the project +and must not overlap other recorded installations, including through symlinks. + +Install options: + --tag Install all skills with this tag instead of a name + --version Install an immutable version (named skill only) + --label