🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
chore: prepare JS v6 and PY v5 SDK majors (#18516)
Hassieb Pakzad00b8271ed06c
diff --git a/.github/workflows/sdk-api-spec.yml b/.github/workflows/sdk-api-spec.ymlindex 77c81014e7..ed1c987230 100644--- a/.github/workflows/sdk-api-spec.yml+++ b/.github/workflows/sdk-api-spec.yml@@ -10,14 +10,31 @@ on:- "web/scripts/python-sdk/patch-generated-deprecations.ts"- "web/scripts/typescript-sdk/patch-generated-deprecations.ts"workflow_dispatch:+ inputs:+ python_sdk_base_branch:+ description: "langfuse-python branch to generate against and open the PR into"+ required: true+ default: main+ type: string+ js_sdk_base_branch:+ description: "langfuse-js branch to generate against and open the PR into"+ required: true+ default: main+ type: stringconcurrency:- group: sdk-api-spec-${{ github.ref }}+ # `:` cannot appear in a branch name, so distinct branch pairs never collide.+ group: sdk-api-spec-${{ github.ref }}:${{ inputs.python_sdk_base_branch || 'main' }}:${{ inputs.js_sdk_base_branch || 'main' }}cancel-in-progress: truepermissions:contents: read+# Push runs have no inputs and target the SDK default branches.+env:+ PYTHON_SDK_BASE_BRANCH: ${{ inputs.python_sdk_base_branch || 'main' }}+ JS_SDK_BASE_BRANCH: ${{ inputs.js_sdk_base_branch || 'main' }}+jobs:generate-sdk-api-specs:runs-on: blacksmith-4vcpu-ubuntu-2404@@ -27,6 +44,15 @@ jobs:typescript_has_changes: ${{ steps.prepare-typescript-sdk.outputs.has_changes }}typescript_branch_name: ${{ steps.prepare-typescript-sdk.outputs.branch_name }}steps:+ - name: Validate SDK base branches+ run: |+ for branch in "$PYTHON_SDK_BASE_BRANCH" "$JS_SDK_BASE_BRANCH"; do+ if ! git check-ref-format --branch "$branch" > /dev/null; then+ echo "Invalid SDK base branch: $branch"+ exit 1+ fi+ done+- name: Checkout repositoryuses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1with:@@ -77,7 +103,7 @@ jobs:id: prepare-python-sdkrun: |# Clone langfuse-python repository- git clone https://github.com/langfuse/langfuse-python.git ../langfuse-python+ git clone --branch "$PYTHON_SDK_BASE_BRANCH" https://github.com/langfuse/langfuse-python.git ../langfuse-pythoncd ../langfuse-pythongit config user.name "langfuse-bot"@@ -135,7 +161,7 @@ jobs:id: prepare-typescript-sdkrun: |# Clone langfuse-js repository- git clone https://github.com/langfuse/langfuse-js.git ../langfuse-js+ git clone --branch "$JS_SDK_BASE_BRANCH" https://github.com/langfuse/langfuse-js.git ../langfuse-jscd ../langfuse-js# Configure git@@ -163,9 +189,15 @@ jobs:fifi- # Install dependencies and format+ # Install dependencies, reserve a request slot in methods without+ # query params or a body so later query params never shift+ # requestOptions, and format. SDK branches without the script+ # (the v5.x line) keep Fern's signatures unchanged.corepack enablepnpm install+ if [ -f scripts/patch-generated-request-placeholders.mjs ]; then+ node scripts/patch-generated-request-placeholders.mjs+ fipnpm format# Check for changes and show diff for debugging@@ -238,14 +270,20 @@ jobs:NEW_PR_URL="$("$GH_BIN" pr create \--repo langfuse/langfuse-python \+ --base "$PYTHON_SDK_BASE_BRANCH" \--head "$BRANCH_NAME" \--title "feat(api): update API spec from langfuse/langfuse ${GITHUB_SHA::7}" \- --body "" \+ --body "Generated from langfuse/langfuse \`${GITHUB_REF_NAME}\` at ${GITHUB_SHA::7}." \"${REVIEWER_ARGS[@]}")"NEW_PR_NUMBER="${NEW_PR_URL##*/}"- # Only retire stale bot PRs after their replacement exists.- "$GH_BIN" pr list --repo langfuse/langfuse-python --author langfuse-bot --state open --json number --jq '.[].number' | while read -r pr_number; do+ # Only retire stale bot PRs after their replacement exists, and only+ # on push runs to main. Manual runs never close bot PRs, so an open+ # release-branch or hand-dispatched PR survives until merged or closed.+ if [ "$GITHUB_EVENT_NAME" != "push" ]; then+ exit 0+ fi+ "$GH_BIN" pr list --repo langfuse/langfuse-python --author langfuse-bot --base main --state open --json number --jq '.[].number' | while read -r pr_number; doif [ -n "$pr_number" ] && [ "$pr_number" != "$NEW_PR_NUMBER" ]; then"$GH_BIN" pr close --repo langfuse/langfuse-python "$pr_number"fi@@ -295,14 +333,20 @@ jobs:NEW_PR_URL="$("$GH_BIN" pr create \--repo langfuse/langfuse-js \+ --base "$JS_SDK_BASE_BRANCH" \--head "$BRANCH_NAME" \--title "feat(api): update API spec from langfuse/langfuse ${GITHUB_SHA::7}" \- --body "" \+ --body "Generated from langfuse/langfuse \`${GITHUB_REF_NAME}\` at ${GITHUB_SHA::7}." \"${REVIEWER_ARGS[@]}")"NEW_PR_NUMBER="${NEW_PR_URL##*/}"- # Only retire stale bot PRs after their replacement exists.- "$GH_BIN" pr list --repo langfuse/langfuse-js --author langfuse-bot --state open --json number --jq '.[].number' | while read -r pr_number; do+ # Only retire stale bot PRs after their replacement exists, and only+ # on push runs to main. Manual runs never close bot PRs, so an open+ # release-branch or hand-dispatched PR survives until merged or closed.+ if [ "$GITHUB_EVENT_NAME" != "push" ]; then+ exit 0+ fi+ "$GH_BIN" pr list --repo langfuse/langfuse-js --author langfuse-bot --base main --state open --json number --jq '.[].number' | while read -r pr_number; doif [ -n "$pr_number" ] && [ "$pr_number" != "$NEW_PR_NUMBER" ]; then"$GH_BIN" pr close --repo langfuse/langfuse-js "$pr_number"fidiff --git a/fern/apis/server/definition/commons.yml b/fern/apis/server/definition/commons.ymlindex 13c1aea1be..3ec7a75a93 100644--- a/fern/apis/server/definition/commons.yml+++ b/fern/apis/server/definition/commons.yml@@ -18,211 +18,6 @@ types:docs: ISO date after which the endpoint may stop working, when a removal date is committed.# Objects- # Source: web/src/features/public-api/types/traces.ts - APITrace, APIExtendedTrace, GetTraceV1Response- Trace:- properties:- id:- type: string- docs: The unique identifier of a trace- timestamp:- type: datetime- docs: The timestamp when the trace was created- name:- type: nullable<string>- docs: The name of the trace- input:- type: optional<unknown>- docs: The input data of the trace. Can be any JSON.- output:- type: optional<unknown>- docs: The output data of the trace. Can be any JSON.- sessionId:- type: nullable<string>- docs: The session identifier associated with the trace- release:- type: nullable<string>- docs: The release version of the application when the trace was created- version:- type: nullable<string>- docs: The version of the trace- userId:- type: nullable<string>- docs: The user identifier associated with the trace- metadata:- type: optional<map<string, unknown>>- docs: The metadata associated with the trace. Values can be any JSON; non-object metadata sent at ingestion is returned under the `metadata` key.- tags:- type: list<string>- docs: The tags associated with the trace.- public:- type: boolean- docs: Public traces are accessible via url without login- environment:- type: string- docs: The environment from which this trace originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.- TraceWithDetails: # GET /traces- extends: Trace- properties:- htmlPath:- type: string- docs: Path of trace in Langfuse UI- latency:- type: optional<nullable<double>>- docs: Latency of trace in seconds- totalCost:- type: optional<nullable<double>>- docs: Cost of trace in USD- observations:- type: optional<nullable<list<string>>>- docs: List of observation ids- scores:- type: optional<nullable<list<string>>>- docs: List of score ids- TraceWithFullDetails: # GET traces/[traceID]- extends: Trace- properties:- htmlPath:- type: string- docs: Path of trace in Langfuse UI- latency:- type: optional<nullable<double>>- docs: Latency of trace in seconds- totalCost:- type: optional<nullable<double>>- docs: Cost of trace in USD- observations:- type: list<ObservationsView>- docs: List of observations- scores:- type: list<ScoreV1>- docs: List of scores- _deprecation: optional<Deprecation>- # Source: web/src/features/public-api/types/sessions.ts - APISession- Session:- properties:- id: string- createdAt: datetime- projectId: string- environment:- type: string- docs: The environment from which this session originated.- SessionWithTraces:- extends: Session- properties:- traces: list<Trace>- _deprecation: optional<Deprecation>- # Source: web/src/features/public-api/types/observations.ts - APIObservation- Observation:- properties:- id:- type: string- docs: The unique identifier of the observation- traceId:- type: nullable<string>- docs: The trace ID associated with the observation- type:- type: string- docs: The type of the observation- name:- type: nullable<string>- docs: The name of the observation- startTime:- type: datetime- docs: The start time of the observation- endTime:- type: nullable<datetime>- docs: The end time of the observation.- completionStartTime:- type: nullable<datetime>- docs: The completion start time of the observation- model:- type: nullable<string>- docs: The model used for the observation- modelParameters:- type: unknown- docs: The parameters of the model used for the observation- input:- type: unknown- docs: The input data of the observation- version:- type: nullable<string>- docs: The version of the observation- metadata:- type: optional<map<string, unknown>>- docs: Additional metadata of the observation- output:- type: unknown- docs: The output data of the observation- usage:- type: Usage- docs: (Deprecated. Use usageDetails and costDetails instead.) The usage data of the observation- level:- type: ObservationLevel- docs: The level of the observation- statusMessage:- type: nullable<string>- docs: The status message of the observation- parentObservationId:- type: nullable<string>- docs: The parent observation ID- promptId:- type: nullable<string>- docs: The prompt ID associated with the observation- usageDetails:- type: map<string, integer>- docs: 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: map<string, double>- docs: 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- docs: The environment from which this observation originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.-- ObservationsView:- extends: Observation- properties:- promptName:- type: nullable<string>- docs: The name of the prompt associated with the observation- promptVersion:- type: nullable<integer>- docs: The version of the prompt associated with the observation- modelId:- type: nullable<string>- docs: The unique identifier of the model- inputPrice:- type: nullable<double>- docs: The price of the input in USD- outputPrice:- type: nullable<double>- docs: The price of the output in USD.- totalPrice:- type: nullable<double>- docs: The total price in USD.- calculatedInputCost:- type: nullable<double>- docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the input in USD- calculatedOutputCost:- type: nullable<double>- docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated cost of the output in USD- calculatedTotalCost:- type: nullable<double>- docs: (Deprecated. Use usageDetails and costDetails instead.) The calculated total cost in USD- latency:- type: nullable<double>- docs: The latency in seconds.- timeToFirstToken:- type: nullable<double>- docs: The time to the first token in seconds-- # Single-observation response (GET /observations/{observationId}); carries the- # deprecation signal without adding it to the shared ObservationsView (used as- # a list element and nested in TraceWithFullDetails).- ObservationsViewSingle:- extends: ObservationsView- properties:- _deprecation: optional<Deprecation>-# Source: web/src/features/public-api/types/observations.ts - APIObservationV2ObservationV2:docs: |@@ -434,83 +229,6 @@ types:properties:value: doublelabel: string- # Source: packages/shared/src/features/scores/interfaces/api/v1/schemas.ts - APIScoreSchemaV1- BaseScoreV1:- properties:- id: string- traceId: string- name: string- source: ScoreSource- observationId:- type: optional<nullable<string>>- docs: The observation ID associated with the score- timestamp: datetime- createdAt: datetime- updatedAt: datetime- authorUserId:- type: nullable<string>- docs: The user ID of the author- comment:- type: nullable<string>- docs: Comment on the score- metadata:- type: optional<map<string, unknown>>- docs: Metadata associated with the score- configId:- type: nullable<string>- docs: 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: nullable<string>- docs: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.- environment:- type: string- docs: The environment from which this score originated. Can be any lowercase alphanumeric string with hyphens and underscores that does not start with 'langfuse'.- NumericScoreV1:- extends: BaseScoreV1- properties:- value:- type: double- docs: The numeric value of the score- BooleanScoreV1:- extends: BaseScoreV1- properties:- value:- type: double- docs: The numeric value of the score. Equals 1 for "True" and 0 for "False"- stringValue:- type: string- docs: The string representation of the score value. Is inferred from the numeric value and equals "True" or "False"- CategoricalScoreV1:- extends: BaseScoreV1- properties:- value:- type: double- docs: Represents the numeric category mapping of the stringValue. If no config is linked, defaults to 0.- stringValue:- type: string- docs: The string representation of the score value. If no config is linked, can be any string. Otherwise, must map to a config category- TextScoreV1:- extends: BaseScoreV1- properties:- stringValue:- type: string- docs: The text content of the score (1-500 characters)- ScoreV1:- discriminant: "dataType"- union:- NUMERIC:- type: NumericScoreV1- docs: "Score with NUMERIC data type"- CATEGORICAL:- type: CategoricalScoreV1- docs: "Score with CATEGORICAL data type"- BOOLEAN:- type: BooleanScoreV1- docs: "Score with BOOLEAN data type"- TEXT:- type: TextScoreV1- docs: "Score with TEXT data type"-# Source: packages/shared/src/features/scores/interfaces/api/v2/schemas.ts - APIScoreSchemaV2BaseScore:properties:@@ -675,6 +393,9 @@ types:datasetName: stringcreatedAt: datetimeupdatedAt: datetime+ version:+ type: optional<datetime>+ docs: When this version of the dataset item became current. Listing dataset items with a `version` at or after this timestamp returns this item version, until the item is changed again. Self-hosted deployments that set `LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION=false` update items in place, so there it stays at the item's first write.mediaReferences:type: list<DatasetItemMediaReference>docs: Resolved Langfuse media references found in input, expectedOutput, and metadata.@@ -718,51 +439,6 @@ types:urlExpiry:type: stringdocs: The expiry date and time of the download URL- # Source: web/src/features/public-api/types/datasets.ts - APIDatasetRunItem- DatasetRunItem:- properties:- id: string- datasetRunId: string- datasetRunName: string- datasetItemId: string- traceId: string- observationId:- type: nullable<string>- docs: The observation ID associated with this run item- createdAt: datetime- updatedAt: datetime- # Source: web/src/features/public-api/types/datasets.ts - APIDatasetRun- DatasetRun:- properties:- id:- type: string- docs: Unique identifier of the dataset run- name:- type: string- docs: Name of the dataset run- description:- type: nullable<string>- docs: Description of the run- metadata:- type: unknown- docs: Metadata of the dataset run- datasetId:- type: string- docs: Id of the associated dataset- datasetName:- type: string- docs: Name of the associated dataset- createdAt:- type: datetime- docs: The date and time when the dataset run was created- updatedAt:- type: datetime- docs: The date and time when the dataset run was last updated- DatasetRunWithItems:- extends: DatasetRun- properties:- datasetRunItems: list<DatasetRunItem>- _deprecation: optional<Deprecation># Source: web/src/features/public-api/types/models.ts - APIModelDefinitionModel:docs: |@@ -1086,6 +762,13 @@ types:- CORRECTION- TEXT+ OpenAIUsage:+ docs: Usage interface of OpenAI for improved compatibility.+ properties:+ promptTokens: optional<integer>+ completionTokens: optional<integer>+ totalTokens: optional<integer>+errors:Error:status-code: 400diff --git a/fern/apis/server/definition/dataset-run-items.yml b/fern/apis/server/definition/dataset-run-items.ymldeleted file mode 100644index 79c8fe02db..0000000000--- a/fern/apis/server/definition/dataset-run-items.yml+++ /dev/null@@ -1,67 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- commons: ./commons.yml- pagination: ./utils/pagination.yml-service:- auth: true- base-path: /api/public- endpoints:- create:- availability:- status: deprecated- message: "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."- method: POST- docs: Create a dataset run item- path: /dataset-run-items- request: CreateDatasetRunItemRequest- response: commons.DatasetRunItem- list:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. In Langfuse v4, dataset run items are replaced by experiment items; use `GET /api/public/experiment-items?fromStartTime=<from>&toStartTime=<to>` instead. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- method: GET- docs: List dataset run items- path: /dataset-run-items- request:- name: ListDatasetRunItemsRequest- query-parameters:- datasetId: string- runName: string- page:- type: optional<integer>- docs: page number, starts at 1- limit:- type: optional<integer>- docs: limit of items per page- response: PaginatedDatasetRunItems--types:- CreateDatasetRunItemRequest:- properties:- runName: string- runDescription:- type: optional<string>- docs: Description of the run. If run exists, description will be updated.- metadata:- type: optional<unknown>- docs: Metadata of the dataset run, updates run if run already exists- datasetItemId: string- observationId: optional<string>- traceId:- type: optional<string>- docs: traceId should always be provided. For compatibility with older SDK versions it can also be inferred from the provided observationId.- datasetVersion:- type: optional<datetime>- docs: |- 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: optional<datetime>- docs: Optional timestamp to set the createdAt field of the dataset run item. If not provided or null, defaults to current timestamp.- PaginatedDatasetRunItems:- properties:- data: list<commons.DatasetRunItem>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>diff --git a/fern/apis/server/definition/datasets.yml b/fern/apis/server/definition/datasets.ymlindex d43b61a333..db825959de 100644--- a/fern/apis/server/definition/datasets.yml+++ b/fern/apis/server/definition/datasets.yml@@ -33,48 +33,6 @@ service:path: /v2/datasetsrequest: CreateDatasetRequestresponse: commons.Dataset- getRun:- availability:- status: deprecated- message: "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."- method: GET- docs: Get a dataset run and its items- path: /datasets/{datasetName}/runs/{runName}- path-parameters:- datasetName: string- runName: string- response: commons.DatasetRunWithItems- deleteRun:- availability:- status: deprecated- message: "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."- method: DELETE- docs: Delete a dataset run and all its run items. This action is irreversible.- path: /datasets/{datasetName}/runs/{runName}- path-parameters:- datasetName: string- runName: string- response: DeleteDatasetRunResponse- getRuns:- availability:- status: deprecated- message: "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."- method: GET- docs: Get dataset runs- path: /datasets/{datasetName}/runs- path-parameters:- datasetName: string- request:- name: GetDatasetRunsRequest- query-parameters:- page:- type: optional<integer>- docs: page number, starts at 1- limit:- type: optional<integer>- docs: limit of items per page- response: PaginatedDatasetRuns-types:PaginatedDatasets:properties:@@ -91,11 +49,3 @@ types:expectedOutputSchema:type: optional<unknown>docs: JSON Schema for validating dataset item expected outputs. When set, all new and existing dataset items will be validated against this schema.- PaginatedDatasetRuns:- properties:- data: list<commons.DatasetRun>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>- DeleteDatasetRunResponse:- properties:- message: stringdiff --git a/fern/apis/server/definition/experiments.yml b/fern/apis/server/definition/experiments.ymlindex 3af755ca03..15c936630e 100644--- a/fern/apis/server/definition/experiments.yml+++ b/fern/apis/server/definition/experiments.yml@@ -1,7 +1,7 @@# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.jsonimports:commons: ./commons.yml- scoresV3: ./scores-v3.yml+ scores: ./scores.ymlpagination: ./utils/pagination.ymlservice:@@ -150,7 +150,7 @@ types:type: optional<nullable<map<string, unknown>>>docs: Included only when `fields=metadata` is requested.scores:- type: optional<list<scoresV3.ScoreV3>>+ type: optional<list<scores.ScoreV3>>docs: Included only when `fields=scores` is requested. Contains scores directly attached to the experiment.ExperimentItemsResponse:@@ -197,5 +197,5 @@ types:type: optional<nullable<string>>docs: Included when `fields=experimentMetadata` is requested.scores:- type: optional<list<scoresV3.ScoreV3>>+ type: optional<list<scores.ScoreV3>>docs: Included only when `fields=scores` is requested. Contains item and trace scores only; experiment-level scores are returned by the experiments endpoint.diff --git a/fern/apis/server/definition/ingestion.yml b/fern/apis/server/definition/ingestion.ymldeleted file mode 100644index e6793f36e8..0000000000--- a/fern/apis/server/definition/ingestion.yml+++ /dev/null@@ -1,451 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- pagination: ./utils/pagination.yml- commons: ./commons.yml-service:- auth: true- base-path: /api/public- endpoints:- batch:- availability:- status: deprecated- message: "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."- docs: |- **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.- method: POST- path: /ingestion- request:- name: IngestionRequest- body:- properties:- batch:- type: list<IngestionEvent>- docs: "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:- type: optional<unknown>- docs: Optional. Metadata field used by the Langfuse SDKs for debugging.- response:- type: IngestionResponse- status-code: 207- examples:- # Trace Create Request- - request:- batch:- - id: abcdef-1234-5678-90ab- timestamp: "2022-01-01T00:00:00.000Z"- type: "trace-create"- body:- id: abcdef-1234-5678-90ab- timestamp: "2022-01-01T00:00:00.000Z"- environment: "production"- name: "My Trace"- userId: "1234-5678-90ab-cdef"- input: "My input"- output: "My output"- sessionId: "1234-5678-90ab-cdef"- release: "1.0.0"- version: "1.0.0"- metadata: "My metadata"- tags: ["tag1", "tag2"]- public: true- response:- body:- successes:- - id: abcdef-1234-5678-90ab- status: 201- errors: []-- # Observation Create Request- - request:- batch:- - id: abcdef-1234-5678-90ab- timestamp: "2022-01-01T00:00:00.000Z"- type: "span-create"- body:- id: abcdef-1234-5678-90ab- traceId: "1234-5678-90ab-cdef"- startTime: "2022-01-01T00:00:00.000Z"- environment: "test"- response:- body:- successes:- - id: abcdef-1234-5678-90ab- status: 201- errors: []-- # Score Create Request- - request:- batch:- - id: abcdef-1234-5678-90ab- timestamp: "2022-01-01T00:00:00.000Z"- type: "score-create"- body:- id: abcdef-1234-5678-90ab- traceId: "1234-5678-90ab-cdef"- name: "My Score"- value: 0.9- environment: "default"- response:- body:- successes:- - id: abcdef-1234-5678-90ab- status: 201- errors: []--types:- IngestionEvent:- discriminant: "type"- union:- trace-create:- type: TraceEvent- docs: "Creates a new trace. Upserts on id for updates if trace with id exists. 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."- score-create:- type: ScoreEvent- docs: Creates a new score. Upserts on id for updates if score with id exists.- span-create:- type: CreateSpanEvent- docs: "Creates a new span. 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."- span-update:- type: UpdateSpanEvent- docs: "Updates span based on id. 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."- generation-create:- type: CreateGenerationEvent- docs: "Creates a new generation. 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."- generation-update:- type: UpdateGenerationEvent- docs: "Updates a generation based on id. 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."- event-create:- type: CreateEventEvent- docs: "Creates an event. 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."-- # both are legacy- observation-create:- type: CreateObservationEvent- docs: "Deprecated event type. 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."- observation-update:- type: UpdateObservationEvent- docs: "Deprecated event type. 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."-- ObservationType:- enum:- - SPAN- - GENERATION- - EVENT- - AGENT- - TOOL- - CHAIN- - RETRIEVER- - EVALUATOR- - EMBEDDING- - GUARDRAIL-- IngestionUsage:- discriminated: false- union:- - commons.Usage- - OpenAIUsage-- OpenAIUsage:- docs: Usage interface of OpenAI for improved compatibility.- properties:- promptTokens: optional<integer>- completionTokens: optional<integer>- totalTokens: optional<integer>-- OptionalObservationBody:- properties:- traceId: optional<string>- name: optional<string>- startTime: optional<datetime>- metadata: optional<unknown>- input: optional<unknown>- output: optional<unknown>- level: optional<commons.ObservationLevel>- statusMessage: optional<string>- parentObservationId: optional<string>- version: optional<string>- environment: optional<string>-- CreateEventBody:- extends: OptionalObservationBody- properties:- id: optional<string>-- UpdateEventBody:- extends: OptionalObservationBody- properties:- id: string-- CreateSpanBody:- extends: CreateEventBody- properties:- endTime: optional<datetime>-- UpdateSpanBody:- extends: UpdateEventBody- properties:- endTime: optional<datetime>-- CreateGenerationBody:- extends: CreateSpanBody- properties:- completionStartTime: optional<datetime>- model: optional<string>- modelParameters: optional<map<string, commons.MapValue>>- usage: optional<IngestionUsage>- usageDetails: optional<UsageDetails>- costDetails: optional<map<string, double>>- promptName: optional<string>- promptVersion: optional<integer>-- UpdateGenerationBody:- extends: UpdateSpanBody- properties:- completionStartTime: optional<datetime>- model: optional<string>- modelParameters: optional<map<string, commons.MapValue>>- usage: optional<IngestionUsage>- promptName: optional<string>- usageDetails: optional<UsageDetails>- costDetails: optional<map<string, double>>- promptVersion: optional<integer>-- ObservationBody:- properties:- id: optional<string>- traceId: optional<string>- type: ObservationType- name: optional<string>- startTime: optional<datetime>- endTime: optional<datetime>- completionStartTime: optional<datetime>- model: optional<string>- modelParameters: optional<map<string, commons.MapValue>>- input: optional<unknown>- version: optional<string>- metadata: optional<unknown>- output: optional<unknown>- usage: optional<commons.Usage>- level: optional<commons.ObservationLevel>- statusMessage: optional<string>- parentObservationId: optional<string>- environment: optional<string>-- TraceBody:- properties:- id: optional<string>- timestamp: optional<datetime>- name: optional<string>- userId: optional<string>- input: optional<unknown>- output: optional<unknown>- sessionId: optional<string>- release: optional<string>- version: optional<string>- metadata: optional<unknown>- tags: optional<list<string>>- environment: optional<string>- public:- type: optional<boolean>- docs: Make trace publicly accessible via url-- ScoreBody:- properties:- id: optional<string>- traceId: optional<string>- sessionId: optional<string>- observationId: optional<string>- datasetRunId: optional<string>- name:- type: string- docs: The name of the score. Always overrides "output" for correction scores.- environment: optional<string>- queueId:- type: optional<string>- docs: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.- value:- type: commons.CreateScoreValue- docs: 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: optional<string>- metadata: optional<unknown>- dataType:- type: optional<commons.ScoreDataType>- docs: When set, must match the score value's type. If not set, will be inferred from the score value or config- configId:- type: optional<string>- docs: 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- examples:- - value:- name: "novelty"- value: 0.9- traceId: "cdef-1234-5678-90ab"- - value:- name: "consistency"- value: 1.2- dataType: "NUMERIC"- traceId: "cdef-1234-5678-90ab"- - value:- name: "accuracy"- value: 0.9- dataType: "NUMERIC"- configId: "9203-4567-89ab-cdef"- traceId: "cdef-1234-5678-90ab"- - value:- name: "toxicity"- value: "not toxic"- traceId: "cdef-1234-5678-90ab"- - value:- name: "correctness"- value: "partially correct"- dataType: "CATEGORICAL"- configId: "1234-5678-90ab-cdef"- traceId: "cdef-1234-5678-90ab"- - value:- name: "hallucination"- value: 0- dataType: "BOOLEAN"- traceId: "cdef-1234-5678-90ab"- - value:- name: "helpfulness"- value: 1- dataType: "BOOLEAN"- configId: "1234-5678-90ab-cdef"- traceId: "cdef-1234-5678-90ab"- - value:- name: "contextrelevant"- value: "not relevant"- sessionId: "abyt-1234-5678-80ab"- - value:- name: "hallucination"- value: 0- datasetRunId: "7891-5678-90ab-hijk"-- BaseEvent:- properties:- id:- type: string- docs: UUID v4 that identifies the event- timestamp:- type: string- docs: "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:- type: optional<unknown>- docs: Optional. Metadata field used by the Langfuse SDKs for debugging.-- TraceEvent:- docs: "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."- extends: BaseEvent- properties:- body: TraceBody-- CreateObservationEvent:- docs: "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."- extends: BaseEvent- properties:- body: ObservationBody-- UpdateObservationEvent:- docs: "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."- extends: BaseEvent- properties:- body: ObservationBody-- ScoreEvent:- extends: BaseEvent- properties:- body: ScoreBody-- CreateGenerationEvent:- docs: "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."- extends: BaseEvent- properties:- body: CreateGenerationBody-- UpdateGenerationEvent:- docs: "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."- extends: BaseEvent- properties:- body: UpdateGenerationBody-- CreateSpanEvent:- docs: "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."- extends: BaseEvent- properties:- body: CreateSpanBody-- UpdateSpanEvent:- docs: "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."- extends: BaseEvent- properties:- body: UpdateSpanBody-- CreateEventEvent:- docs: "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."- extends: BaseEvent- properties:- body: CreateEventBody-- IngestionSuccess:- properties:- id: string- status: integer-- IngestionError:- properties:- id: string- status: integer- message: optional<string>- error: optional<unknown>-- IngestionResponse:- properties:- successes: list<IngestionSuccess>- errors: list<IngestionError>- _deprecation: optional<commons.Deprecation>-- OpenAICompletionUsageSchema:- docs: OpenAI Usage schema from (Chat-)Completion APIs- properties:- prompt_tokens: integer- completion_tokens: integer- total_tokens: integer- prompt_tokens_details: optional<map<string, optional<integer>>>- completion_tokens_details: optional<map<string, optional<integer>>>-- OpenAIResponseUsageSchema:- docs: OpenAI Usage schema from Response API- properties:- input_tokens: integer- output_tokens: integer- total_tokens: integer- input_tokens_details: optional<map<string, optional<integer>>>- output_tokens_details: optional<map<string, optional<integer>>>-- UsageDetails:- discriminated: false- union:- - map<string, integer>- - OpenAICompletionUsageSchema- - OpenAIResponseUsageSchemadiff --git a/fern/apis/server/definition/legacy/metrics-v1.yml b/fern/apis/server/definition/legacy/metrics-v1.ymldeleted file mode 100644index 18317e60e7..0000000000--- a/fern/apis/server/definition/legacy/metrics-v1.yml+++ /dev/null@@ -1,78 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- pagination: ../utils/pagination.yml- commons: ../commons.yml-service:- auth: true- base-path: /api/public- endpoints:- metrics:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. Use `GET /api/public/v2/metrics?query=<urlencoded json query>` instead. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: |- 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).- method: GET- path: /metrics- request:- name: GetMetricsRequest- query-parameters:- query:- type: string- docs: |- 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)- }- }- ```- response: MetricsResponse-types:- MetricsResponse:- properties:- data:- type: list<map<string, unknown>>- docs: |- 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: optional<commons.Deprecation>diff --git a/fern/apis/server/definition/legacy/observations-v1.yml b/fern/apis/server/definition/legacy/observations-v1.ymldeleted file mode 100644index 08d83bfbe8..0000000000--- a/fern/apis/server/definition/legacy/observations-v1.yml+++ /dev/null@@ -1,169 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- commons: ../commons.yml- pagination: ../utils/pagination.yml-service:- auth: true- base-path: /api/public- endpoints:- get:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` instead. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: Get a observation- method: GET- path: /observations/{observationId}- path-parameters:- observationId:- type: string- docs: The unique langfuse identifier of an observation, can be an event, span or generation- response: commons.ObservationsViewSingle- getMany:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. Use `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>` instead. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: |- 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.- method: GET- path: /observations- request:- name: GetObservationsRequest- query-parameters:- page:- type: optional<integer>- docs: Page number, starts at 1.- limit:- type: optional<integer>- docs: Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit.- name: optional<string>- userId: optional<string>- type: optional<string>- traceId: optional<string>- level:- type: optional<commons.ObservationLevel>- docs: Optional filter for observations with a specific level (e.g. "DEBUG", "DEFAULT", "WARNING", "ERROR").- parentObservationId: optional<string>- environment:- type: optional<string>- allow-multiple: true- docs: Optional filter for observations where the environment is one of the provided values.- fromStartTime:- type: optional<datetime>- docs: Retrieve only observations with a start_time on or after this datetime (ISO 8601).- toStartTime:- type: optional<datetime>- docs: Retrieve only observations with a start_time before this datetime (ISO 8601).- version:- type: optional<string>- docs: Optional filter to only include observations with a certain version.- filter:- type: optional<string>- docs: |- 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"- }- ]- ```- response: ObservationsViews--types:- Observations:- properties:- data: list<commons.Observation>- meta: pagination.MetaResponse-- ObservationsViews:- properties:- data: list<commons.ObservationsView>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>diff --git a/fern/apis/server/definition/legacy/score-v1.yml b/fern/apis/server/definition/legacy/score-v1.ymldeleted file mode 100644index 54560bd070..0000000000--- a/fern/apis/server/definition/legacy/score-v1.yml+++ /dev/null@@ -1,13 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-service:- auth: true- base-path: /api/public- endpoints:- delete:- docs: Delete a score (supports both trace and session scores)- method: DELETE- path: /scores/{scoreId}- path-parameters:- scoreId:- type: string- docs: The unique langfuse identifier of a scorediff --git a/fern/apis/server/definition/scores-v3.yml b/fern/apis/server/definition/scores-v3.ymldeleted file mode 100644index d2c439b070..0000000000--- a/fern/apis/server/definition/scores-v3.yml+++ /dev/null@@ -1,252 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- commons: ./commons.yml- pagination: ./utils/pagination.yml--service:- auth: true- base-path: /api/public- endpoints:- getManyV3:- docs: |- 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.- method: GET- path: /v3/scores- request:- name: GetScoresV3Request- query-parameters:- limit:- type: optional<integer>- docs: Number of items per page. Maximum 100, default 50. Requests with a limit greater than 100 return HTTP 400.- cursor:- type: optional<string>- docs: URL-safe base64 (base64url) cursor for pagination. Use the cursor from the previous response to get the next page. Absent on the final page.- fields:- type: optional<string>- docs: >- 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.- id:- type: optional<string>- docs: Comma-separated list of score IDs to filter by (OR within, AND across filters).- name:- type: optional<string>- docs: Comma-separated list of score names to filter by.- source:- type: optional<string>- docs: Comma-separated list of score sources to filter by (e.g. API, ANNOTATION, EVAL). Case-insensitive — `api` and `API` are equivalent.- dataType:- type: optional<string>- docs: 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.- environment:- type: optional<string>- docs: Comma-separated list of environments to filter by.- configId:- type: optional<string>- docs: Comma-separated list of score config IDs to filter by.- queueId:- type: optional<string>- docs: Comma-separated list of annotation queue IDs to filter by.- authorUserId:- type: optional<string>- docs: Comma-separated list of author user IDs to filter by.- value:- type: optional<string>- docs: >- 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.- valueMin:- type: optional<double>- docs: Inclusive lower bound on the numeric value. Requires dataType=NUMERIC as a single value; otherwise the request returns HTTP 400.- valueMax:- type: optional<double>- docs: Inclusive upper bound on the numeric value. Requires dataType=NUMERIC as a single value; otherwise the request returns HTTP 400.- traceId:- type: optional<string>- docs: 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.- sessionId:- type: optional<string>- docs: Comma-separated list of session IDs to filter by. Mutually exclusive with traceId, observationId, experimentId.- observationId:- type: optional<string>- docs: >- 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.- experimentId:- type: optional<string>- docs: Comma-separated list of dataset run IDs (experiment IDs) to filter by. Mutually exclusive with traceId, sessionId, observationId.- fromTimestamp:- type: optional<datetime>- docs: Inclusive lower bound on the score timestamp.- toTimestamp:- type: optional<datetime>- docs: Exclusive upper bound on the score timestamp.- response: GetScoresV3Response--types:- ScoreSubjectTraceV3:- properties:- id:- type: string- docs: The trace ID.-- ScoreSubjectObservationV3:- properties:- id:- type: string- docs: The observation ID.- traceId:- type: optional<string>- docs: The parent trace ID, if available.-- ScoreSubjectSessionV3:- properties:- id:- type: string- docs: The session ID.-- ScoreSubjectExperimentV3:- properties:- id:- type: string- docs: The dataset run ID (experiment ID).-- ScoreSubjectV3:- docs: A reference to the entity this score is attached to. Discriminated by "kind" — one of trace, observation, session, or experiment.- discriminant: kind- union:- trace:- type: ScoreSubjectTraceV3- docs: Subject is a trace-level score.- observation:- type: ScoreSubjectObservationV3- docs: Subject is an observation-level score scoped to a trace.- session:- type: ScoreSubjectSessionV3- docs: Subject is a session-level score.- experiment:- type: ScoreSubjectExperimentV3- docs: Subject is a dataset run (experiment) score.-- # Score model types keep the V3 suffix because commons.yml already declares- # Score, NumericScore, BooleanScore, etc. for the v1/v2 API surface.- # Fern uses a flat global namespace, so those names are taken.- BaseScoreV3:- properties:- id: string- projectId: string- name: string- source: commons.ScoreSource- timestamp: datetime- environment:- type: string- docs: The environment from which this score originated.- createdAt: datetime- updatedAt: datetime- comment:- type: optional<nullable<string>>- docs: Optional comment attached to the score. Present when "details" is included in the fields parameter.- configId:- type: optional<nullable<string>>- docs: The score config ID, if this score was created from a config. Present when "details" is included in the fields parameter.- metadata:- type: optional<map<string, unknown>>- docs: Arbitrary metadata attached to the score. Present when "details" is included in the fields parameter.- authorUserId:- type: optional<nullable<string>>- docs: The user who created this score, if available. Present when "annotation" is included in the fields parameter.- queueId:- type: optional<nullable<string>>- docs: The annotation queue this score belongs to, if any. Present when "annotation" is included in the fields parameter.- subject:- type: optional<ScoreSubjectV3>- docs: The entity this score is attached to (trace, observation, session, or experiment). Present when "subject" is included in the fields parameter.-- NumericScoreV3:- extends: BaseScoreV3- properties:- value:- type: double- docs: The numeric value of the score.-- BooleanScoreV3:- extends: BaseScoreV3- properties:- value:- type: boolean- docs: The boolean value of the score.-- CategoricalScoreV3:- extends: BaseScoreV3- properties:- value:- type: string- docs: The string category value of the score.-- TextScoreV3:- extends: BaseScoreV3- properties:- value:- type: string- docs: The text content of the score.-- CorrectionScoreV3:- extends: BaseScoreV3- properties:- value:- type: string- docs: The correction content of the score. Empty string if not set.-- ScoreV3:- discriminant: dataType- union:- NUMERIC:- type: NumericScoreV3- docs: Score with NUMERIC data type. Value is a number.- BOOLEAN:- type: BooleanScoreV3- docs: Score with BOOLEAN data type. Value is a boolean.- CATEGORICAL:- type: CategoricalScoreV3- docs: Score with CATEGORICAL data type. Value is a string category.- TEXT:- type: TextScoreV3- docs: Score with TEXT data type. Value is a string.- CORRECTION:- type: CorrectionScoreV3- docs: Score with CORRECTION data type. Value is the correction string.-- GetScoresV3Meta:- extends:- - pagination.CursorMetaResponse- properties:- limit: integer-- GetScoresV3Response:- properties:- data: list<ScoreV3>- meta: GetScoresV3Metadiff --git a/fern/apis/server/definition/scores.yml b/fern/apis/server/definition/scores.ymlindex 98ea9abfa6..6a6f9805e9 100644--- a/fern/apis/server/definition/scores.yml+++ b/fern/apis/server/definition/scores.yml@@ -1,123 +1,132 @@# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.jsonimports:- pagination: ./utils/pagination.ymlcommons: ./commons.yml+ pagination: ./utils/pagination.ymlservice:auth: truebase-path: /api/publicendpoints:create:docs: >- Create scores asynchronously. Single score: 200 with ID. Batch: 202 if accepted,+ Create scores asynchronously from a list of scores. Returns 202 if all scores are accepted,or 207 with accepted/rejected counts and error messages. Do not automatically retry a 207 batch.- The generated reference shows only 200; batches return 202 or 207.+ The generated reference shows only 200; the endpoint returns 202 or 207.method: POSTpath: /scoresrequest: CreateScoresRequestresponse: CreateScoresResponse- get-many:- availability:- status: deprecated- message: "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."- docs: Get a list of scores (supports both trace and session scores)++ delete:+ docs: Delete a score (supports both trace and session scores)+ method: DELETE+ path: /scores/{scoreId}+ path-parameters:+ scoreId:+ type: string+ docs: The unique langfuse identifier of a score++ getMany:+ docs: |+ 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.method: GET- path: /v2/scores+ path: /v3/scoresrequest:- name: GetScoresRequest+ name: GetScoresV3Requestquery-parameters:- page:- type: optional<integer>- docs: Page number, starts at 1.limit:type: optional<integer>- docs: 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.- userId:+ docs: Number of items per page. Maximum 100, default 50. Requests with a limit greater than 100 return HTTP 400.+ cursor:type: optional<string>- docs: Retrieve only scores with this userId associated to the trace.- name:+ docs: URL-safe base64 (base64url) cursor for pagination. Use the cursor from the previous response to get the next page. Absent on the final page.+ fields:type: optional<string>- docs: Retrieve only scores with this name.- fromTimestamp:- type: optional<datetime>- docs: Optional filter to only include scores created on or after a certain datetime (ISO 8601)- toTimestamp:- type: optional<datetime>- docs: Optional filter to only include scores created before a certain datetime (ISO 8601)- environment:+ docs: >+ 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.+ id:type: optional<string>- allow-multiple: true- docs: Optional filter for scores where the environment is one of the provided values.- source:- type: optional<commons.ScoreSource>- docs: Retrieve only scores from a specific source.- operator:+ docs: Comma-separated list of score IDs to filter by (OR within, AND across filters).+ name:type: optional<string>- docs: Retrieve only scores with <operator> value.- value:- type: optional<double>- docs: Retrieve only scores with <operator> value.- scoreIds:+ docs: Comma-separated list of score names to filter by.+ source:type: optional<string>- docs: Comma-separated list of score IDs to limit the results to.- configId:+ docs: Comma-separated list of score sources to filter by (e.g. API, ANNOTATION, EVAL). Case-insensitive — `api` and `API` are equivalent.+ dataType:type: optional<string>- docs: Retrieve only scores with a specific configId.- sessionId:+ docs: 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.+ environment:type: optional<string>- docs: Retrieve only scores with a specific sessionId.- datasetRunId:+ docs: Comma-separated list of environments to filter by.+ configId:type: optional<string>- docs: Retrieve only scores with a specific datasetRunId.- traceId:+ docs: Comma-separated list of score config IDs to filter by.+ queueId:type: optional<string>- docs: Retrieve only scores with a specific traceId.- observationId:+ docs: Comma-separated list of annotation queue IDs to filter by.+ authorUserId:type: optional<string>- docs: Comma-separated list of observation IDs to filter scores by.- queueId:+ docs: Comma-separated list of author user IDs to filter by.+ value:type: optional<string>- docs: Retrieve only scores with a specific annotation queueId.- dataType:- type: optional<commons.ScoreDataType>- docs: Retrieve only scores with a specific dataType.- traceTags:+ docs: >+ 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.+ valueMin:+ type: optional<double>+ docs: Inclusive lower bound on the numeric value. Requires dataType=NUMERIC as a single value; otherwise the request returns HTTP 400.+ valueMax:+ type: optional<double>+ docs: Inclusive upper bound on the numeric value. Requires dataType=NUMERIC as a single value; otherwise the request returns HTTP 400.+ traceId:type: optional<string>- allow-multiple: true- docs: Only scores linked to traces that include all of these tags will be returned.- fields:+ docs: 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.+ sessionId:type: optional<string>- docs: "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."- filter:+ docs: Comma-separated list of session IDs to filter by. Mutually exclusive with traceId, observationId, experimentId.+ observationId:type: optional<string>docs: >- 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).- response: GetScoresResponse- get-by-id:- availability:- status: deprecated- message: "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."- docs: Get a score (supports both trace and session scores)- method: GET- path: /v2/scores/{scoreId}- path-parameters:- scoreId:- type: string- docs: The unique langfuse identifier of a score- response: commons.Score+ 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.+ experimentId:+ type: optional<string>+ docs: Comma-separated list of dataset run IDs (experiment IDs) to filter by. Mutually exclusive with traceId, sessionId, observationId.+ fromTimestamp:+ type: optional<datetime>+ docs: Inclusive lower bound on the score timestamp.+ toTimestamp:+ type: optional<datetime>+ docs: Exclusive upper bound on the score timestamp.+ response: GetScoresV3Responsetypes:CreateScoresRequest:- discriminated: false- union:- - CreateScoreRequest- - CreateScoreBatchRequest-- CreateScoreBatchRequest:type: list<CreateScoreRequest>examples:- value:@@ -157,6 +166,9 @@ types:source:type: optional<CreateScoreSource>docs: The source of the score. Defaults to API. Set to ANNOTATION to prefill scores (e.g. from an LLM) for a human reviewer to verify in an annotation queue. When source is ANNOTATION, a configId is required unless dataType is CORRECTION. EVAL is reserved for internal evaluator outputs and is not accepted on this endpoint.+ timestamp:+ type: optional<datetime>+ docs: The timestamp of the score, as an ISO 8601 datetime with a timezone offset. Defaults to the time the request is received. To update an existing score, send it again with the same id and timestamp.examples:- value:name: "novelty"@@ -224,7 +236,6 @@ types:# also match 207 bodies and hide rejected scores.union:- CreateScoreBatchResults- - CreateScoreResponse- CreateScoreBatchResponseCreateScoreBatchResponse:@@ -232,74 +243,226 @@ types:properties:message: literal<"Accepted">- CreateScoreResponse:+ CreateScoreBatchResults:+ docs: Acceptance counts and errors (HTTP 207).+ properties:+ accepted: integer+ rejected: integer+ errors: list<CreateScoreBatchError>++ CreateScoreBatchError:+ properties:+ message: string++ ScoreSubjectTraceV3:properties:id:type: string- docs: The id of the created object in Langfuse+ docs: The trace ID.- GetScoresResponseTraceData:+ ScoreSubjectObservationV3:properties:- userId:+ id:+ type: string+ docs: The observation ID.+ traceId:type: optional<string>- docs: The user ID associated with the trace referenced by score- tags:- type: optional<list<string>>- docs: A list of tags associated with the trace referenced by score+ docs: The parent trace ID, if available.++ ScoreSubjectSessionV3:+ properties:+ id:+ type: string+ docs: The session ID.++ ScoreSubjectExperimentV3:+ properties:+ id:+ type: string+ docs: The dataset run ID (experiment ID).++ ScoreSubjectV3:+ docs: A reference to the entity this score is attached to. Discriminated by "kind" — one of trace, observation, session, or experiment.+ discriminant: kind+ union:+ trace:+ type: ScoreSubjectTraceV3+ docs: Subject is a trace-level score.+ observation:+ type: ScoreSubjectObservationV3+ docs: Subject is an observation-level score scoped to a trace.+ session:+ type: ScoreSubjectSessionV3+ docs: Subject is a session-level score.+ experiment:+ type: ScoreSubjectExperimentV3+ docs: Subject is a dataset run (experiment) score.++ # Score model types keep the V3 suffix because commons.yml already declares+ # Score, NumericScore, BooleanScore, etc. for the v1/v2 API surface.+ # Fern uses a flat global namespace, so those names are taken.+ BaseScoreV3:+ properties:+ id: string+ projectId: string+ name: string+ source: commons.ScoreSource+ timestamp: datetimeenvironment:- type: optional<string>- docs: The environment of the trace referenced by score- sessionId:- type: optional<string>- docs: The session ID associated with the trace referenced by score+ type: string+ docs: The environment from which this score originated.+ createdAt: datetime+ updatedAt: datetime+ comment:+ type: optional<nullable<string>>+ docs: Optional comment attached to the score. Present when "details" is included in the fields parameter.+ configId:+ type: optional<nullable<string>>+ docs: The score config ID, if this score was created from a config. Present when "details" is included in the fields parameter.+ metadata:+ type: optional<map<string, unknown>>+ docs: Arbitrary metadata attached to the score. Present when "details" is included in the fields parameter.+ authorUserId:+ type: optional<nullable<string>>+ docs: The user who created this score, if available. Present when "annotation" is included in the fields parameter.+ queueId:+ type: optional<nullable<string>>+ docs: The annotation queue this score belongs to, if any. Present when "annotation" is included in the fields parameter.+ subject:+ type: optional<ScoreSubjectV3>+ docs: The entity this score is attached to (trace, observation, session, or experiment). Present when "subject" is included in the fields parameter.- GetScoresResponseDataNumeric:- extends: commons.NumericScore+ NumericScoreV3:+ extends: BaseScoreV3properties:- trace: optional<GetScoresResponseTraceData>+ value:+ type: double+ docs: The numeric value of the score.- GetScoresResponseDataCategorical:- extends: commons.CategoricalScore+ BooleanScoreV3:+ extends: BaseScoreV3properties:- trace: optional<GetScoresResponseTraceData>+ value:+ type: boolean+ docs: The boolean value of the score.- GetScoresResponseDataBoolean:- extends: commons.BooleanScore+ CategoricalScoreV3:+ extends: BaseScoreV3properties:- trace: optional<GetScoresResponseTraceData>+ value:+ type: string+ docs: The string category value of the score.- GetScoresResponseDataCorrection:- extends: commons.CorrectionScore+ TextScoreV3:+ extends: BaseScoreV3properties:- trace: optional<GetScoresResponseTraceData>+ value:+ type: string+ docs: The text content of the score.- GetScoresResponseDataText:- extends: commons.TextScore+ CorrectionScoreV3:+ extends: BaseScoreV3properties:- trace: optional<GetScoresResponseTraceData>+ value:+ type: string+ docs: The correction content of the score. Empty string if not set.- GetScoresResponseData:+ ScoreV3:discriminant: dataTypeunion:- NUMERIC: GetScoresResponseDataNumeric- CATEGORICAL: GetScoresResponseDataCategorical- BOOLEAN: GetScoresResponseDataBoolean- CORRECTION: GetScoresResponseDataCorrection- TEXT: GetScoresResponseDataText+ NUMERIC:+ type: NumericScoreV3+ docs: Score with NUMERIC data type. Value is a number.+ BOOLEAN:+ type: BooleanScoreV3+ docs: Score with BOOLEAN data type. Value is a boolean.+ CATEGORICAL:+ type: CategoricalScoreV3+ docs: Score with CATEGORICAL data type. Value is a string category.+ TEXT:+ type: TextScoreV3+ docs: Score with TEXT data type. Value is a string.+ CORRECTION:+ type: CorrectionScoreV3+ docs: Score with CORRECTION data type. Value is the correction string.- GetScoresResponse:+ GetScoresV3Meta:+ extends:+ - pagination.CursorMetaResponseproperties:- data: list<GetScoresResponseData>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>+ limit: integer- CreateScoreBatchResults:- docs: Acceptance counts and errors (HTTP 207).+ GetScoresV3Response:properties:- accepted: integer- rejected: integer- errors: list<CreateScoreBatchError>-- CreateScoreBatchError:+ data: list<ScoreV3>+ meta: GetScoresV3Meta+ ScoreBody:properties:- message: string+ id: optional<string>+ traceId: optional<string>+ sessionId: optional<string>+ observationId: optional<string>+ datasetRunId: optional<string>+ name:+ type: string+ docs: The name of the score. Always overrides "output" for correction scores.+ environment: optional<string>+ queueId:+ type: optional<string>+ docs: The annotation queue referenced by the score. Indicates if score was initially created while processing annotation queue.+ value:+ type: commons.CreateScoreValue+ docs: 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: optional<string>+ metadata: optional<unknown>+ dataType:+ type: optional<commons.ScoreDataType>+ docs: When set, must match the score value's type. If not set, will be inferred from the score value or config+ configId:+ type: optional<string>+ docs: 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+ examples:+ - value:+ name: "novelty"+ value: 0.9+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "consistency"+ value: 1.2+ dataType: "NUMERIC"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "accuracy"+ value: 0.9+ dataType: "NUMERIC"+ configId: "9203-4567-89ab-cdef"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "toxicity"+ value: "not toxic"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "correctness"+ value: "partially correct"+ dataType: "CATEGORICAL"+ configId: "1234-5678-90ab-cdef"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "hallucination"+ value: 0+ dataType: "BOOLEAN"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "helpfulness"+ value: 1+ dataType: "BOOLEAN"+ configId: "1234-5678-90ab-cdef"+ traceId: "cdef-1234-5678-90ab"+ - value:+ name: "contextrelevant"+ value: "not relevant"+ sessionId: "abyt-1234-5678-80ab"+ - value:+ name: "hallucination"+ value: 0+ datasetRunId: "7891-5678-90ab-hijk"diff --git a/fern/apis/server/definition/sessions.yml b/fern/apis/server/definition/sessions.ymldeleted file mode 100644index b673df603a..0000000000--- a/fern/apis/server/definition/sessions.yml+++ /dev/null@@ -1,65 +0,0 @@-# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- pagination: ./utils/pagination.yml- commons: ./commons.yml-service:- auth: true- base-path: /api/public- endpoints:- list:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. In Langfuse v4, read session data via `GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: |- Get sessions.-- This legacy endpoint is not recommended for new data extraction workflows.- Use the v2 observations endpoint with a bounded time range and group rows by- `sessionId` instead:- `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.- method: GET- path: /sessions- request:- name: GetSessionsRequest- query-parameters:- page:- type: optional<integer>- docs: Page number, starts at 1- limit:- type: optional<integer>- docs: Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit.- fromTimestamp:- type: optional<datetime>- docs: Optional filter to only include sessions created on or after a certain datetime (ISO 8601)- toTimestamp:- type: optional<datetime>- docs: Optional filter to only include sessions created before a certain datetime (ISO 8601)- environment:- type: optional<string>- allow-multiple: true- docs: Optional filter for sessions where the environment is one of the provided values.- response: PaginatedSessions- get:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. In Langfuse v4, read session data via `GET /api/public/v2/observations?filter=<urlencoded sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: |- Get a session.-- Please note that `traces` on this endpoint are not paginated. For large- sessions or new data extraction workflows, use the v2 observations endpoint- with a URL-encoded `sessionId` filter and a bounded time range:- `GET /api/public/v2/observations?filter=<sessionId filter>&fromStartTime=<from>&toStartTime=<to>`.- method: GET- path: /sessions/{sessionId}- path-parameters:- sessionId:- type: string- docs: The unique id of a session- response: commons.SessionWithTraces-types:- PaginatedSessions:- properties:- data: list<commons.Session>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>diff --git a/fern/apis/server/definition/trace.yml b/fern/apis/server/definition/trace.ymlindex ce93e784d8..0604baedd2 100644--- a/fern/apis/server/definition/trace.yml+++ b/fern/apis/server/definition/trace.yml@@ -1,29 +1,8 @@# yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json-imports:- pagination: ./utils/pagination.yml- commons: ./commons.ymlservice:auth: truebase-path: /api/publicendpoints:- get:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. In Langfuse v4, read span and trace data via `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: Get a specific trace- method: GET- path: /traces/{traceId}- request:- name: GetTraceRequest- query-parameters:- fields:- type: optional<string>- docs: "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'."- path-parameters:- traceId:- type: string- docs: The unique langfuse identifier of a trace- response: commons.TraceWithFullDetailsdelete:docs: Delete a specific tracemethod: DELETE@@ -33,162 +12,6 @@ service:type: stringdocs: The unique langfuse identifier of the trace to deleteresponse: DeleteTraceResponse- list:- availability:- status: deprecated- message: "On Langfuse Cloud, Langfuse v3 is deprecated and this endpoint will be removed on November 16, 2026. In Langfuse v4, read span and trace data via `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`. Self-hosted deployments are unaffected by this date; the endpoint becomes unavailable when they upgrade to Langfuse v4."- docs: Get list of traces- method: GET- path: /traces- request:- name: GetTracesRequest- query-parameters:- page:- type: optional<integer>- docs: Page number, starts at 1- limit:- type: optional<integer>- docs: Limit of items per page. If you encounter api issues due to too large page sizes, try to reduce the limit.- userId: optional<string>- name: optional<string>- sessionId: optional<string>- fromTimestamp:- type: optional<datetime>- docs: Optional filter to only include traces with a trace.timestamp on or after a certain datetime (ISO 8601)- toTimestamp:- type: optional<datetime>- docs: Optional filter to only include traces with a trace.timestamp before a certain datetime (ISO 8601)- orderBy:- type: optional<string>- docs: "Format of the string [field].[asc/desc]. Fields: id, timestamp, name, userId, release, version, public, bookmarked, sessionId. Example: timestamp.asc"- tags:- type: optional<string>- allow-multiple: true- docs: Only traces that include all of these tags will be returned.- version:- type: optional<string>- docs: Optional filter to only include traces with a certain version.- release:- type: optional<string>- docs: Optional filter to only include traces with a certain release.- environment:- type: optional<string>- allow-multiple: true- docs: Optional filter for traces where the environment is one of the provided values.- fields:- type: optional<string>- docs: "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'."- filter:- type: optional<string>- docs: |- 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- response: TracesdeleteMultiple:docs: Delete multiple tracesmethod: DELETE@@ -203,14 +26,6 @@ service:response: DeleteTraceResponsetypes:- Traces:- properties:- data: list<commons.TraceWithDetails>- meta: pagination.MetaResponse- _deprecation: optional<commons.Deprecation>DeleteTraceResponse:properties:message: string- Sort:- properties:- id: stringdiff --git a/packages/shared/src/features/scores/interfaces/api/shared.ts b/packages/shared/src/features/scores/interfaces/api/shared.tsindex 752892af91..5bfcf13f4a 100644--- a/packages/shared/src/features/scores/interfaces/api/shared.ts+++ b/packages/shared/src/features/scores/interfaces/api/shared.ts@@ -78,6 +78,7 @@ export const GetScoresQuery = z.object({export const PostScoreBody = applyScoreValidation(PostScoreBodyFoundationSchema.extend({source: PublicApiCreateScoreSourceDomain.default(ScoreSourceEnum.API),+ timestamp: stringDateTime,}).and(z.discriminatedUnion("dataType", [z.object({diff --git a/packages/shared/src/in-app-agent/server/mcpPolicy.ts b/packages/shared/src/in-app-agent/server/mcpPolicy.tsindex 204ffb507f..6e22ff28f7 100644--- a/packages/shared/src/in-app-agent/server/mcpPolicy.ts+++ b/packages/shared/src/in-app-agent/server/mcpPolicy.ts@@ -214,7 +214,7 @@ export const IN_APP_AGENT_LANGFUSE_MCP_TOOL_POLICIES = {},getExternalMediaStorage: {approval: "auto",- availability: { scope: "project:read" },+ availability: { scope: "integrations:CRUD" },},configureExternalMediaStorage: {approval: "approval",diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.tsindex 79593183d9..575bd0c294 100644--- a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts@@ -45,6 +45,10 @@ import {} from "./OtelIngestionProcessor";import * as serverBarrel from "../index";import { flattenJsonToPathArrays } from "./utils";+import {+ metadataArraysToRecord,+ parseMetadataCHRecordToDomain,+} from "../utils/metadata_conversion";const METRIC = "langfuse.ingestion.metadata_dropped";const ARRAY_ATTRIBUTE_DROPPED_METRIC =@@ -535,10 +539,48 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {);expect(fromBlob).toMatchObject(metadata);- expect(fromPerKey).toEqual(fromBlob);+ // Strings the metadata read path would parse as JSON keep their+ // encoding, so they read back as strings. A blob cannot tell them apart.+ const expected = { ...fromBlob, digits: '"42"', version: '"1.0"' };+ expect(fromPerKey).toEqual(expected);expect(flattenJsonToPathArrays(fromPerKey)).toEqual(- flattenJsonToPathArrays(fromBlob),+ flattenJsonToPathArrays(expected),+ );+ },+ );++ it.each(["v3", "v4"] as const)(+ "reads per-key values back with the type they were sent with (%s)",+ async (path) => {+ const sent = {+ digits: "42",+ version: "1.0",+ quoted: '"q"',+ jsonish: '{"a":1}',+ flag: "true",+ nullish: "null",+ label: "",+ environment: "prod",+ retries: 3,+ enabled: true,+ steps: [1, "two"],+ };+ const stored = await processMetadata(+ path,+ Object.entries(sent).map(([key, value]) => ({+ key: `langfuse.observation.metadata.${key}`,+ value: { stringValue: JSON.stringify(value) },+ })),);++ const { names, values } = flattenJsonToPathArrays(stored);+ const read = parseMetadataCHRecordToDomain(+ metadataArraysToRecord(names, values as string[]) ?? {},+ );++ expect(read).toMatchObject(sent);+ // Plain strings are stored raw, so string metadata filters match them.+ expect(stored).toMatchObject({ environment: "prod", label: "" });},);@@ -595,6 +637,99 @@ describe("per-key metadata values from structured-metadata SDK majors", () => {});});+ describe("user, session and tags sent as per-key metadata", () => {+ const compatAttributes = (+ domain: "observation" | "trace",+ encode: boolean,+ ): OtelAttribute[] =>+ Object.entries({+ langfuse_user_id: "u1",+ langfuse_session_id: "s1",+ langfuse_tags: "a",+ }).map(([key, value]) => ({+ key: `langfuse.${domain}.metadata.${key}`,+ value: {+ stringValue:+ encode || typeof value !== "string" ? JSON.stringify(value) : value,+ },+ }));++ const processTraceAttributes = async (+ path: "v3" | "v4",+ attributes: OtelAttribute[],+ scopeVersion: string,+ ) => {+ const batch = buildBatch(attributes);+ batch[0].scopeSpans![0].scope!.version = scopeVersion;+ const processor = new OtelIngestionProcessor({+ projectId: PROJECT_ID,+ publicKey: "pk-test",+ sdkName: "python",+ sdkVersion: scopeVersion,+ });+ if (path === "v4") {+ const event = processor.processToEvent(batch).at(-1);+ return {+ userId: event?.userId,+ sessionId: event?.sessionId,+ tags: event?.tags,+ };+ }+ const trace = (await processor.processToIngestionEvents(batch)).find(+ (event) => event.type === "trace-create",+ )?.body as+ | { userId?: string; sessionId?: string; tags?: string[] }+ | undefined;+ return {+ userId: trace?.userId,+ sessionId: trace?.sessionId,+ tags: trace?.tags,+ };+ };++ it.each([+ { path: "v3", domain: "observation" },+ { path: "v3", domain: "trace" },+ { path: "v4", domain: "observation" },+ { path: "v4", domain: "trace" },+ ] as const)(+ "decodes JSON-encoded values from a structured-metadata major ($path, $domain)",+ async ({ path, domain }) => {+ expect(+ await processTraceAttributes(+ path,+ compatAttributes(domain, true),+ "5.0.0",+ ),+ ).toEqual({ userId: "u1", sessionId: "s1", tags: ["a"] });+ },+ );++ it("keeps the exact digits of a numeric ID beyond 2^53", async () => {+ const result = await processTraceAttributes(+ "v4",+ [+ {+ key: "langfuse.observation.metadata.langfuse_user_id",+ value: { stringValue: "1234567890123456789" },+ },+ ],+ "5.0.0",+ );+ expect(result.userId).toBe("1234567890123456789");+ });++ it("keeps raw string values from the current major", async () => {+ expect(+ await processTraceAttributes(+ "v4",+ compatAttributes("observation", false),+ "4.15.6",+ ),+ ).toEqual({ userId: "u1", sessionId: "s1", tags: ["a"] });+ });+ });+it("falls back to telemetry.sdk.language without a Langfuse SDK header", async () => {const result = await processMetadata("v4",diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.tsindex 6d978eff7f..60a7e9bd23 100644--- a/packages/shared/src/server/otel/OtelIngestionProcessor.ts+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.ts@@ -45,6 +45,7 @@ import { OtelIngestionQueue } from "../redis/otelIngestionQueue";import { isValidDateString, flattenJsonToPathArrays } from "./utils";import { convertDateToClickhouseDateTime } from "../clickhouse/client";import { isNullOrUndefined } from "../../utils/isNullOrUndefined";+import { safeJsonParse } from "../../utils/json";import { defineOwnValue } from "../../utils/objects";export const AI_GATEWAY_INSTRUMENTATION_SCOPE_NAME = "langfuse-ai-gateway";@@ -658,14 +659,20 @@ export class OtelIngestionProcessor {: this.extractCostDetails(spanAttributes, spanContext),// Properties- tags: this.extractTags(spanAttributes),+ tags: this.extractTags(spanAttributes, decodeMetadataValues),public: this.extractPublic(spanAttributes),isAppRoot: this.extractIsAppRoot(spanAttributes),traceName:spanAttributes?.[LangfuseOtelSpanAttributes.TRACE_NAME] ??null,- userId: this.extractUserId(spanAttributes),- sessionId: this.extractSessionId(spanAttributes),+ userId: this.extractUserId(+ spanAttributes,+ decodeMetadataValues,+ ),+ sessionId: this.extractSessionId(+ spanAttributes,+ decodeMetadataValues,+ ),release:(spanAttributes?.[LangfuseOtelSpanAttributes.RELEASE@@ -1147,10 +1154,10 @@ export class OtelIngestionProcessor {(attributes?.[LangfuseOtelSpanAttributes.RELEASE] as string) ??resourceAttributes?.[LangfuseOtelSpanAttributes.RELEASE] ??null,- userId: this.extractUserId(attributes),- sessionId: this.extractSessionId(attributes),+ userId: this.extractUserId(attributes, decodeMetadataValues),+ sessionId: this.extractSessionId(attributes, decodeMetadataValues),public: this.extractPublic(attributes),- tags: this.extractTags(attributes),+ tags: this.extractTags(attributes, decodeMetadataValues),environment: this.extractEnvironment(attributes, resourceAttributes),input,output,@@ -1187,10 +1194,10 @@ export class OtelIngestionProcessor {(attributes?.[LangfuseOtelSpanAttributes.RELEASE] as string) ??resourceAttributes?.[LangfuseOtelSpanAttributes.RELEASE] ??null,- userId: this.extractUserId(attributes),- sessionId: this.extractSessionId(attributes),+ userId: this.extractUserId(attributes, decodeMetadataValues),+ sessionId: this.extractSessionId(attributes, decodeMetadataValues),public: this.extractPublic(attributes),- tags: this.extractTags(attributes),+ tags: this.extractTags(attributes, decodeMetadataValues),environment: this.extractEnvironment(attributes, resourceAttributes),input: attributes[LangfuseOtelSpanAttributes.TRACE_INPUT],output: attributes[LangfuseOtelSpanAttributes.TRACE_OUTPUT],@@ -2711,41 +2718,80 @@ export class OtelIngestionProcessor {private extractUserId(attributes: Record<string, unknown>,+ decodeMetadataValues: boolean,): string | undefined {- const userIdKeys = [- "langfuse.user.id",- "user.id",- `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_user_id`,- `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_user_id`,- `ai.telemetry.metadata.userId`,- ];-- for (const key of userIdKeys) {- if (attributes[key]) {- return typeof attributes[key] === "string"- ? (attributes[key] as string)- : JSON.stringify(attributes[key]);- }- }+ return this.extractStringAttribute(+ attributes,+ [+ "langfuse.user.id",+ "user.id",+ `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_user_id`,+ `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_user_id`,+ `ai.telemetry.metadata.userId`,+ ],+ decodeMetadataValues,+ );}private extractSessionId(attributes: Record<string, unknown>,+ decodeMetadataValues: boolean,): string | undefined {- const userIdKeys = [- "langfuse.session.id",- "session.id",- "gen_ai.conversation.id",- `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_session_id`,- `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_session_id`,- `ai.telemetry.metadata.sessionId`,- ];+ return this.extractStringAttribute(+ attributes,+ [+ "langfuse.session.id",+ "session.id",+ "gen_ai.conversation.id",+ `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_session_id`,+ `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_session_id`,+ `ai.telemetry.metadata.sessionId`,+ ],+ decodeMetadataValues,+ );+ }- for (const key of userIdKeys) {- if (attributes[key]) {- return typeof attributes[key] === "string"- ? (attributes[key] as string)- : JSON.stringify(attributes[key]);+ /**+ * readAttribute decodes the langfuse_* compat keys read from metadata, which+ * structured-metadata SDK majors JSON-encode like every per-key value.+ */+ private readAttribute(+ attributes: Record<string, unknown>,+ key: string,+ decodeMetadataValues: boolean,+ ): unknown {+ const value = attributes[key];+ if (+ !decodeMetadataValues ||+ typeof value !== "string" ||+ !(+ key.startsWith(`${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.`) ||+ key.startsWith(`${LangfuseOtelSpanAttributes.TRACE_METADATA}.`)+ )+ ) {+ return value;+ }+ try {+ return JSON.parse(value);+ } catch {+ return value;+ }+ }++ /**+ * extractStringAttribute keeps a decoded value only when it is a string, so+ * an encoded number keeps its exact digits instead of a lossy JS number.+ */+ private extractStringAttribute(+ attributes: Record<string, unknown>,+ keys: string[],+ decodeMetadataValues: boolean,+ ): string | undefined {+ for (const key of keys) {+ const decoded = this.readAttribute(attributes, key, decodeMetadataValues);+ const value = typeof decoded === "string" ? decoded : attributes[key];+ if (value) {+ return typeof value === "string" ? value : JSON.stringify(value);}}}@@ -3420,16 +3466,23 @@ export class OtelIngestionProcessor {return null;}- private extractTags(attributes: Record<string, unknown>): string[] {+ private extractTags(+ attributes: Record<string, unknown>,+ decodeMetadataValues: boolean,+ ): string[] {const tagsValue =attributes[LangfuseOtelSpanAttributes.TRACE_TAGS] ||attributes["langfuse.tags"] ||- attributes[- `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_tags`- ] ||- attributes[- `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_tags`- ] ||+ this.readAttribute(+ attributes,+ `${LangfuseOtelSpanAttributes.OBSERVATION_METADATA}.langfuse_tags`,+ decodeMetadataValues,+ ) ||+ this.readAttribute(+ attributes,+ `${LangfuseOtelSpanAttributes.TRACE_METADATA}.langfuse_tags`,+ decodeMetadataValues,+ ) ||attributes["ai.telemetry.metadata.tags"] ||attributes["tag.tags"];@@ -3595,7 +3648,14 @@ export class OtelIngestionProcessor {// undecodable value (e.g. cut by an attribute length limit) is kept as// sent so its content is not lost.try {- metadata[metadataKey] = JSON.parse(value);+ const decoded = JSON.parse(value);+ // Strings are stored raw and metadata reads JSON-parse every stored+ // value, so a string such as "42" or '{"a":1}' would read back as a+ // number or object. Keeping its encoding preserves the string type.+ metadata[metadataKey] =+ typeof decoded === "string" && safeJsonParse(decoded) !== undefined+ ? value+ : decoded;} catch {metadata[metadataKey] = value;recordIncrement("langfuse.ingestion.metadata_undecoded", 1, {diff --git a/web/public/generated/api/openapi.yml b/web/public/generated/api/openapi.ymlindex 337a689776..c82a0d03f8 100644--- a/web/public/generated/api/openapi.yml+++ b/web/public/generated/api/openapi.yml@@ -1149,138 +1149,6 @@ paths:application/json:schema: {}security: *ref_0- /api/public/dataset-run-items:- post:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, create- experiment data via the SDK experiment runner or the OpenTelemetry- endpoint at POST /api/public/otel/v1/traces. Self-hosted deployments are- unaffected by this date; the endpoint becomes unavailable when they- upgrade to Langfuse v4. See the [Langfuse v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Create a dataset run item- operationId: datasetRunItems_create- tags:- - DatasetRunItems- parameters: []- responses:- '200':- description: ''- content:- application/json:- schema:- $ref: '#/components/schemas/DatasetRunItem'- '400':- description: ''- content:- application/json:- schema: {}- '401':- description: ''- content:- application/json:- schema: {}- '403':- description: ''- content:- application/json:- schema: {}- '404':- description: ''- content:- application/json:- schema: {}- '405':- description: ''- content:- application/json:- schema: {}- security: *ref_0- requestBody:- required: true- content:- application/json:- schema:- $ref: '#/components/schemas/CreateDatasetRunItemRequest'- deprecated: true- get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, dataset- run items are replaced by experiment items; use `GET- /api/public/experiment-items?fromStartTime=<from>&toStartTime=<to>`- instead. Self-hosted deployments are unaffected by this date; the- endpoint becomes unavailable when they upgrade to Langfuse v4. See the- [Langfuse v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- List dataset run items- operationId: datasetRunItems_list- tags:- - DatasetRunItems- parameters:- - name: datasetId- in: query- required: true- schema:- type: string- - name: runName- in: query- required: true- schema:- type: string- - name: page- in: query- description: page number, starts at 1- required: false- schema:- type: integer- nullable: true- - name: limit- in: query- description: limit of items per page- required: false- schema:- type: integer- nullable: true- responses:- '200':- description: ''- content:- application/json:- schema:- $ref: '#/components/schemas/PaginatedDatasetRunItems'- '400':- description: ''- content:- application/json:- schema: {}- '401':- description: ''- content:- application/json:- schema: {}- '403':- description: ''- content:- application/json:- schema: {}- '404':- description: ''- content:- application/json:- schema: {}- '405':- description: ''- content:- application/json:- schema: {}- security: *ref_0- deprecated: true/api/public/v2/datasets:get:description: Get all datasets@@ -1425,196 +1293,6 @@ paths: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: >-@@ -2791,102 +2469,75 @@ paths:schema: {}'503':description: ''- /api/public/ingestion:- post:+ /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: >-- **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+ Create or update an LLM connection. The connection is upserted on+ provider.+ operationId: llmConnections_upserttags:- - Ingestion+ - LlmConnectionsparameters: []responses:- '207':+ '200':description: ''content:application/json:schema:- $ref: '#/components/schemas/IngestionResponse'+ $ref: '#/components/schemas/LlmConnection''400':description: ''content:@@ -2918,99 +2569,18 @@ paths: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:+ $ref: '#/components/schemas/UpsertLlmConnectionRequest'+ /api/public/llm-connections/{id}:+ delete:description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. Use `GET- /api/public/v2/metrics?query=<urlencoded json query>` instead.- Self-hosted deployments are unaffected by this date; the endpoint- becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse- v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get metrics from the Langfuse project using a query object.--- Consider using the [v2 metrics- endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for- better performance.--- For more details, see the [Metrics API- documentation](https://langfuse.com/docs/metrics/features/metrics-api).- operationId: legacy_metricsV1_metrics+ Delete an LLM connection by id. Evaluators that depend on the deleted+ connection are automatically paused.+ operationId: llmConnections_deletetags:- - LegacyMetricsV1+ - LlmConnectionsparameters:- - 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)- }- }-- ```+ - name: id+ in: pathrequired: trueschema:type: string@@ -3020,7 +2590,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/legacyMetricsResponse'+ $ref: '#/components/schemas/DeleteLlmConnectionResponse''400':description: ''content:@@ -3047,39 +2617,113 @@ paths:application/json:schema: {}security: *ref_0- deprecated: true- /api/public/observations/{observationId}:+ /api/public/media/{mediaId}:get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. Use `GET- /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`- instead. Self-hosted deployments are unaffected by this date; the- endpoint becomes unavailable when they upgrade to Langfuse v4. See the- [Langfuse v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get a observation- operationId: legacy_observationsV1_get+ description: Get a media record+ operationId: media_gettags:- - LegacyObservationsV1+ - Mediaparameters:- - name: observationId+ - name: mediaIdin: path- description: >-- The unique langfuse identifier of an observation, can be an event,- span or generation+ 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 recordrequired: trueschema: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/ObservationsViewSingle'+ $ref: '#/components/schemas/GetMediaUploadUrlResponse''400':description: ''content:@@ -3106,293 +2750,345 @@ paths:application/json:schema: {}security: *ref_0- deprecated: true- /api/public/observations:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/GetMediaUploadUrlRequest'+ /api/public/v2/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/observations?fromStartTime=<from>&toStartTime=<to>`- instead. Self-hosted deployments are unaffected by this date; the- endpoint becomes unavailable when they upgrade to Langfuse v4. See the- [Langfuse v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).+ Get metrics from the Langfuse project using a query object. V2 endpoint+ with optimized performance.- Get a list of observations.+ 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.- 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, ...).+ ## V2 Differences+ - Supports `observations`, `scores-numeric`, `scores-boolean`, and+ `scores-categorical` views only (traces view not supported)- ## Filter Structure+ - Direct access to tags and release fields on observations- Each filter condition has the following structure:+ - Semantic-root filtering and grouping through the v2-only+ `isRootObservation` dimension- ```json+ - Backwards-compatible: traceName, traceRelease, traceVersion dimensions+ are still available on observations view- [- {- "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- }- ]+ - 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 Columns+ ## Available Views- ### Core Observation Fields- - `id` (string) - Observation ID+ ### observations- - `type` (string) - Observation type (SPAN, GENERATION, EVENT)+ Query observation-level data (spans, generations, events).- - `name` (string) - Observation name- - `traceId` (string) - Associated trace ID+ **Dimensions:**- - `startTime` (datetime) - Observation start time+ - `environment` - Deployment environment (e.g., production, staging)- - `endTime` (datetime) - Observation end time+ - `type` - Type of observation (SPAN, GENERATION, EVENT)- - `environment` (string) - Environment tag+ - `name` - Name of the observation- - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)+ - `level` - Logging level of the observation- - `statusMessage` (string) - Status message+ - `version` - Version of the observation- - `version` (string) - Version tag+ - `tags` - User-defined tags+ - `release` - Release version- ### Performance Metrics+ - `traceName` - Name of the parent trace (backwards-compatible)- - `latency` (number) - Latency in seconds (calculated: end_time -- start_time)+ - `traceRelease` - Release version of the parent trace+ (backwards-compatible, maps to release)- - `timeToFirstToken` (number) - Time to first token in seconds+ - `traceVersion` - Version of the parent trace (backwards-compatible,+ maps to version)- - `tokensPerSecond` (number) - Output tokens per second+ - `providedModelName` - Name of the model used+ - `promptName` - Name of the prompt used- ### Token Usage+ - `promptVersion` - Version of the prompt used- - `inputTokens` (number) - Number of input tokens+ - `isRootObservation` - Boolean semantic-root status. `true` includes+ physical roots and app roots whose SDK parent is external (so+ `parentObservationId` may be non-null).- - `outputTokens` (number) - Number of output tokens+ - `startTimeMonth` - Month of start_time in YYYY-MM format- - `totalTokens` (number) - Total tokens (alias: `tokens`)+ **Measures:**- ### Cost Metrics+ - `count` - Total number of observations- - `inputCost` (number) - Input cost in USD+ - `latency` - Observation latency (milliseconds)- - `outputCost` (number) - Output cost in USD+ - `streamingLatency` - Generation latency from completion start to end+ (milliseconds)- - `totalCost` (number) - Total cost in USD+ - `inputTokens` - Sum of input tokens consumed+ - `outputTokens` - Sum of output tokens produced- ### Model Information+ - `totalTokens` - Sum of all tokens consumed- - `model` (string) - Provided model name+ - `outputTokensPerSecond` - Output tokens per second- - `promptName` (string) - Associated prompt name+ - `tokensPerSecond` - Total tokens per second- - `promptVersion` (number) - Associated prompt version+ - `inputCost` - Input cost (USD)+ - `outputCost` - Output cost (USD)- ### Structured Data+ - `totalCost` - Total cost (USD)- - `metadata` (stringObject/numberObject/categoryOptions) - Metadata- key-value pairs. Use `key` parameter to filter on specific metadata- keys.+ - `timeToFirstToken` - Time to first token (milliseconds)+ - `countScores` - Number of scores attached to the observation- ### Associated Trace Fields (requires join with traces table)- - `userId` (string) - User ID from associated trace+ ### scores-numeric- - `traceName` (string) - Name from associated trace+ Query numeric and boolean score data.- - `traceEnvironment` (string) - Environment from associated trace- - `traceTags` (arrayOptions) - Tags from associated trace+ **Dimensions:**+ - `environment` - Deployment environment- ## Filter Examples+ - `name` - Name of the score (e.g., accuracy, toxicity)- ```json+ - `source` - Origin of the score (API, ANNOTATION, EVAL)- [- {- "type": "string",- "column": "type",- "operator": "=",- "value": "GENERATION"- },- {- "type": "number",- "column": "latency",- "operator": ">=",- "value": 2.5- },- {- "type": "stringObject",- "column": "metadata",- "key": "environment",- "operator": "=",- "value": "production"- }- ]+ - `dataType` - Data type (NUMERIC, BOOLEAN)- ```- 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: {}+ - `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:@@ -3404,23 +3100,20 @@ paths: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+ /api/public/models:+ post:+ description: Create a model+ operationId: models_createtags:- - LegacyScoreV1- parameters:- - name: scoreId- in: path- description: The unique langfuse identifier of a score- required: true- schema:- type: string+ - Models+ parameters: []responses:- '204':+ '200':description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/Model''400':description: ''content:@@ -3447,12 +3140,17 @@ paths:application/json:schema: {}security: *ref_0- /api/public/llm-connections:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/CreateModelRequest'get:- description: Get all LLM connections in a project- operationId: llmConnections_list+ description: Get all models+ operationId: models_listtags:- - LlmConnections+ - Modelsparameters:- name: pagein: query@@ -3474,7 +3172,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/PaginatedLlmConnections'+ $ref: '#/components/schemas/PaginatedModels''400':description: ''content:@@ -3501,61 +3199,14 @@ paths:application/json:schema: {}security: *ref_0+ /api/public/models/{id}:put:description: >-- Create or update an LLM connection. The connection is upserted on- provider.- operationId: llmConnections_upsert+ Create or replace a project-owned model using its id. Built-in models+ cannot be modified.+ operationId: models_upserttags:- - 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+ - Modelsparameters:- name: idin: path@@ -3568,7 +3219,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/DeleteLlmConnectionResponse'+ $ref: '#/components/schemas/Model''400':description: ''content:@@ -3595,16 +3246,20 @@ paths:application/json:schema: {}security: *ref_0- /api/public/media/{mediaId}:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/CreateModelRequest'get:- description: Get a media record- operationId: media_get+ description: Get a model+ operationId: models_gettags:- - Media+ - Modelsparameters:- - name: mediaId+ - name: idin: path- description: The unique langfuse identifier of a media recordrequired: trueschema:type: string@@ -3614,7 +3269,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/GetMediaResponse'+ $ref: '#/components/schemas/Model''400':description: ''content:@@ -3641,15 +3296,17 @@ paths:application/json:schema: {}security: *ref_0- patch:- description: Patch a media record- operationId: media_patch+ 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_deletetags:- - Media+ - Modelsparameters:- - name: mediaId+ - name: idin: path- description: The unique langfuse identifier of a media recordrequired: trueschema:type: string@@ -3682,376 +3339,426 @@ paths: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:+ /api/public/v2/observations: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+ Get a list of observations with cursor-based pagination and flexible+ field selection.- - `level` - Logging level of the observation- - `version` - Version of the observation+ 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.- - `tags` - User-defined tags- - `release` - Release version+ ## Cursor-based Pagination- - `traceName` - Name of the parent trace (backwards-compatible)+ This endpoint uses cursor-based pagination for efficient traversal of+ large datasets.- - `traceRelease` - Release version of the parent trace- (backwards-compatible, maps to release)+ The cursor is returned in the response metadata and should be passed in+ subsequent requests- - `traceVersion` - Version of the parent trace (backwards-compatible,- maps to version)+ to retrieve the next page of results.- - `providedModelName` - Name of the model used- - `promptName` - Name of the prompt used+ ## Field Selection- - `promptVersion` - Version of the prompt used+ Use the `fields` parameter to control which observation fields are+ returned:- - `isRootObservation` - Boolean semantic-root status. `true` includes- physical roots and app roots whose SDK parent is external (so- `parentObservationId` may be non-null).+ - `core` - Always included: id, traceId, startTime, endTime, projectId,+ parentObservationId, type- - `startTimeMonth` - Month of start_time in YYYY-MM format+ - `basic` - name, level, statusMessage, version, environment,+ bookmarked, public, userId, sessionId, isRootObservation+ - `time` - completionStartTime, createdAt, updatedAt- **Measures:**+ - `io` - input, output- - `count` - Total number of observations+ - `metadata` - metadata (truncated to 200 chars by default, use+ `expandMetadata` to get full values)- - `latency` - Observation latency (milliseconds)+ - `model` - model, internalModelId, modelParameters- - `streamingLatency` - Generation latency from completion start to end- (milliseconds)+ - `usage` - usageDetails, costDetails, totalCost, usagePricingTierName- - `inputTokens` - Sum of input tokens consumed+ - `prompt` - promptId, promptName, promptVersion- - `outputTokens` - Sum of output tokens produced+ - `metrics` - latency, timeToFirstToken- - `totalTokens` - Sum of all tokens consumed+ - `trace_context` - tags, release, traceName- - `outputTokensPerSecond` - Output tokens per second- - `tokensPerSecond` - Total tokens per second+ If not specified, `core` and `basic` field groups are returned.- - `inputCost` - Input cost (USD)- - `outputCost` - Output cost (USD)+ ## Filters- - `totalCost` - Total cost (USD)+ Multiple filtering options are available via query parameters or the+ structured `filter` parameter.- - `timeToFirstToken` - Time to first token (milliseconds)+ 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.- - `countScores` - Number of scores attached to the observation+ Available groups: core, basic, time, io, metadata, model, usage,+ prompt, metrics, trace_context.+ If not specified, `core` and `basic` field groups are returned.- ### scores-numeric+ 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.- Query numeric and boolean score data.+ 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.- **Dimensions:**+ 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, ...).- - `environment` - Deployment environment- - `name` - Name of the score (e.g., accuracy, toxicity)+ ## Filter Structure- - `source` - Origin of the score (API, ANNOTATION, EVAL)+ Each filter condition has the following structure:- - `dataType` - Data type (NUMERIC, BOOLEAN)+ ```json- - `configId` - Identifier of the score config+ [+ {+ "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+ }+ ]- - `timestampMonth` - Month in YYYY-MM format+ ```- - `timestampDay` - Day in YYYY-MM-DD format- - `value` - Numeric value of the score+ ## Available Columns- - `traceName` - Name of the parent trace- - `tags` - Tags+ ### Core Observation Fields- - `traceRelease` - Release version+ - `id` (string) - Observation ID- - `traceVersion` - Version+ - `type` (string) - Observation type (SPAN, GENERATION, EVENT)- - `observationName` - Name of the associated observation+ - `name` (string) - Observation name- - `observationModelName` - Model name of the associated observation+ - `traceId` (string) - Associated trace ID- - `observationPromptName` - Prompt name of the associated observation+ - `startTime` (datetime) - Observation start time- - `observationPromptVersion` - Prompt version of the associated- observation+ - `endTime` (datetime) - Observation end time+ - `environment` (string) - Environment tag- **Measures:**+ - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)- - `count` - Total number of scores+ - `statusMessage` (string) - Status message- - `value` - Score value (for aggregations)+ - `version` (string) - Version tag+ - `userId` (string) - User ID- ### scores-boolean+ - `sessionId` (string) - Session ID- Query boolean score data. It has the same score and parent- trace/observation dimensions as scores-numeric, plus:+ - `isRootObservation` (boolean) - Whether the observation is a+ logical root. Observations marked as app roots by the SDK may retain+ a non-null parentObservationId.- **Dimensions:**+ ### Trace-Related Fields- - `booleanValue` - Boolean value for true/false grouping and filtering+ - `traceName` (string) - Name of the parent trace+ - `traceTags` (arrayOptions) - Tags from the parent trace- **Measures:**+ - `tags` (arrayOptions) - Alias for traceTags- - `count` - Total number of boolean scores- - `value` - Numeric 0/1 score value; `avg` returns the true-rate+ ### Performance Metrics+ - `latency` (number) - Latency in seconds (calculated: end_time -+ start_time)- ### scores-categorical+ - `timeToFirstToken` (number) - Time to first token in seconds- Query categorical score data. Same dimensions as scores-numeric except- uses `stringValue` instead of `value`.+ - `tokensPerSecond` (number) - Output tokens per second- **Measures:**+ ### Token Usage- - `count` - Total number of scores+ - `inputTokens` (number) - Number of input tokens+ - `outputTokens` (number) - Number of output tokens- ## High Cardinality Dimensions+ - `totalTokens` (number) - Total tokens (alias: `tokens`)- The following dimensions cannot be used as grouping dimensions in v2- metrics API as they can cause performance issues.- Use them in filters instead.+ ### Cost Metrics+ - `inputCost` (number) - Input cost in USD- **observations view:**+ - `outputCost` (number) - Output cost in USD- - `id` - Use traceId filter to narrow down results+ - `totalCost` (number) - Total cost in USD- - `traceId` - Use traceId filter instead- - `userId` - Use userId filter instead+ ### Model Information- - `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+ - `model` (string) - Provided model name (alias:+ `providedModelName`)- - `traceId` - Use traceId filter instead+ - `promptName` (string) - Associated prompt name- - `userId` - Use userId filter instead+ - `promptVersion` (number) - Associated prompt version- - `sessionId` - Use sessionId filter instead- - `observationId` - Use observationId filter instead+ ### Structured Data+ - `input` (string) - Observation input. Supports accelerated indexed+ literal search with the `matches` operator.- ## Aggregations+ - `output` (string) - Observation output. Supports accelerated+ indexed literal search with the `matches` operator.- Available aggregation functions: `sum`, `avg`, `count`, `max`, `min`,- `p50`, `p75`, `p90`, `p95`, `p99`, `histogram`+ - `metadata` (stringObject/numberObject/categoryOptions) - Metadata+ key-value pairs. Use `key` parameter to filter on specific metadata+ keys.- ## Time Granularities+ 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.- 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:+ ## Filter Examples```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"+ [+ {+ "type": "string",+ "column": "type",+ "operator": "=",+ "value": "GENERATION"},- "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+ {+ "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}- }-- ```--- 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+ required: falseschema:type: string+ nullable: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/MetricsV2Response'+ $ref: '#/components/schemas/ObservationsV2Response''400':description: ''content:@@ -4078,12 +3785,49 @@ paths:application/json:schema: {}security: *ref_0- /api/public/models:+ /api/public/otel/v1/traces:post:- description: Create a model- operationId: models_create+ 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_exportTracestags:- - Models+ - Opentelemetryparameters: []responses:'200':@@ -4091,7 +3835,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/Model'+ $ref: '#/components/schemas/OtelTraceResponse''400':description: ''content:@@ -4123,34 +3867,33 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/CreateModelRequest'+ 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 models- operationId: models_list+ description: >-+ Get all memberships for the organization associated with the API key+ (requires organization-scoped API key)+ operationId: organizations_getOrganizationMembershipstags:- - 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+ - Organizations+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/PaginatedModels'+ $ref: '#/components/schemas/MembershipsResponse''400':description: ''content:@@ -4177,27 +3920,21 @@ paths: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+ Create or update a membership for the organization associated with the+ API key (requires organization-scoped API key)+ operationId: organizations_updateOrganizationMembershiptags:- - Models- parameters:- - name: id- in: path- required: true- schema:- type: string+ - Organizations+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Model'+ $ref: '#/components/schemas/MembershipResponse''400':description: ''content:@@ -4229,14 +3966,64 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/CreateModelRequest'- get:- description: Get a model- operationId: models_get+ $ref: '#/components/schemas/MembershipRequest'+ delete:+ description: >-+ Delete a membership from the organization associated with the API key+ (requires organization-scoped API key)+ operationId: organizations_deleteOrganizationMembershiptags:- - Models+ - 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:+ - Organizationsparameters:- - name: id+ - name: projectIdin: pathrequired: trueschema:@@ -4247,7 +4034,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/Model'+ $ref: '#/components/schemas/MembershipsResponse''400':description: ''content:@@ -4274,23 +4061,27 @@ paths:application/json:schema: {}security: *ref_0- delete:+ put: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+ 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_updateProjectMembershiptags:- - Models+ - Organizationsparameters:- - name: id+ - name: projectIdin: pathrequired: trueschema:type: stringresponses:- '204':+ '200':description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MembershipResponse''400':description: ''content:@@ -4317,426 +4108,33 @@ paths:application/json:schema: {}security: *ref_0- /api/public/v2/observations:- get:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/MembershipRequest'+ delete: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+ Delete a membership from a specific project (requires+ organization-scoped API key). The user must be a member of the+ organization.+ operationId: organizations_deleteProjectMembershiptags:- - Observations+ - Organizationsparameters:- - 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+ - name: projectId+ in: path+ required: trueschema: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: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/ObservationsV2Response'+ $ref: '#/components/schemas/MembershipDeletionResponse''400':description: ''content:@@ -4763,49 +4161,20 @@ paths: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+ 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_getOrganizationProjectstags:- - Opentelemetry+ - Organizationsparameters: []responses:'200':@@ -4813,7 +4182,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/OtelTraceResponse'+ $ref: '#/components/schemas/OrganizationProjectsResponse''400':description: ''content:@@ -4840,28 +4209,12 @@ paths: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:+ /api/public/organizations/apiKeys:get:description: >-- Get all memberships for the organization associated with the API key+ Get all API keys for the organization associated with the API key(requires organization-scoped API key)- operationId: organizations_getOrganizationMemberships+ operationId: organizations_getOrganizationApiKeystags:- Organizationsparameters: []@@ -4871,7 +4224,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/MembershipsResponse'+ $ref: '#/components/schemas/OrganizationApiKeysResponse''400':description: ''content:@@ -4898,13 +4251,15 @@ paths:application/json:schema: {}security: *ref_0- put:+ /api/public/projects:+ get:description: >-- Create or update a membership for the organization associated with the- API key (requires organization-scoped API key)- operationId: organizations_updateOrganizationMembership+ 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_gettags:- - Organizations+ - Projectsparameters: []responses:'200':@@ -4912,7 +4267,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/MembershipResponse'+ $ref: '#/components/schemas/Projects''400':description: ''content:@@ -4939,19 +4294,11 @@ paths: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+ post:+ description: Create a new project (requires organization-scoped API key)+ operationId: projects_createtags:- - Organizations+ - Projectsparameters: []responses:'200':@@ -4959,7 +4306,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/MembershipDeletionResponse'+ $ref: '#/components/schemas/Project''400':description: ''content:@@ -4991,15 +4338,30 @@ paths: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+ 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_updatetags:- - Organizations+ - Projectsparameters:- name: projectIdin: path@@ -5012,7 +4374,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/MembershipsResponse'+ $ref: '#/components/schemas/Project''400':description: ''content:@@ -5039,14 +4401,37 @@ paths:application/json:schema: {}security: *ref_0- put:+ 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: >-- 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+ Delete a project by ID (requires organization-scoped API key). Project+ deletion is processed asynchronously.+ operationId: projects_deletetags:- - Organizations+ - Projectsparameters:- name: projectIdin: path@@ -5054,12 +4439,12 @@ paths:schema:type: stringresponses:- '200':+ '202':description: ''content:application/json:schema:- $ref: '#/components/schemas/MembershipResponse'+ $ref: '#/components/schemas/ProjectDeletionResponse''400':description: ''content:@@ -5086,20 +4471,12 @@ paths: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+ /api/public/projects/{projectId}/apiKeys:+ get:+ description: Get all API keys for a project (requires organization-scoped API key)+ operationId: projects_getApiKeystags:- - Organizations+ - Projectsparameters:- name: projectIdin: path@@ -5112,7 +4489,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/MembershipDeletionResponse'+ $ref: '#/components/schemas/ApiKeyList''400':description: ''content:@@ -5139,28 +4516,25 @@ paths:application/json:schema: {}security: *ref_0- requestBody:- required: true- content:- application/json:- schema:- $ref: '#/components/schemas/DeleteMembershipRequest'- /api/public/organizations/projects:- get:+ post:description: >-- Get all projects for the organization associated with the API key- (requires organization-scoped API key)- operationId: organizations_getOrganizationProjects+ Create a new API key for a project (requires organization-scoped API key)+ operationId: projects_createApiKeytags:- - Organizations- parameters: []+ - Projects+ parameters:+ - name: projectId+ in: path+ required: true+ schema:+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/OrganizationProjectsResponse'+ $ref: '#/components/schemas/ApiKeyResponse''400':description: ''content:@@ -5187,65 +4561,70 @@ paths: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+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ nullable: true+ description: >-+ Optional name for the API key. Cannot be provided together+ with note, even if either value is an empty string.+ note:+ type: string+ nullable: true+ description: >-+ Deprecated alias for name. Cannot be provided together with+ name, even if either value is an empty string.+ deprecated: true+ expiresAt:+ type: string+ format: date-time+ nullable: true+ description: >-+ Optional expiration timestamp in ISO 8601 format. Must be in+ the future. Omit or set to null for a key that does not+ expire.+ publicKey:+ type: string+ nullable: true+ description: >-+ Optional predefined public key. Must start with 'pk-lf-'. If+ provided, secretKey must also be provided.+ secretKey:+ type: string+ nullable: true+ description: >-+ Optional predefined secret key. Must start with 'sk-lf-'. If+ provided, publicKey must also be provided.+ /api/public/projects/{projectId}/apiKeys/{apiKeyId}:+ delete:+ description: Delete an API key for a project (requires organization-scoped API key)+ operationId: projects_deleteApiKeytags:- Projects- parameters: []+ parameters:+ - name: projectId+ in: path+ required: true+ schema:+ type: string+ - name: apiKeyId+ in: path+ required: true+ schema:+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Projects'+ $ref: '#/components/schemas/ApiKeyDeletionResponse''400':description: ''content:@@ -5272,19 +4651,36 @@ paths:application/json:schema: {}security: *ref_0- post:- description: Create a new project (requires organization-scoped API key)- operationId: projects_create+ /api/public/v2/prompts/{name}/versions/{version}:+ patch:+ description: Update labels for a specific prompt version+ operationId: promptVersion_updatetags:- - Projects- parameters: []+ - 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: integerresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Project'+ $ref: '#/components/schemas/Prompt''400':description: ''content:@@ -5318,41 +4714,67 @@ paths:schema:type: objectproperties:- name:- type: string- metadata:- type: object- additionalProperties: true- nullable: true- description: Optional metadata for the project- retention:- type: integer+ newLabels:+ type: array+ items:+ type: stringdescription: >-- Number of days to retain data. Must be 0 or at least 3 days.- Requires data-retention entitlement for non-zero values.- Optional.+ New labels for the prompt version. Labels are unique across+ versions. The "latest" label is reserved and managed by+ Langfuse.required:- - name- - retention- /api/public/projects/{projectId}:- put:- description: Update a project by ID (requires organization-scoped API key).- operationId: projects_update+ - newLabels+ /api/public/v2/prompts/{promptName}:+ get:+ description: Get a prompt+ operationId: prompts_gettags:- - Projects+ - Promptsparameters:- - name: projectId+ - name: promptNamein: 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: trueschema: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: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Project'+ $ref: '#/components/schemas/Prompt''400':description: ''content:@@ -5379,50 +4801,41 @@ paths: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:- - namedelete:description: >-- Delete a project by ID (requires organization-scoped API key). Project- deletion is processed asynchronously.- operationId: projects_delete+ Delete prompt versions. If neither version nor label is specified, all+ versions of the prompt are deleted.+ operationId: prompts_deletetags:- - Projects+ - Promptsparameters:- - name: projectId+ - name: promptNamein: path+ description: The name of the promptrequired: trueschema: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: trueresponses:- '202':+ '204':description: ''- content:- application/json:- schema:- $ref: '#/components/schemas/ProjectDeletionResponse''400':description: ''content:@@ -5449,30 +4862,142 @@ paths:application/json:schema: {}security: *ref_0- /api/public/projects/{projectId}/apiKeys:+ /api/public/v2/prompts:get:- description: Get all API keys for a project (requires organization-scoped API key)- operationId: projects_getApiKeys+ description: Get a list of prompt names with versions and labels+ operationId: prompts_listtags:- - Projects+ - Promptsparameters:- - name: projectId- in: path- required: true+ - name: name+ in: query+ required: falseschema:type: string- responses:- '200':- description: ''- content:- application/json:- schema:- $ref: '#/components/schemas/ApiKeyList'- '400':- description: ''- content:- application/json:- schema: {}+ 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:@@ -5495,24 +5020,18 @@ paths:schema: {}security: *ref_0post:- description: >-- Create a new API key for a project (requires organization-scoped API key)- operationId: projects_createApiKey+ description: Create a new version for the prompt with the given `name`+ operationId: prompts_createtags:- - Projects- parameters:- - name: projectId- in: path- required: true- schema:- type: string+ - Prompts+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/ApiKeyResponse'+ $ref: '#/components/schemas/Prompt''400':description: ''content:@@ -5544,65 +5063,23 @@ paths:content:application/json:schema:- type: object- properties:- name:- type: string- nullable: true- description: >-- Optional name for the API key. Cannot be provided together- with note, even if either value is an empty string.- note:- type: string- nullable: true- description: >-- Deprecated alias for name. Cannot be provided together with- name, even if either value is an empty string.- deprecated: true- expiresAt:- type: string- format: date-time- nullable: true- description: >-- Optional expiration timestamp in ISO 8601 format. Must be in- the future. Omit or set to null for a key that does not- expire.- publicKey:- type: string- nullable: true- description: >-- Optional predefined public key. Must start with 'pk-lf-'. If- provided, secretKey must also be provided.- secretKey:- type: string- nullable: true- description: >-- Optional predefined secret key. Must start with 'sk-lf-'. If- provided, publicKey must also be provided.- /api/public/projects/{projectId}/apiKeys/{apiKeyId}:- delete:- description: Delete an API key for a project (requires organization-scoped API key)- operationId: projects_deleteApiKey+ $ref: '#/components/schemas/CreatePromptRequest'+ /api/public/scim/ServiceProviderConfig:+ get:+ description: >-+ Get SCIM Service Provider Configuration (requires organization-scoped+ API key)+ operationId: scim_getServiceProviderConfigtags:- - Projects- parameters:- - name: projectId- in: path- required: true- schema:- type: string- - name: apiKeyId- in: path- required: true- schema:- type: string+ - Scim+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/ApiKeyDeletionResponse'+ $ref: '#/components/schemas/ServiceProviderConfig''400':description: ''content:@@ -5629,36 +5106,20 @@ paths: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+ /api/public/scim/ResourceTypes:+ get:+ description: Get SCIM Resource Types (requires organization-scoped API key)+ operationId: scim_getResourceTypestags:- - 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+ - Scim+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Prompt'+ $ref: '#/components/schemas/ResourceTypesResponse''400':description: ''content:@@ -5685,135 +5146,20 @@ paths: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}:+ /api/public/scim/Schemas:get:- description: Get a prompt- operationId: prompts_get+ description: Get SCIM Schemas (requires organization-scoped API key)+ operationId: scim_getSchemastags:- - 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+ - Scim+ 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- 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: ''+ $ref: '#/components/schemas/SchemasResponse''400':description: ''content:@@ -5840,137 +5186,41 @@ paths:application/json:schema: {}security: *ref_0- /api/public/v2/prompts:+ /api/public/scim/Users:get:- description: Get a list of prompt names with versions and labels- operationId: prompts_list+ description: List users in the organization (requires organization-scoped API key)+ operationId: scim_listUserstags:- - Prompts+ - Scimparameters:- - name: name- in: query- required: false- schema:- type: string- nullable: true- - name: label- in: query- required: false- schema:- type: string- nullable: true- - name: tag+ - name: filterin: query+ description: Filter expression (e.g. userName eq "value")required: falseschema:type: stringnullable: true- - name: page+ - name: startIndexin: query- description: page number, starts at 1+ description: 1-based index of the first result to return (default 1)required: falseschema:type: integernullable: true- - name: limit+ - name: countin: query- description: limit of items per page+ description: Maximum number of results to return (default 100)required: falseschema:type: integernullable: 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: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/PromptMetaListResponse'+ $ref: '#/components/schemas/ScimUsersListResponse''400':description: ''content:@@ -5998,10 +5248,12 @@ paths:schema: {}security: *ref_0post:- description: Create a new version for the prompt with the given `name`- operationId: prompts_create+ description: >-+ Create a new user in the organization (requires organization-scoped API+ key)+ operationId: scim_createUsertags:- - Prompts+ - Scimparameters: []responses:'200':@@ -6009,237 +5261,7 @@ paths: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'+ $ref: '#/components/schemas/ScimUser''400':description: ''content:@@ -6595,56 +5617,148 @@ paths: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+ /api/public/scores:+ post:+ description: >-+ Create scores asynchronously from a list of scores. Returns 202 if all+ scores are accepted, or 207 with accepted/rejected counts and error+ messages. Do not automatically retry a 207 batch. The generated+ reference shows only 200; the endpoint returns 202 or 207.+ operationId: scores_createtags:- - 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+ - Scores+ parameters: []+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/CreateScoresResponse'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ security: *ref_0+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/CreateScoresRequest'+ /api/public/scores/{scoreId}:+ delete:+ description: Delete a score (supports both trace and session scores)+ operationId: scores_delete+ tags:+ - Scores+ parameters:+ - name: scoreId+ in: path+ description: The unique langfuse identifier of a score+ required: true+ schema:+ type: string+ responses:+ '204':+ description: ''+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ security: *ref_0+ /api/public/v3/scores:+ get:+ description: |-+ Get a list of scores with a polymorphic `value` field (v3).++ The `value` field type depends on `dataType`:+ - `NUMERIC` → number+ - `BOOLEAN` → boolean+ - `CATEGORICAL`, `TEXT`, `CORRECTION` → string++ The response always includes the core fields: id, projectId, name,+ value, dataType, source, timestamp, environment, createdAt, updatedAt.++ Additional field groups can be requested via the `fields` parameter:+ - `details` — adds comment, configId, metadata+ - `subject` — adds the subject object describing the entity the score+ is attached to: kind (trace, observation, session, or experiment),+ id, and traceId for observation-level scores+ - `annotation` — adds authorUserId, queueId++ Unknown group names return HTTP 400.+ operationId: scores_getMany+ tags:+ - Scores+ parameters:+ - name: limit+ in: query+ description: >-+ Number of items per page. Maximum 100, default 50. Requests with a+ limit greater than 100 return HTTP 400.+ required: false+ schema:+ type: integer+ nullable: true+ - name: cursor+ in: query+ description: >-+ URL-safe base64 (base64url) cursor for pagination. Use the cursor+ from the previous response to get the next page. Absent on the final+ page.+ required: false+ schema:+ type: string+ nullable: true+ - name: fields+ in: query+ description: >-+ Comma-separated field groups to include in addition to the+ always-returned core fields. Allowed: details, subject, annotation —+ see the endpoint description for the fields each group adds. Unknownnames return HTTP 400.required: falseschema:@@ -6839,16 +5953,58 @@ paths:application/json:schema: {}security: *ref_0- /api/public/scores:- post:- description: >-- Create scores asynchronously. Single score: 200 with ID. Batch: 202 if- accepted, or 207 with accepted/rejected counts and error messages. Do- not automatically retry a 207 batch. The generated reference shows only- 200; batches return 202 or 207.- operationId: scores_create+ /api/public/traces/{traceId}:+ delete:+ description: Delete a specific trace+ operationId: trace_deletetags:- - Scores+ - Trace+ parameters:+ - name: traceId+ in: path+ description: The unique langfuse identifier of the trace to delete+ required: true+ schema:+ type: string+ responses:+ '200':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/DeleteTraceResponse'+ '400':+ description: ''+ content:+ application/json:+ schema: {}+ '401':+ description: ''+ content:+ application/json:+ schema: {}+ '403':+ description: ''+ content:+ application/json:+ schema: {}+ '404':+ description: ''+ content:+ application/json:+ schema: {}+ '405':+ description: ''+ content:+ application/json:+ schema: {}+ security: *ref_0+ /api/public/traces:+ delete:+ description: Delete multiple traces+ operationId: trace_deleteMultiple+ tags:+ - Traceparameters: []responses:'200':@@ -6856,7 +6012,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/CreateScoresResponse'+ $ref: '#/components/schemas/DeleteTraceResponse''400':description: ''content:@@ -6888,213 +6044,48 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/CreateScoresRequest'- /api/public/v2/scores:+ 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: >-- **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).-+ description: |-+ List dashboard widgets in the project, ordered by most recently+ updated first.- Get a list of scores (supports both trace and session scores)- operationId: scores_get-many+ Responses may include legacy `traces` widgets created before this+ API existed. New widgets cannot be created with `view: traces`.+ operationId: unstable_dashboardWidgets_listtags:- - Scores+ - UnstableDashboardWidgetsparameters:- name: pagein: query- description: Page number, starts at 1.+ description: 1-based page number. Defaults to `1`.required: falseschema:type: integernullable: true- name: limitin: 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.+ description: Maximum number of items per page. Defaults to `50`.required: falseschema:type: integernullable: true- - name: userId- in: query- description: Retrieve only scores with this userId associated to the trace.- required: false- schema:- type: string- nullable: true- - name: name- in: query- description: Retrieve only scores with this name.- required: false- schema:- type: string- nullable: true- - name: fromTimestamp- in: query- description: >-- Optional filter to only include scores created on or after a certain- datetime (ISO 8601)- required: false- schema:- type: string- format: date-time- nullable: true- - name: toTimestamp- in: query- description: >-- Optional filter to only include scores created before a certain- datetime (ISO 8601)- required: false- schema:- type: string- format: date-time- nullable: true- - name: environment- in: query- description: >-- Optional filter for scores where the environment is one of the- provided values.- required: false- schema:- type: array- items:- type: string- nullable: true- - name: source- in: query- description: Retrieve only scores from a specific source.- required: false- schema:- $ref: '#/components/schemas/ScoreSource'- nullable: true- - name: operator- in: query- description: Retrieve only scores with <operator> value.- required: false- schema:- type: string- nullable: true- - name: value- in: query- description: Retrieve only scores with <operator> value.- required: false- schema:- type: number- format: double- nullable: true- - name: scoreIds- in: query- description: Comma-separated list of score IDs to limit the results to.- required: false- schema:- type: string- nullable: true- - name: configId- in: query- description: Retrieve only scores with a specific configId.- required: false- schema:- type: string- nullable: true- - name: sessionId- in: query- description: Retrieve only scores with a specific sessionId.- required: false- schema:- type: string- nullable: true- - name: datasetRunId- in: query- description: Retrieve only scores with a specific datasetRunId.- required: false- schema:- type: string- nullable: true- - name: traceId- in: query- description: Retrieve only scores with a specific traceId.- required: false- schema:- type: string- nullable: true- - name: observationId- in: query- description: Comma-separated list of observation IDs to filter scores by.- required: false- schema:- type: string- nullable: true- - name: queueId- in: query- description: Retrieve only scores with a specific annotation queueId.- required: false- schema:- type: string- nullable: true- - name: dataType- in: query- description: Retrieve only scores with a specific dataType.- required: false- schema:- $ref: '#/components/schemas/ScoreDataType'- nullable: true- - name: traceTags- in: query- description: >-- Only scores linked to traces that include all of these tags will be- returned.- required: false- schema:- type: array- items:- type: string- nullable: true- - name: fields- in: query- description: >-- Comma-separated list of field groups to include in the response.- Available field groups: 'score' (core score fields), 'trace' (trace- properties: userId, tags, environment, sessionId). If not specified,- both 'score' and 'trace' are returned by default. Example: 'score'- to exclude trace data, 'score,trace' to include both. Note: When- filtering by trace properties (using userId or traceTags- parameters), the 'trace' field group must be included, otherwise a- 400 error will be returned.- required: false- schema:- type: string- nullable: true- - name: filter- in: query- description: >-- A JSON stringified array of filter objects. Each object requires- type, column, operator, and value. Supports filtering by score- metadata using the stringObject type. Example:- [{"type":"stringObject","column":"metadata","key":"user_id","operator":"=","value":"abc123"}].- Supported types: stringObject (metadata key-value filtering),- string, number, datetime, stringOptions, arrayOptions. Supported- operators for stringObject: =, contains, does not contain, starts- with, ends with, is set, is not set. Use is set / is not set to- filter on metadata key presence. An empty value for contains, starts- with, or ends with is treated as is set (key presence).- required: false- schema:- type: string- nullable: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/GetScoresResponse'+ $ref: '#/components/schemas/unstableDashboardWidgetList''400':description: ''content:@@ -7120,38 +6111,61 @@ paths: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- deprecated: true- /api/public/v2/scores/{scoreId}:- get:+ post: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).+ 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`.- Get a score (supports both trace and session scores)- operationId: scores_get-by-id+ Unstable API note:++ - This surface may evolve while dashboard/widget APIs are being+ finalized.+ operationId: unstable_dashboardWidgets_createtags:- - Scores- parameters:- - name: scoreId- in: path- description: The unique langfuse identifier of a score- required: true- schema:- type: string+ - UnstableDashboardWidgets+ parameters: []responses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Score'+ $ref: '#/components/schemas/unstableDashboardWidget''400':description: ''content:@@ -7177,91 +6191,47 @@ paths: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- deprecated: true- /api/public/sessions:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest'+ /api/public/unstable/dashboard-widgets/{widgetId}:get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, read- session data via `GET /api/public/v2/observations?filter=<urlencoded- sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted- deployments are unaffected by this date; the endpoint becomes- unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4- upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get sessions.--- This legacy endpoint is not recommended for new data extraction- workflows.-- Use the v2 observations endpoint with a bounded time range and group- rows by-- `sessionId` instead:+ description: |-+ Get a dashboard widget by id.- `GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.- operationId: sessions_list+ The response may use `view: traces` for legacy widgets.+ operationId: unstable_dashboardWidgets_gettags:- - Sessions+ - UnstableDashboardWidgetsparameters:- - 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+ - name: widgetId+ in: path+ required: trueschema: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: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/PaginatedSessions'+ $ref: '#/components/schemas/unstableDashboardWidget''400':description: ''content:@@ -7287,40 +6257,36 @@ paths: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- deprecated: true- /api/public/sessions/{sessionId}:- get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, read- session data via `GET /api/public/v2/observations?filter=<urlencoded- sessionId filter>&fromStartTime=<from>&toStartTime=<to>`. Self-hosted- deployments are unaffected by this date; the endpoint becomes- unavailable when they upgrade to Langfuse v4. See the [Langfuse v3 to v4- upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get a session.--- Please note that `traces` on this endpoint are not paginated. For large-- sessions or new data extraction workflows, use the v2 observations- endpoint+ patch:+ description: |-+ Update a dashboard widget.- with a URL-encoded `sessionId` filter and a bounded time range:+ 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`.- `GET /api/public/v2/observations?filter=<sessionId- filter>&fromStartTime=<from>&toStartTime=<to>`.- operationId: sessions_get+ `view` cannot be changed to the legacy `traces` value. Existing+ `traces` widgets may be updated on other fields.+ operationId: unstable_dashboardWidgets_updatetags:- - Sessions+ - UnstableDashboardWidgetsparameters:- - name: sessionId+ - name: widgetIdin: path- description: The unique id of a sessionrequired: trueschema:type: string@@ -7330,7 +6296,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/SessionWithTraces'+ $ref: '#/components/schemas/unstableDashboardWidget''400':description: ''content:@@ -7356,44 +6322,113 @@ paths: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- deprecated: true- /api/public/traces/{traceId}:- get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, read span- and trace data via `GET- /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.- Self-hosted deployments are unaffected by this date; the endpoint- becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse- v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get a specific trace- operationId: trace_get+ 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_deletetags:- - Trace+ - UnstableDashboardWidgetsparameters:- - name: traceId+ - name: widgetIdin: path- description: The unique langfuse identifier of a tracerequired: trueschema:type: string- - name: fields+ 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: pagein: 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'.+ description: 1-based page number. Defaults to `1`.required: falseschema:- type: string+ type: integer+ nullable: true+ - name: limit+ in: query+ description: Maximum number of items per page. Defaults to `50`.+ required: false+ schema:+ type: integernullable: trueresponses:'200':@@ -7401,7 +6436,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/TraceWithFullDetails'+ $ref: '#/components/schemas/unstableDashboardList''400':description: ''content:@@ -7427,17 +6462,85 @@ paths: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- deprecated: true- delete:- description: Delete a specific trace- operationId: trace_delete+ post:+ description: Create a dashboard.+ operationId: unstable_dashboards_createtags:- - Trace+ - 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:+ - UnstableDashboardsparameters:- - name: traceId+ - name: dashboardIdin: path- description: The unique langfuse identifier of the trace to deleterequired: trueschema:type: string@@ -7447,7 +6550,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/DeleteTraceResponse'+ $ref: '#/components/schemas/unstableDashboard''400':description: ''content:@@ -7473,319 +6576,37 @@ paths: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/traces:- get:- description: >-- **Deprecated:** On Langfuse Cloud, Langfuse v3 is deprecated and this- endpoint will be removed on November 16, 2026. In Langfuse v4, read span- and trace data via `GET- /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>`.- Self-hosted deployments are unaffected by this date; the endpoint- becomes unavailable when they upgrade to Langfuse v4. See the [Langfuse- v3 to v4 upgrade- guide](https://langfuse.com/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4).--- Get list of traces- operationId: trace_list+ patch:+ description: Update a dashboard's name, description, definition, or filters.+ operationId: unstable_dashboards_updatetags:- - Trace+ - UnstableDashboardsparameters:- - 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+ - name: dashboardId+ in: path+ required: trueschema: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: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/Traces'+ $ref: '#/components/schemas/unstableDashboard''400':description: ''content:@@ -7811,21 +6632,43 @@ paths: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- deprecated: true+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableUpdateDashboardRequest'delete:- description: Delete multiple traces- operationId: trace_deleteMultiple+ description: Delete a dashboard.+ operationId: unstable_dashboards_deletetags:- - Trace- parameters: []+ - UnstableDashboards+ parameters:+ - name: dashboardId+ in: path+ required: true+ schema:+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/DeleteTraceResponse'+ $ref: '#/components/schemas/unstableDeleteDashboardResponse''400':description: ''content:@@ -7851,54 +6694,48 @@ paths: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:- type: object- properties:- traceIds:- type: array- items:- type: string- description: List of trace IDs to delete- required:- - traceIds- /api/public/unstable/dashboard-widgets:- get:+ /api/public/unstable/dashboards/{dashboardId}/placements:+ post:description: |-- List dashboard widgets in the project, ordered by most recently- updated first.+ Add a placement to a dashboard grid (see `DashboardPlacement` for+ grid semantics).- Responses may include legacy `traces` widgets created before this- API existed. New widgets cannot be created with `view: traces`.- operationId: unstable_dashboardWidgets_list+ `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_addPlacementtags:- - UnstableDashboardWidgets+ - UnstableDashboardsparameters:- - 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+ - name: dashboardId+ in: path+ required: trueschema:- type: integer- nullable: true+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardWidgetList'+ $ref: '#/components/schemas/unstableDashboardPlacement''400':description: ''content:@@ -7924,6 +6761,12 @@ paths:content:application/json:schema: {}+ '409':+ description: ''+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstablePublicApiError''429':description: ''content:@@ -7937,48 +6780,40 @@ paths: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+ 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_updatePlacementtags:- - UnstableDashboardWidgets- parameters: []+ - UnstableDashboards+ parameters:+ - name: dashboardId+ in: path+ required: true+ schema:+ type: string+ - name: placementId+ in: path+ required: true+ schema:+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardWidget'+ $ref: '#/components/schemas/unstableDashboardPlacement''400':description: ''content:@@ -8022,18 +6857,21 @@ paths: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+ $ref: '#/components/schemas/unstableUpdateDashboardPlacementRequest'+ delete:+ description: >-+ Remove a placement from a dashboard grid without deleting the referenced+ widget.+ operationId: unstable_dashboards_deletePlacementtags:- - UnstableDashboardWidgets+ - UnstableDashboardsparameters:- - name: widgetId+ - name: dashboardId+ in: path+ required: true+ schema:+ type: string+ - name: placementIdin: pathrequired: trueschema:@@ -8044,7 +6882,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardWidget'+ $ref: '#/components/schemas/unstableDeleteDashboardPlacementResponse''400':description: ''content:@@ -8083,33 +6921,77 @@ paths: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+ /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_listtags:- - UnstableDashboardWidgets+ - UnstableSkillsparameters:- - name: widgetId- in: path- required: true+ - 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: falseschema:type: string+ format: date-time+ nullable: trueresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardWidget'+ $ref: '#/components/schemas/unstableSkillMetaListResponse''400':description: ''content:@@ -8135,47 +7017,20 @@ paths: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+ post:+ description: Create skill version+ operationId: unstable_skills_createVersiontags:- - UnstableDashboardWidgets- parameters:- - name: widgetId- in: path- required: true- schema:- type: string+ - UnstableSkills+ parameters: []responses:- '200':+ '201':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse'+ $ref: '#/components/schemas/unstableSkillVersion''400':description: ''content:@@ -8201,47 +7056,39 @@ paths: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:+ requestBody:+ required: true+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/unstableCreateSkillVersionRequest'+ /api/public/unstable/skills/{skillName}:get:- description: |-- List dashboards in the project, ordered by most recently updated- first.- operationId: unstable_dashboards_list+ 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_gettags:- - UnstableDashboards+ - UnstableSkillsparameters:- - name: page+ - name: skillName+ in: path+ required: true+ schema:+ type: string+ - name: versionin: query- description: 1-based page number. Defaults to `1`.required: falseschema:type: integernullable: true- - name: limit+ - name: labelin: query- description: Maximum number of items per page. Defaults to `50`.required: falseschema:- type: integer+ type: stringnullable: trueresponses:'200':@@ -8249,7 +7096,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardList'+ $ref: '#/components/schemas/unstableSkillVersion''400':description: ''content:@@ -8275,32 +7122,28 @@ paths: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+ 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_updatetags:- - UnstableDashboards- parameters: []+ - UnstableSkills+ parameters:+ - name: skillName+ in: path+ required: true+ schema:+ type: stringresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboard'+ $ref: '#/components/schemas/unstableSkillVersion''400':description: ''content:@@ -8326,34 +7169,27 @@ paths: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_0requestBody:required: truecontent:application/json:schema:- $ref: '#/components/schemas/unstableCreateDashboardRequest'- /api/public/unstable/dashboards/{dashboardId}:+ $ref: '#/components/schemas/unstableUpdateSkillRequest'+ /api/public/unstable/skills/files/content:get:- description: Get a dashboard by id.- operationId: unstable_dashboards_get+ description: >-+ Read a batch of text contents by canonical base64-encoded SHA-256 hashes.+ operationId: unstable_skills_getFileContentstags:- - UnstableDashboards+ - UnstableSkillsparameters:- - name: dashboardId- in: path+ - 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: trueschema:type: string@@ -8363,7 +7199,7 @@ paths:content:application/json:schema:- $ref: '#/components/schemas/unstableDashboard'+ $ref: '#/components/schemas/unstableSkillFileContentsResponse''400':description: ''content:@@ -8389,37 +7225,33 @@ paths: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/{skillName}/versions/{skillVersion}:patch:- description: Update a dashboard's name, description, definition, or filters.- operationId: unstable_dashboards_update+ description: >-+ Replace the labels on a skill version and atomically move them from+ other versions.+ operationId: unstable_skills_setLabelstags:- - UnstableDashboards+ - UnstableSkillsparameters:- - name: dashboardId+ - name: skillNamein: pathrequired: trueschema:type: string+ - name: skillVersion+ in: path+ required: true+ schema:+ type: integerresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboard'+ $ref: '#/components/schemas/unstableSkillVersion''400':description: ''content:@@ -8445,110 +7277,38 @@ paths: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_0requestBody:required: truecontent:application/json:schema:- $ref: '#/components/schemas/unstableUpdateDashboardRequest'+ $ref: '#/components/schemas/unstableUpdateSkillLabelsRequest'delete:- description: Delete a dashboard.- operationId: unstable_dashboards_delete+ description: >-+ Delete one immutable skill version. Unreferenced blobs are retained for+ asynchronous cleanup.+ operationId: unstable_skills_deleteVersiontags:- - UnstableDashboards+ - UnstableSkillsparameters:- - name: dashboardId+ - name: skillNamein: pathrequired: trueschema: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+ - name: skillVersionin: pathrequired: trueschema:- type: string+ type: integerresponses:'200':description: ''content:application/json:schema:- $ref: '#/components/schemas/unstableDashboardPlacement'+ $ref: '#/components/schemas/unstableDeleteSkillVersionResponse''400':description: ''content:@@ -8574,1060 +7334,37 @@ paths: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:+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- - 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- - GOOGLE_CLOUD_STORAGE- BlobStorageIntegrationFileType:- title: BlobStorageIntegrationFileType- type: string- enum:- - JSON- - CSV- - JSONL- - PARQUET- description: >-- File format for exported data. `PARQUET` is a columnar binary format- encoded and compressed by the storage engine; gzip compression does not- apply to it. Note that the model-price columns (`input_price`,- `output_price`, `total_price`) are not included in Parquet observation- exports.- BlobStorageIntegrationFileTypeResponse:- title: BlobStorageIntegrationFileTypeResponse- type: string- enum:- - JSON- - CSV- - JSONL- - PARQUET- description: File type reported for an existing integration.- BlobStorageExportMode:- title: BlobStorageExportMode- type: string- enum:- - FULL_HISTORY- - FROM_TODAY- - FROM_CUSTOM_DATE- BlobStorageExportFrequency:- title: BlobStorageExportFrequency- type: string- enum:- - every_20_minutes- - hourly- - daily- - weekly- BlobStorageExportSource:- title: BlobStorageExportSource- type: string- enum:- - LEGACY_TRACES_OBSERVATIONS- - OBSERVATIONS_V2- - LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS- description: >-- What data the integration exports.-- - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables.- Observation columns are controlled by `exportFieldGroups`; field groups- without a counterpart in this data model (e.g. `trace_context`) are- omitted.-- - `OBSERVATIONS_V2`: same data model as the- `/api/public/v2/observations` endpoint, plus scores. Columns are- controlled by `exportFieldGroups`.-- - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation- columns of both portions are controlled by `exportFieldGroups`.--- **Note:** which sources a deployment accepts depends on how far it has- moved to the v4 data model. `OBSERVATIONS_V2` and the- enriched-observations portion of- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations- table, so they require a deployment that already populates it.- `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and- observations tables, so they require a deployment that still populates- those. A deployment part-way through the migration populates both and- accepts every source. Selecting a source the deployment cannot serve is- rejected with `400`, rather than exporting an empty result. See- https://langfuse.com/docs/v4.- BlobStorageExportFieldGroup:- title: BlobStorageExportFieldGroup- type: string- enum:- - core- - basic- - time- - io- - metadata- - model- - usage- - prompt- - metrics- - tools- - trace_context- 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). For GOOGLE_CLOUD_STORAGE with default- credentials, the bucket must be listed in- `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.- endpoint:- type: string- nullable: true- description: >-- Custom endpoint URL (required for S3_COMPATIBLE type). Ignored for- GOOGLE_CLOUD_STORAGE.- region:- type: string- description: >-- Storage region used by S3-compatible clients (AWS, GCS, Cloudflare- R2, MinIO, Azure location IDs such as eastus, OCI). Leading and- trailing whitespace is removed. The remaining value must be 1-63- letters, numbers, or hyphens, and cannot start or end with a hyphen.- Examples: us-east-1, europe-west1, eastus, auto. Not used by- GOOGLE_CLOUD_STORAGE; pass auto.- accessKeyId:- type: string- nullable: true- description: Access key ID for authentication. Not used for GOOGLE_CLOUD_STORAGE.- secretAccessKey:- type: string- nullable: true- description: >-- Secret access key for authentication (will be encrypted when- stored). When omitted on update, the stored secret is kept, unless- the type changes between GOOGLE_CLOUD_STORAGE and another type.--- For GOOGLE_CLOUD_STORAGE, a GCP service account JSON key. On- self-hosted deployments, pass `__GCS_DEFAULT_CREDENTIALS__` instead- to use the deployment's Application Default Credentials; the bucket- must then be listed in `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.- Default credentials are not available on Langfuse Cloud.- prefix:- type: string- nullable: true- description: >-- Path prefix for exported files (must end with forward slash if- provided)- exportFrequency:- $ref: '#/components/schemas/BlobStorageExportFrequency'- enabled:- type: boolean- description: Whether the integration is active- forcePathStyle:- type: boolean- description: Use path-style URLs for S3 requests- fileType:- $ref: '#/components/schemas/BlobStorageIntegrationFileType'- exportMode:- $ref: '#/components/schemas/BlobStorageExportMode'- exportStartDate:- type: string- format: date-time- nullable: true- description: >-- Custom start date for exports (required when exportMode is- FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for- timezone differences).- compressed:- type: boolean- nullable: true- description: >-- Enable gzip compression for exported files (.csv.gz, .json.gz,- .jsonl.gz). Defaults to true.- exportSource:- $ref: '#/components/schemas/BlobStorageExportSource'- nullable: true- description: >-- Data to export. When omitted on update, the existing value is- preserved. When omitted on create, the default is `OBSERVATIONS_V2`- on Langfuse Cloud, and on self-hosted deployments- `LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the- deployment no longer populates the legacy tables. The default is- never a source the deployment cannot serve. Required when- `exportFieldGroups` is provided.--- **Cloud-only project deprecation gate (effective 2026-05-20):** For- projects created on or after 2026-05-20 on Langfuse Cloud,- `LEGACY_TRACES_OBSERVATIONS` and- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP- 400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted- deployments are unaffected.--- **Cloud-only integration deprecation gate (effective 2026-06-22):**- On Langfuse Cloud, legacy export sources are only accepted for blob- storage integrations created before 2026-06-22, regardless of- project age. Requests that would create a new integration with- `LEGACY_TRACES_OBSERVATIONS` or- `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP- 400. Use `OBSERVATIONS_V2` instead. Self-hosted deployments are- unaffected.- exportFieldGroups:- type: array- items:- $ref: '#/components/schemas/BlobStorageExportFieldGroup'- nullable: true- description: >-- Field groups to include in each exported observation 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: truecreatedAt:type: stringformat: date-time@@ -9636,1432 +7373,934 @@ components:format: date-timerequired:- id- - projectId- - type- - bucketName- - endpoint- - region- - accessKeyId- - prefix- - exportFrequency- - enabled- - forcePathStyle- - fileType- - exportMode- - exportStartDate- - compressed- - exportSource- - exportFieldGroups- - nextSyncAt- - lastSyncAt- - lastError- - lastErrorAt+ - name+ - description+ - scoreConfigIds- 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+ AnnotationQueueItem:+ title: AnnotationQueueItemtype: objectproperties:id:type: string- projectId:+ queueId:type: string- syncStatus:- $ref: '#/components/schemas/BlobStorageSyncStatus'- enabled:- type: boolean- lastSyncAt:+ objectId: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:+ objectType:+ $ref: '#/components/schemas/AnnotationQueueObjectType'+ status:+ $ref: '#/components/schemas/AnnotationQueueStatus'+ completedAt:type: stringformat: date-timenullable: true- description: When the next export is scheduled. Null if no sync has occurred yet.- lastError:+ createdAt: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:+ format: date-time+ updatedAt:type: stringformat: date-time- nullable: true- description: When the last error occurred. Cleared on successful export.required:- id- - projectId- - syncStatus- - enabled- - lastSyncAt- - nextSyncAt- - lastError- - lastErrorAt- BlobStorageIntegrationDeletionResponse:- title: BlobStorageIntegrationDeletionResponse- type: object- properties:- message:- type: string- required:- - message- CreateCommentRequest:- title: CreateCommentRequest- type: object- properties:- projectId:- type: string- description: The id of the project to attach the comment to.- objectType:- type: string- description: >-- The type of the object to attach the comment to (trace, observation,- session, prompt).- objectId:- type: string- description: >-- The id of the object to attach the comment to. If this does not- reference a valid existing object, an error will be thrown.- content:- type: string- description: >-- The content of the comment. May include markdown. Currently limited- to 5000 characters.- authorUserId:- type: string- nullable: true- description: >-- The id of the user who created the comment. Must be a member of the- organization that owns the project, otherwise an error will be- thrown.- required:- - projectId- - objectType+ - queueId- 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+ - objectType+ - status+ - createdAt+ - updatedAt+ PaginatedAnnotationQueues:+ title: PaginatedAnnotationQueuestype: objectproperties:data:type: arrayitems:- $ref: '#/components/schemas/Comment'+ $ref: '#/components/schemas/AnnotationQueue'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.+ - data+ - meta+ PaginatedAnnotationQueueItems:+ title: PaginatedAnnotationQueueItems+ type: object+ properties:+ data:+ type: array+ items:+ $ref: '#/components/schemas/AnnotationQueueItem'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'required:- - message- Trace:- title: Trace+ - data+ - meta+ CreateAnnotationQueueRequest:+ title: CreateAnnotationQueueRequesttype: objectproperties:- id:- type: string- description: The unique identifier of a trace- timestamp:- type: string- format: date-time- description: The timestamp when the trace was createdname: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:+ description:type: stringnullable: true- description: The user identifier associated with the trace- metadata:- type: object- additionalProperties: true- nullable: true- description: >-- The metadata associated with the trace. Values can be any JSON;- non-object metadata sent at ingestion is returned under the- `metadata` key.- tags:+ scoreConfigIds:type: arrayitems: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+ - scoreConfigIds+ CreateAnnotationQueueItemRequest:+ title: CreateAnnotationQueueItemRequesttype: objectproperties:- htmlPath:+ objectId: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+ objectType:+ $ref: '#/components/schemas/AnnotationQueueObjectType'+ status:+ $ref: '#/components/schemas/AnnotationQueueStatus'nullable: true- description: List of observation ids- scores:- type: array- items:- type: string+ description: Defaults to PENDING for new queue items+ required:+ - objectId+ - objectType+ UpdateAnnotationQueueItemRequest:+ title: UpdateAnnotationQueueItemRequest+ type: object+ properties:+ status:+ $ref: '#/components/schemas/AnnotationQueueStatus'nullable: true- description: List of score ids+ DeleteAnnotationQueueItemResponse:+ title: DeleteAnnotationQueueItemResponse+ type: object+ properties:+ success:+ type: boolean+ message:+ type: stringrequired:- - htmlPath- allOf:- - $ref: '#/components/schemas/Trace'- TraceWithFullDetails:- title: TraceWithFullDetails+ - success+ - message+ AnnotationQueueAssignmentRequest:+ title: AnnotationQueueAssignmentRequesttype: objectproperties:- htmlPath:+ userId: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: truerequired:- - htmlPath- - observations- - scores- allOf:- - $ref: '#/components/schemas/Trace'- Session:- title: Session+ - userId+ DeleteAnnotationQueueAssignmentResponse:+ title: DeleteAnnotationQueueAssignmentResponsetype: objectproperties:- id:+ success:+ type: boolean+ required:+ - success+ CreateAnnotationQueueAssignmentResponse:+ title: CreateAnnotationQueueAssignmentResponse+ type: object+ properties:+ userId:type: string- createdAt:+ queueId:type: string- format: date-timeprojectId:type: string- environment:- type: string- description: The environment from which this session originated.required:- - id- - createdAt+ - userId+ - queueId- 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+ BlobStorageIntegrationType:+ title: BlobStorageIntegrationType+ type: string+ enum:+ - S3+ - S3_COMPATIBLE+ - AZURE_BLOB_STORAGE+ - GOOGLE_CLOUD_STORAGE+ BlobStorageIntegrationFileType:+ title: BlobStorageIntegrationFileType+ type: string+ enum:+ - JSON+ - CSV+ - JSONL+ - PARQUET+ description: >-+ File format for exported data. `PARQUET` is a columnar binary format+ encoded and compressed by the storage engine; gzip compression does not+ apply to it. Note that the model-price columns (`input_price`,+ `output_price`, `total_price`) are not included in Parquet observation+ exports.+ BlobStorageIntegrationFileTypeResponse:+ title: BlobStorageIntegrationFileTypeResponse+ type: string+ enum:+ - JSON+ - CSV+ - JSONL+ - PARQUET+ description: File type reported for an existing integration.+ BlobStorageExportMode:+ title: BlobStorageExportMode+ type: string+ enum:+ - FULL_HISTORY+ - FROM_TODAY+ - FROM_CUSTOM_DATE+ BlobStorageExportFrequency:+ title: BlobStorageExportFrequency+ type: string+ enum:+ - every_20_minutes+ - hourly+ - daily+ - weekly+ BlobStorageExportSource:+ title: BlobStorageExportSource+ type: string+ enum:+ - LEGACY_TRACES_OBSERVATIONS+ - OBSERVATIONS_V2+ - LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS+ description: >-+ What data the integration exports.++ - `LEGACY_TRACES_OBSERVATIONS`: traces, observations, and scores tables.+ Observation columns are controlled by `exportFieldGroups`; field groups+ without a counterpart in this data model (e.g. `trace_context`) are+ omitted.++ - `OBSERVATIONS_V2`: same data model as the+ `/api/public/v2/observations` endpoint, plus scores. Columns are+ controlled by `exportFieldGroups`.++ - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation+ columns of both portions are controlled by `exportFieldGroups`.+++ **Note:** which sources a deployment accepts depends on how far it has+ moved to the v4 data model. `OBSERVATIONS_V2` and the+ enriched-observations portion of+ `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations+ table, so they require a deployment that already populates it.+ `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of+ `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and+ observations tables, so they require a deployment that still populates+ those. A deployment part-way through the migration populates both and+ accepts every source. Selecting a source the deployment cannot serve is+ rejected with `400`, rather than exporting an empty result. See+ https://langfuse.com/docs/v4.+ BlobStorageExportFieldGroup:+ title: BlobStorageExportFieldGroup+ type: string+ enum:+ - core+ - basic+ - time+ - io+ - metadata+ - model+ - usage+ - prompt+ - metrics+ - tools+ - trace_context+ 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: CreateBlobStorageIntegrationRequesttype: objectproperties:- id:- type: string- description: The unique identifier of the observation- traceId:+ projectId:type: string- nullable: true- description: The trace ID associated with the observation+ description: ID of the project in which to configure the blob storage integrationtype:+ $ref: '#/components/schemas/BlobStorageIntegrationType'+ bucketName: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:+ description: >-+ Name of the storage bucket. For AZURE_BLOB_STORAGE, must be a valid+ Azure container name (3-63 chars, lowercase letters, numbers, and+ hyphens only, must start and end with a letter or number, no+ consecutive hyphens). For GOOGLE_CLOUD_STORAGE with default+ credentials, the bucket must be listed in+ `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.+ endpoint:type: stringnullable: true- description: The version of the observation- metadata:- type: object- additionalProperties: true- nullable: true- description: Additional metadata of the observation- output:- description: The output data of the observation- usage:- $ref: '#/components/schemas/Usage'description: >-- (Deprecated. Use usageDetails and costDetails instead.) The usage- data of the observation- level:- $ref: '#/components/schemas/ObservationLevel'- description: The level of the observation- statusMessage:+ Custom endpoint URL (required for S3_COMPATIBLE type). Ignored for+ GOOGLE_CLOUD_STORAGE.+ region:type: string- nullable: true- description: The status message of the observation- parentObservationId:+ description: >-+ Storage region used by S3-compatible clients (AWS, GCS, Cloudflare+ R2, MinIO, Azure location IDs such as eastus, OCI). Leading and+ trailing whitespace is removed. The remaining value must be 1-63+ letters, numbers, or hyphens, and cannot start or end with a hyphen.+ Examples: us-east-1, europe-west1, eastus, auto. Not used by+ GOOGLE_CLOUD_STORAGE; pass auto.+ accessKeyId:type: stringnullable: true- description: The parent observation ID- promptId:+ description: Access key ID for authentication. Not used for GOOGLE_CLOUD_STORAGE.+ secretAccessKey:type: stringnullable: true- description: The prompt ID associated with the observation- usageDetails:- type: object- additionalProperties:- type: integerdescription: >-- 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- - output- - usage- - level- - statusMessage- - parentObservationId- - promptId- - usageDetails- - costDetails- - environment- ObservationsView:- title: ObservationsView- type: object- properties:- promptName:+ Secret access key for authentication (will be encrypted when+ stored). When omitted on update, the stored secret is kept, unless+ the type changes between GOOGLE_CLOUD_STORAGE and another type.+++ For GOOGLE_CLOUD_STORAGE, a GCP service account JSON key. On+ self-hosted deployments, pass `__GCS_DEFAULT_CREDENTIALS__` instead+ to use the deployment's Application Default Credentials; the bucket+ must then be listed in `LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS`.+ Default credentials are not available on Langfuse Cloud.+ prefix:type: stringnullable: 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:+ 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- 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+ format: date-timenullable: truedescription: >-- (Deprecated. Use usageDetails and costDetails instead.) The- calculated cost of the input in USD- calculatedOutputCost:- type: number- format: double+ 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: booleannullable: truedescription: >-- (Deprecated. Use usageDetails and costDetails instead.) The- calculated cost of the output in USD- calculatedTotalCost:- type: number- format: double+ Enable gzip compression for exported files (.csv.gz, .json.gz,+ .jsonl.gz). Defaults to true.+ exportSource:+ $ref: '#/components/schemas/BlobStorageExportSource'nullable: truedescription: >-- (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+ 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: The time to the first token in seconds+ 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:- - 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+ - projectId+ - type+ - bucketName+ - region+ - exportFrequency+ - enabled+ - forcePathStyle+ - fileType+ - exportMode+ BlobStorageIntegrationResponse:+ title: BlobStorageIntegrationResponsetype: 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:+ properties:+ id:type: string- format: date-time- nullable: true- description: The end time of the observationprojectId: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:+ $ref: '#/components/schemas/BlobStorageIntegrationType'+ bucketName: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:+ endpoint:type: stringnullable: true- description: The name of the observation- level:- $ref: '#/components/schemas/ObservationLevel'- nullable: true- description: The level of the observation- statusMessage:+ region:type: string- nullable: true- description: The status message of the observation- version:+ accessKeyId:type: stringnullable: true- description: The version of the observation- environment:+ prefix:type: string- nullable: true- description: The environment from which this observation originated- bookmarked:+ exportFrequency:+ $ref: '#/components/schemas/BlobStorageExportFrequency'+ enabled:type: boolean- nullable: true- description: Whether the observation is bookmarked- public:+ forcePathStyle: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:+ fileType:+ $ref: '#/components/schemas/BlobStorageIntegrationFileTypeResponse'+ exportMode:+ $ref: '#/components/schemas/BlobStorageExportMode'+ exportStartDate:type: stringformat: date-timenullable: true- description: The last update timestamp of the observation- input:- nullable: true- description: The input data of the observation- output:- nullable: true- description: The output data of the observation- metadata:- type: object- additionalProperties: true- nullable: true- description: Additional metadata of the observation- model:- type: string- nullable: true- description: The model name as provided by the user- internalModelId:- type: string- nullable: true- description: The internal model ID matched by Langfuse- modelParameters:- nullable: true- description: The parameters of the model used for the observation- usageDetails:- type: object- additionalProperties:- type: integer- nullable: true- description: >-- The usage details of the observation. Key is the usage metric name,- value is the number of units consumed.- costDetails:- type: object- additionalProperties:- type: number- format: double- nullable: true- description: >-- The cost details of the observation. Key is the cost metric name,- value is the cost in USD.- totalCost:- type: number- format: double- nullable: true- description: The total cost of the observation in USD- usagePricingTierName:- type: string+ compressed:+ type: boolean+ exportSource:+ $ref: '#/components/schemas/BlobStorageExportSource'+ exportFieldGroups:+ type: array+ items:+ $ref: '#/components/schemas/BlobStorageExportFieldGroup'nullable: truedescription: >-- 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:+ Field groups included in each exported observation row. An empty+ list is treated as all groups during export.+ nextSyncAt:type: string+ format: date-timenullable: true- description: >-- The matched model ID. Null when the `model` field group is not- requested.- inputPrice:+ lastSyncAt:type: string+ format: date-timenullable: 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:+ lastError:type: stringnullable: 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:+ lastErrorAt:type: string+ format: date-timenullable: 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:+ createdAt: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:+ format: date-time+ updatedAt:type: string- nullable: true- description: The release version of the parent trace+ format: date-timerequired:- 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+ - 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:- - input- - output- - total- - unit- ScoreConfig:- title: ScoreConfig+ - 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: BlobStorageIntegrationStatusResponsetype: object- description: Configuration for a scoreproperties:id:type: string- name:+ projectId:type: string- createdAt:+ syncStatus:+ $ref: '#/components/schemas/BlobStorageSyncStatus'+ enabled:+ type: boolean+ lastSyncAt:type: stringformat: date-time- updatedAt:+ 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: stringformat: 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: doublenullable: true- description: >-- Sets minimum value for numerical scores. If not set, the minimum- value defaults to -∞- maxValue:- type: number- format: double+ description: When the next export is scheduled. Null if no sync has occurred yet.+ lastError:+ type: stringnullable: truedescription: >-- 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:+ Raw error message from the storage provider (S3/Azure/GCS) if the+ last export failed. Cleared on successful export.+ lastErrorAt:type: string+ format: date-timenullable: true- description: Description of the score config+ description: When the last error occurred. Cleared on successful export.required:- id- - name- - createdAt- - updatedAt- projectId- - dataType- - isArchived- ConfigCategory:- title: ConfigCategory+ - syncStatus+ - enabled+ - lastSyncAt+ - nextSyncAt+ - lastError+ - lastErrorAt+ BlobStorageIntegrationDeletionResponse:+ title: BlobStorageIntegrationDeletionResponsetype: objectproperties:- value:- type: number- format: double- label:+ message:type: stringrequired:- - value- - label- BaseScoreV1:- title: BaseScoreV1+ - message+ CreateCommentRequest:+ title: CreateCommentRequesttype: objectproperties:- 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:+ projectId:type: string- nullable: true- description: The user ID of the author- comment:+ description: The id of the project to attach the comment to.+ objectType:type: string- nullable: true- description: Comment on the score- metadata:- type: object- additionalProperties: true- nullable: true- description: Metadata associated with the score- configId:+ description: >-+ The type of the object to attach the comment to (trace, observation,+ session, prompt).+ objectId:type: string- nullable: truedescription: >-- 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:+ 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- nullable: truedescription: >-- The annotation queue referenced by the score. Indicates if score was- initially created while processing annotation queue.- environment:+ The content of the comment. May include markdown. Currently limited+ to 5000 characters.+ authorUserId:type: string+ nullable: truedescription: >-- The environment from which this score originated. Can be any- lowercase alphanumeric string with hyphens and underscores that does- not start with 'langfuse'.+ The id of the user who created the comment. Must be a member of the+ organization that owns the project, otherwise an error will be+ thrown.required:- - id- - traceId- - name- - source- - timestamp- - createdAt- - updatedAt- - authorUserId- - comment- - configId- - queueId- - environment- NumericScoreV1:- title: NumericScoreV1+ - projectId+ - objectType+ - objectId+ - content+ CreateCommentResponse:+ title: CreateCommentResponsetype: objectproperties:- value:- type: number- format: double- description: The numeric value of the score+ id:+ type: string+ description: The id of the created object in Langfuserequired:- - value- allOf:- - $ref: '#/components/schemas/BaseScoreV1'- BooleanScoreV1:- title: BooleanScoreV1+ - id+ GetCommentsResponse:+ title: GetCommentsResponsetype: objectproperties:- 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"+ data:+ type: array+ items:+ $ref: '#/components/schemas/Comment'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'required:- - value- - stringValue- allOf:- - $ref: '#/components/schemas/BaseScoreV1'- CategoricalScoreV1:- title: CategoricalScoreV1+ - data+ - meta+ Deprecation:+ title: Deprecationtype: object- properties:- value:- type: number- format: double+ description: >-+ Migration signal returned by deprecated endpoints. Optional fields are+ omitted when they have no value.+ properties:+ message:+ type: stringdescription: >-- Represents the numeric category mapping of the stringValue. If no- config is linked, defaults to 0.- stringValue:+ Human- and agent-readable summary of the deprecation and its+ replacement.+ replacement:type: string+ nullable: truedescription: >-- 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:+ The replacement endpoint, e.g. "GET /api/public/v2/observations".+ Omitted when the endpoint is being removed without a direct+ replacement.+ docsUrl:type: string- description: The text content of the score (1-500 characters)+ 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:- - 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+ - message+ ObservationV2:+ title: ObservationV2type: 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 observationtraceId:type: stringnullable: true- description: The trace ID associated with the score- sessionId:+ 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-timenullable: true- description: The session ID associated with the score- observationId:+ description: The end time of the observation+ projectId:+ type: string+ description: The project ID this observation belongs to+ parentObservationId:type: stringnullable: true- description: The observation ID associated with the score- datasetRunId:+ 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: booleannullable: true- description: The dataset run ID associated with the score+ 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- source:- $ref: '#/components/schemas/ScoreSource'- timestamp:+ 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: stringformat: date-time+ nullable: true+ description: The completion start time of the observationcreatedAt:type: stringformat: date-time+ nullable: true+ description: The creation timestamp of the observationupdatedAt:type: stringformat: date-time- authorUserId:- type: stringnullable: true- description: The user ID of the author- comment:- type: string+ description: The last update timestamp of the observation+ input:nullable: true- description: Comment on the score+ description: The input data of the observation+ output:+ nullable: true+ description: The output data of the observationmetadata:type: objectadditionalProperties: truenullable: true- description: Metadata associated with the score- configId:+ description: Additional metadata of the observation+ model:type: stringnullable: 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:+ description: The model name as provided by the user+ internalModelId:type: stringnullable: 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: truedescription: >-- The annotation queue referenced by the score. Indicates if score was- initially created while processing annotation queue.- environment:- type: string- description: >-- The environment from which this score originated. Can be any- lowercase alphanumeric string with hyphens and underscores that does- not start with 'langfuse'.- required:- - id- - name- - source- - timestamp- - createdAt- - updatedAt- - authorUserId- - comment- - configId- - queueId- - environment- NumericScore:- title: NumericScore- type: object- properties:- value:- type: number- format: double- description: The numeric value of the score- required:- - value- allOf:- - $ref: '#/components/schemas/BaseScore'- BooleanScore:- title: BooleanScore- type: object- properties:- value:- type: number- format: double- description: >-- The numeric value of the score. Equals 1 for "True" and 0 for "False"- stringValue:- type: string+ 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: truedescription: >-- 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:+ The cost details of the observation. Key is the cost metric name,+ value is the cost in USD.+ totalCost:type: numberformat: double- description: >-- Represents the numeric category mapping of the stringValue. If no- config is linked, defaults to 0.- stringValue:+ nullable: true+ description: The total cost of the observation in USD+ usagePricingTierName:type: string+ nullable: truedescription: >-- 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:+ The name of the pricing tier applied to this observation's usage+ costs+ promptId: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:+ nullable: true+ description: The prompt ID associated with the observation+ promptName: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+ description: The prompt name associated with the observation+ promptVersion:+ type: integer+ nullable: true+ description: The prompt version associated with the observation+ latency:+ type: numberformat: 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:+ 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- createdAt:+ nullable: true+ description: >-+ The matched model ID. Null when the `model` field group is not+ requested.+ inputPrice:type: string- format: date-time- updatedAt:+ 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- format: date-time- objectType:- $ref: '#/components/schemas/CommentObjectType'- objectId:+ 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- content:+ 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- authorUserId:+ 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: stringnullable: true- description: The user ID of the comment author+ description: The release version of the parent tracerequired:- id+ - traceId+ - startTime+ - endTime- projectId- - createdAt- - updatedAt- - objectType- - objectId- - content- Dataset:- title: Dataset+ - parentObservationId+ - type+ - modelId+ - inputPrice+ - outputPrice+ - totalPrice+ Usage:+ title: Usagetype: object+ description: >-+ (Deprecated. Use usageDetails and costDetails instead.) Standard+ interface for usage and costproperties:- id:- type: string- name:- type: string- description:+ 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: stringnullable: true- description: Description of the dataset- metadata:- description: Metadata associated with the dataset- inputSchema:- type: object- additionalProperties: true+ description: Unit of measurement+ inputCost:+ type: number+ format: doublenullable: true- description: JSON Schema for validating dataset item inputs- expectedOutputSchema:- type: object- additionalProperties: true+ description: USD input cost+ outputCost:+ type: number+ format: doublenullable: 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+ description: USD output cost+ totalCost:+ type: number+ format: double+ nullable: true+ description: USD total cost, defaults to input+outputrequired:- - id- - name- - description- - metadata- - inputSchema- - expectedOutputSchema- - projectId- - createdAt- - updatedAt- DatasetItem:- title: DatasetItem+ - input+ - output+ - total+ - unit+ ScoreConfig:+ title: ScoreConfigtype: object+ description: Configuration for a scoreproperties: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:+ name:type: stringcreatedAt:type: string@@ -11069,2280 +8308,1794 @@ components:updatedAt:type: stringformat: date-time- mediaReferences:+ 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: arrayitems:- $ref: '#/components/schemas/DatasetItemMediaReference'- description: >-- Resolved Langfuse media references found in input, expectedOutput,- and metadata.+ $ref: '#/components/schemas/ConfigCategory'+ nullable: true+ description: Configures custom categories for categorical scores+ description:+ type: string+ nullable: true+ description: Description of the score configrequired:- id- - status- - input- - expectedOutput- - metadata- - sourceTraceId- - sourceObservationId- - datasetId- - datasetName+ - name- 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+ - projectId+ - dataType+ - isArchived+ ConfigCategory:+ title: ConfigCategorytype: objectproperties:- 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:+ value:+ type: number+ format: double+ label:type: string- description: The expiry date and time of the download URLrequired:- - mediaId- - contentType- - contentLength- - url- - urlExpiry- DatasetRunItem:- title: DatasetRunItem+ - value+ - label+ BaseScore:+ title: BaseScoretype: objectproperties:id:type: string- datasetRunId:- type: string- datasetRunName:- type: string- datasetItemId:- type: stringtraceId:type: string- observationId:- type: stringnullable: 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:+ description: The trace ID associated with the score+ sessionId:type: string- description: Unique identifier of the dataset run- name:+ nullable: true+ description: The session ID associated with the score+ observationId:type: string- description: Name of the dataset run- description:+ nullable: true+ description: The observation ID associated with the score+ datasetRunId:type: stringnullable: true- description: Description of the run- metadata:- description: Metadata of the dataset run- datasetId:+ description: The dataset run ID associated with the score+ name:type: string- description: Id of the associated dataset- datasetName:+ source:+ $ref: '#/components/schemas/ScoreSource'+ timestamp:type: string- description: Name of the associated dataset+ format: date-timecreatedAt:type: stringformat: date-time- description: The date and time when the dataset run was createdupdatedAt:type: stringformat: date-time- description: The date and time when the dataset run was last updated- required:- - id- - name- - description- - metadata- - datasetId- - datasetName- - createdAt- - updatedAt- DatasetRunWithItems:- title: DatasetRunWithItems- type: object- properties:- datasetRunItems:- type: array- items:- $ref: '#/components/schemas/DatasetRunItem'- _deprecation:- $ref: '#/components/schemas/Deprecation'- nullable: true- required:- - datasetRunItems- allOf:- - $ref: '#/components/schemas/DatasetRun'- Model:- title: Model- type: object- description: >-- Model definition used for transforming usage into USD cost and/or- tokenization.--- Models can have either simple flat pricing or tiered pricing:-- - Flat pricing: Single price per usage type (legacy, but still- supported)-- - Tiered pricing: Multiple pricing tiers with conditional matching based- on usage patterns or observation attributes--- The pricing tiers approach is recommended for models with usage-based- pricing variations.-- When using tiered pricing, the flat price fields (inputPrice,- outputPrice, prices) are populated-- from the default tier for backward compatibility.- properties:- id:- type: string- modelName:- type: string- description: >-- Name of the model definition. If multiple with the same name exist,- they are applied in the following order: (1) custom over built-in,- (2) newest according to startTime where- model.startTime<observation.startTime- matchPattern:- type: string- description: >-- Regex pattern which matches this model definition to- generation.model. Useful in case of fine-tuned models. If you want- to exact match, use `(?i)^modelname$`- startDate:+ authorUserId: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+ description: The user ID of the author+ comment:+ type: stringnullable: true- description: Deprecated. See 'prices' instead. Price (USD) per input unit- outputPrice:- type: number- format: double+ description: Comment on the score+ metadata:+ type: object+ additionalProperties: truenullable: true- description: Deprecated. See 'prices' instead. Price (USD) per output unit- totalPrice:- type: number- format: double+ description: Metadata associated with the score+ configId:+ type: stringnullable: truedescription: >-- Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot- be set if input or output price is set.- tokenizerId:+ 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: stringnullable: truedescription: >-- 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:+ The annotation queue referenced by the score. Indicates if score was+ initially created while processing annotation queue.+ environment: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.+ 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- - modelName- - matchPattern- - startDate- - inputPrice- - outputPrice- - totalPrice- - tokenizerId- - tokenizerConfig- - isLangfuseManaged+ - name+ - source+ - timestamp- createdAt- - prices- - pricingTiers- ModelPrice:- title: ModelPrice+ - updatedAt+ - authorUserId+ - comment+ - configId+ - queueId+ - environment+ NumericScore:+ title: NumericScoretype: objectproperties:- price:+ value:type: numberformat: double+ description: The numeric value of the scorerequired:- - 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+ - value+ allOf:+ - $ref: '#/components/schemas/BaseScore'+ BooleanScore:+ title: BooleanScoretype: object- description: Condition that sums usage details whose keys match a regex.properties:- usageDetailPattern:+ value:+ type: number+ format: double+ description: >-+ The numeric value of the score. Equals 1 for "True" and 0 for "False"+ stringValue:type: string- description: Regex pattern matched against usage detail keys.- operator:- $ref: '#/components/schemas/PricingTierOperator'+ 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: numberformat: 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: 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: Stringdescription: >-- Condition that matches any configured value for a top-level observation- attribute.+ 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: objectproperties:- source:- $ref: '#/components/schemas/PricingTierAttributeSource'- description: Observation attribute object evaluated by this condition.- key:+ id:type: string- description: Exact top-level attribute key.- operator:+ projectId:type: string- const: in- description: Membership operator.- values:- type: array- items:- type: string- description: Accepted string attribute values. At least one value is required.+ 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 authorrequired:- - 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+ - id+ - projectId+ - createdAt+ - updatedAt+ - objectType+ - objectId+ - content+ Dataset:+ title: Datasettype: object- description: Input condition that sums usage details whose keys match a regex.properties:- usageDetailPattern:+ id:+ type: string+ name:+ type: string+ description: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: booleannullable: true- description: Whether the usage-detail regex is case-sensitive. Defaults to false.+ 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-timerequired:- - usageDetailPattern- - operator- - value- PricingTier:- title: PricingTier+ - id+ - name+ - description+ - metadata+ - inputSchema+ - expectedOutputSchema+ - projectId+ - createdAt+ - updatedAt+ DatasetItem:+ title: DatasetItemtype: 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:+ 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- 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:+ nullable: true+ description: The trace ID that sourced this dataset item+ sourceObservationId:+ type: string+ nullable: true+ description: The observation ID that sourced this dataset item+ datasetId:+ type: string+ datasetName:+ type: string+ createdAt:+ type: string+ format: date-time+ updatedAt:+ type: string+ format: date-time+ version:+ type: string+ format: date-time+ nullable: true+ description: >-+ When this version of the dataset item became current. Listing+ dataset items with a `version` at or after this timestamp returns+ this item version, until the item is changed again. Self-hosted+ deployments that set+ `LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION=false`+ update items in place, so there it stays at the item's first write.+ mediaReferences:type: arrayitems:- $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+ $ref: '#/components/schemas/DatasetItemMediaReference'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.+ Resolved Langfuse media references found in input, expectedOutput,+ and metadata.required:- id- - name- - isDefault- - priority- - conditions- - prices- PricingTierInput:- title: PricingTierInput+ - status+ - input+ - expectedOutput+ - metadata+ - sourceTraceId+ - sourceObservationId+ - datasetId+ - datasetName+ - createdAt+ - updatedAt+ - mediaReferences+ DatasetItemMediaReference:+ title: DatasetItemMediaReference+ type: object+ properties:+ field:+ $ref: '#/components/schemas/DatasetItemMediaReferenceField'+ description: The dataset item field containing the reference+ referenceString:+ type: string+ description: >-+ The Langfuse media reference string, e.g.+ `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@`+ jsonPath:+ type: string+ description: >-+ JSONPath of the string holding the reference within the field, e.g.+ `$['image']`+ media:+ $ref: '#/components/schemas/DatasetItemMediaReferenceMedia'+ description: The resolved media record.+ required:+ - field+ - referenceString+ - jsonPath+ - media+ DatasetItemMediaReferenceField:+ title: DatasetItemMediaReferenceField+ type: string+ enum:+ - input+ - expectedOutput+ - metadata+ DatasetItemMediaReferenceMedia:+ title: DatasetItemMediaReferenceMedia+ type: object+ properties:+ mediaId:+ type: string+ description: The unique langfuse identifier of the media record+ contentType:+ type: string+ description: The MIME type of the media record+ contentLength:+ type: integer+ description: The size of the media record in bytes+ url:+ type: string+ description: The signed download URL of the media record+ urlExpiry:+ type: string+ description: The expiry date and time of the download URL+ required:+ - mediaId+ - contentType+ - contentLength+ - url+ - urlExpiry+ Model:+ title: Modeltype: objectdescription: >-- Input schema for creating a pricing tier. The tier ID will be- automatically generated server-side.+ Model definition used for transforming usage into USD cost and/or+ tokenization.- When creating a model with pricing tiers:+ Models can have either simple flat pricing or tiered pricing:- - Exactly one tier must have isDefault=true (the fallback tier)+ - Flat pricing: Single price per usage type (legacy, but still+ supported)- - The default tier must have priority=0 and conditions=[]+ - Tiered pricing: Multiple pricing tiers with conditional matching based+ on usage patterns or observation attributes- - All tier names and priorities must be unique within the model- - Each tier must define at least one price+ 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- See PricingTier for detailed information about how tiers work and why- they're useful.+ from the default tier for backward compatibility.properties:- name:+ id:+ type: string+ modelName:type: stringdescription: >-- 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+ Name of the model definition. If multiple with the same name exist,+ they are applied in the following order: (1) custom over built-in,+ (2) newest according to startTime where+ model.startTime<observation.startTime+ matchPattern:+ type: string+ description: >-+ Regex pattern which matches this model definition to+ generation.model. Useful in case of fine-tuned models. If you want+ to exact match, use `(?i)^modelname$`+ startDate:+ type: string+ format: date-time+ nullable: true+ description: Apply only to generations which are newer than this ISO date.+ unit:+ $ref: '#/components/schemas/ModelUsageUnit'+ nullable: true+ description: Unit used by this model.+ inputPrice:+ type: number+ format: double+ nullable: true+ description: Deprecated. See 'prices' instead. Price (USD) per input unit+ outputPrice:+ type: number+ format: double+ nullable: true+ description: Deprecated. See 'prices' instead. Price (USD) per output unit+ totalPrice:+ type: number+ format: doublenullable: truedescription: >-- 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+ Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot+ be set if input or output price is set.+ tokenizerId:+ type: string+ nullable: truedescription: >-- Priority for tier matching evaluation. Lower numbers = higher- priority (evaluated first).+ 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.- Must be unique within the model. The default tier must have- priority=0.+ This field shows prices by usage type from the default pricing tier.+ Maintained for backward compatibility.- Conditional tiers should use priority 1, 2, 3, etc. based on their- specificity.- conditions:+ If the model uses tiered pricing, this field will be populated from+ the default tier's prices.+ pricingTiers:type: arrayitems:- $ref: '#/components/schemas/PricingTierConditionInput'+ $ref: '#/components/schemas/PricingTier'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.+ Array of pricing tiers with conditional pricing based on usage+ thresholds or observation attributes.- 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.+ 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).- Common usage types: "input", "output", "total", "request", "image"- Prices are in USD per unit (e.g., per token).+ 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.- Example: {"input": 0.000003, "output": 0.000015} represents $3 per- million input tokens and $15 per million output tokens.+ If this array is empty, the model uses legacy flat pricing from the+ inputPrice/outputPrice/totalPrice fields.required:- - name- - priority- - conditions+ - id+ - modelName+ - matchPattern+ - startDate+ - inputPrice+ - outputPrice+ - totalPrice+ - tokenizerId+ - tokenizerConfig+ - isLangfuseManaged+ - createdAt- 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+ - pricingTiers+ ModelPrice:+ title: ModelPrice+ type: object+ properties:+ price:+ type: number+ format: double+ required:+ - price+ PricingTierCondition:+ title: PricingTierConditiononeOf:- - 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+ - $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: PricingTierUsageConditiontype: object+ description: Condition that sums usage details whose keys match a regex.properties:- message:+ usageDetailPattern:type: string- description: Success message after deletion+ 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:- - message- CreateDatasetItemRequest:- title: CreateDatasetItemRequest+ - usageDetailPattern+ - operator+ - value+ - caseSensitive+ PricingTierAttributeCondition:+ title: PricingTierAttributeConditiontype: object+ description: >-+ Condition that matches any configured value for a top-level observation+ attribute.properties:- datasetName:- type: string- input:- nullable: true- expectedOutput:- nullable: true- metadata:- nullable: true- sourceTraceId:- type: string- nullable: true- sourceObservationId:+ source:+ $ref: '#/components/schemas/PricingTierAttributeSource'+ description: Observation attribute object evaluated by this condition.+ key:type: string- nullable: true- id:+ description: Exact top-level attribute key.+ operator: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+ const: in+ description: Membership operator.+ values:+ type: array+ items:+ type: string+ description: Accepted string attribute values. At least one value is required.required:- - datasetName- PaginatedDatasetItems:- title: PaginatedDatasetItems+ - 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: PricingTierUsageConditionInputtype: object+ description: Input condition that sums usage details whose keys match a regex.properties:- data:- type: array- items:- $ref: '#/components/schemas/DatasetItem'- meta:- $ref: '#/components/schemas/utilsMetaResponse'+ 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:- - data- - meta- CreateDatasetRunItemRequest:- title: CreateDatasetRunItemRequest+ - usageDetailPattern+ - operator+ - value+ PricingTier:+ title: PricingTiertype: 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:- 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:+ id:type: string- nullable: true- traceId:+ description: Unique identifier for the pricing tier+ name:type: string- nullable: truedescription: >-- 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+ Name of the pricing tier for display and identification purposes.+++ Examples: "Standard", "High Volume Tier", "Large Context", "Extended+ Context Tier"+ isDefault:+ type: booleandescription: >-- ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g.,- "2026-01-21T14:35:42Z").+ Whether this is the default tier. Every model must have exactly one+ default tier with priority 0 and no conditions.- 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.+ The default tier serves as a fallback when no conditional tiers+ match, ensuring cost calculation always succeeds.- If not provided, uses the latest version of dataset items.- createdAt:- type: string- format: date-time- nullable: true+ It typically represents the base pricing for standard usage+ patterns.+ priority:+ type: integerdescription: >-- 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:+ 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: arrayitems:- $ref: '#/components/schemas/Dataset'- meta:- $ref: '#/components/schemas/utilsMetaResponse'- required:- - data- - meta- CreateDatasetRequest:- title: CreateDatasetRequest- type: object- properties:- name:- type: string- description:- type: string- nullable: true- metadata:- nullable: true- inputSchema:- nullable: true+ $ref: '#/components/schemas/PricingTierCondition'description: >-- JSON Schema for validating dataset item inputs. When set, all new- and existing dataset items will be validated against this schema.- expectedOutputSchema:- nullable: true+ 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: doubledescription: >-- JSON Schema for validating dataset item expected outputs. When set,- all new and existing dataset items will be validated against this- schema.+ 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- 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+ - isDefault+ - priority+ - conditions+ - prices+ PricingTierInput:+ title: PricingTierInputtype: 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_metadatadescription: >-- Source field used to populate a prompt variable.+ Input schema for creating a pricing tier. The tier ID will be+ automatically generated server-side.- Use these values when mapping evaluator prompt variables to live data.+ When creating a model with pricing tiers:+ - Exactly one tier must have isDefault=true (the fallback tier)- Source semantics:+ - The default tier must have priority=0 and conditions=[]- - `input`: the observation input payload+ - All tier names and priorities must be unique within the model- - `output`: the observation output payload+ - Each tier must define at least one price- - `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.+ 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.+- - `expected_output`: the experiment item's expected output when the- observation belongs to an experiment.+ Requirements for default tier:- - `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.+ - Must have isDefault=true+ - Must have priority=0- This controls the type of score value Langfuse stores for evaluation- results:+ - Must have empty conditions array (conditions=[])- - `NUMERIC`: a numeric score such as `0.82`- - `BOOLEAN`: a boolean score such as `true`+ 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).- - `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.+ Must be unique within the model. The default tier must have+ priority=0.- - `dataType` is required.+ 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).- - `scoreReasoningInstructions` and `scoreValueInstructions` are optional- instructions.- - `minValue` and `maxValue` apply only to `NUMERIC` outputs. If both are- set, `minValue` must not exceed `maxValue`.+ The default tier must have an empty array (conditions=[]).- - `categories` and `shouldAllowMultipleMatches` apply only to- `CATEGORICAL` outputs.+ Conditional tiers should define one or more conditions that specify+ when this tier's pricing applies.- - Do not send `version`; that is an internal storage detail.- EvaluatorOutputDefinitionBase:- title: EvaluatorOutputDefinitionBase- type: object- properties:- scoreReasoningInstructions:- type: string- nullable: true++ 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: doubledescription: >-- 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.+ Prices (USD) by usage type for this tier. At least one price must be+ defined.- This response always includes `dataType` and never includes an internal- output-definition `version`.+ Common usage types: "input", "output", "total", "request", "image"- Optional empty descriptions from legacy definitions are omitted.- EvaluationRuleStringFilterOperator:- title: EvaluationRuleStringFilterOperator+ 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: PricingTierOperatortype: stringenum:- - '='- - contains- - does not contain- - starts with- - ends with- EvaluationRuleStringObjectFilterOperator:- title: EvaluationRuleStringObjectFilterOperator+ - 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: ObservationLeveltype: stringenum:- - '='- - contains- - does not contain- - starts with- - ends with- - is set- - is not set- EvaluationRuleNumberFilterOperator:- title: EvaluationRuleNumberFilterOperator+ - 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: CommentObjectTypetype: stringenum:- - '='- - '>'- - <- - '>='- - <=- EvaluationRuleOptionsFilterOperator:- title: EvaluationRuleOptionsFilterOperator+ - TRACE+ - OBSERVATION+ - SESSION+ - PROMPT+ DatasetStatus:+ title: DatasetStatustype: stringenum:- - any of- - none of- EvaluationRuleArrayOptionsFilterOperator:- title: EvaluationRuleArrayOptionsFilterOperator+ - ACTIVE+ - ARCHIVED+ ScoreSource:+ title: ScoreSourcetype: stringenum:- - any of- - none of- - all of- EvaluationRuleBooleanFilterOperator:- title: EvaluationRuleBooleanFilterOperator+ - ANNOTATION+ - API+ - EVAL+ ScoreConfigDataType:+ title: ScoreConfigDataTypetype: stringenum:- - '='- - <>- EvaluationRuleNullFilterOperator:- title: EvaluationRuleNullFilterOperator+ - NUMERIC+ - BOOLEAN+ - CATEGORICAL+ - TEXT+ ScoreDataType:+ title: ScoreDataTypetype: stringenum:- - 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+ - NUMERIC+ - BOOLEAN+ - CATEGORICAL+ - CORRECTION+ - TEXT+ OpenAIUsage:+ title: OpenAIUsagetype: object+ description: Usage interface of OpenAI for improved compatibility.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+ promptTokens:+ type: integer+ nullable: true+ completionTokens:+ type: integer+ nullable: true+ totalTokens:+ type: integer+ nullable: true+ DeleteDatasetItemResponse:+ title: DeleteDatasetItemResponsetype: objectproperties:- column:+ message: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.+ description: Success message after deletionrequired:- - column- - operator- - value- ArrayOptionsEvaluationRuleFilter:- title: ArrayOptionsEvaluationRuleFilter+ - message+ CreateDatasetItemRequest:+ title: CreateDatasetItemRequesttype: objectproperties:- column:+ datasetName: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:+ input:+ nullable: true+ expectedOutput:+ nullable: true+ metadata:+ nullable: true+ sourceTraceId:type: string- description: >-- Object-valued column to filter on. Currently only `metadata` is- supported.- key:+ nullable: true+ sourceObservationId:type: string- description: Top-level key inside the object-valued column to filter on.- operator:- $ref: '#/components/schemas/EvaluationRuleStringObjectFilterOperator'- description: Use `is set` / `is not set` to filter on key presence.- value:+ nullable: true+ id:type: string+ nullable: truedescription: >-- Value to compare against. Ignored for `is set` / `is not set`; send- `""`.- required:- - column- - key- - operator- - value- NumberObjectEvaluationRuleFilter:- title: NumberObjectEvaluationRuleFilter- type: object- properties:- column:- type: string- description: Object-valued column to filter on.- key:- type: string- description: Key inside the object-valued column to filter on.- operator:- $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'- value:- type: number- format: double+ 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 itemsrequired:- - 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:+ - datasetName+ PaginatedDatasetItems:+ title: PaginatedDatasetItems+ type: object+ properties:+ data:type: arrayitems:- type: string+ $ref: '#/components/schemas/DatasetItem'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'required:- - column- - key- - operator- - value- BooleanEvaluationRuleFilter:- title: BooleanEvaluationRuleFilter+ - data+ - meta+ PaginatedDatasets:+ title: PaginatedDatasetstype: objectproperties:- column:- type: string- description: Column to filter on.- operator:- $ref: '#/components/schemas/EvaluationRuleBooleanFilterOperator'- value:- type: boolean+ data:+ type: array+ items:+ $ref: '#/components/schemas/Dataset'+ meta:+ $ref: '#/components/schemas/utilsMetaResponse'required:- - column- - operator- - value- NullEvaluationRuleFilter:- title: NullEvaluationRuleFilter+ - data+ - meta+ CreateDatasetRequest:+ title: CreateDatasetRequesttype: objectproperties:- column:+ name:type: string- description: Column to filter on, for example `parentObservationId`.- operator:- $ref: '#/components/schemas/EvaluationRuleNullFilterOperator'- value:+ description:type: string- const: ''+ nullable: true+ metadata:+ nullable: true+ inputSchema:+ nullable: truedescription: >-- 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+ JSON Schema for validating dataset item inputs. When set, all new+ and existing dataset items will be validated against this schema.+ expectedOutputSchema:+ nullable: truedescription: >-- Prompt variable name without braces.-+ JSON Schema for validating dataset item expected outputs. When set,+ all new and existing dataset items will be validated against this+ schema.+ required:+ - name+ EvaluatorType:+ title: EvaluatorType+ type: string+ enum:+ - llm_as_judge+ - code+ description: |-+ The evaluator type.- 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.+ 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.- 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.+ Use these values when mapping evaluator prompt variables to live data.- Requirements:+ Source semantics:- - Must start with `$`+ - `input`: the observation input payload- - Must be a syntactically valid JSONPath expression+ - `output`: the observation output payload- - Most useful with `source=metadata`- required:- - variable- - source- PromptVariableMappingRead:- title: PromptVariableMappingRead- type: object- description: |-- Connects one prompt variable to source data.+ - `metadata`: the observation metadata object. Combine with `jsonPath`+ when you need one nested field instead of the whole object.- `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.+ - `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.- `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+ - `experiment_item_metadata`: the experiment item's metadata when the+ observation belongs to an experiment.+ EvaluatorOutputScoreType:+ title: EvaluatorOutputScoreTypetype: stringenum:- - trace- - span- - generation- - event- - agent- - tool- - chain- - retriever- - evaluator- - embedding- - guardrail- - dataset_item+ - NUMERIC+ - BOOLEAN+ - CATEGORICALdescription: >-- **Deprecated:** Legacy Langfuse object kind used by trace and dataset- evaluation rules.- EvaluationRuleFilter:- title: EvaluationRuleFilter+ 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: EvaluatorOutputDefinitiononeOf:- type: objectallOf:- type: objectproperties:- 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:+ dataType:type: stringenum:- - numberObject- - $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'+ - NUMERIC+ - $ref: '#/components/schemas/PublicEvaluatorNumericScore'required:- - type- title: NumberObjectEvaluationRuleFilter+ - dataType+ title: PublicEvaluatorNumericScore- type: objectallOf:- type: objectproperties:- type:+ dataType:type: stringenum:- - boolean- - $ref: '#/components/schemas/BooleanEvaluationRuleFilter'+ - BOOLEAN+ - $ref: '#/components/schemas/PublicEvaluatorBooleanScore'required:- - type- title: BooleanEvaluationRuleFilter+ - dataType+ title: PublicEvaluatorBooleanScore- type: objectallOf:- type: objectproperties:- type:+ dataType:type: stringenum:- - 'null'- - $ref: '#/components/schemas/NullEvaluationRuleFilter'+ - CATEGORICAL+ - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'required:- - type- title: NullEvaluationRuleFilter+ - dataType+ title: PublicEvaluatorCategoricalScoredescription: >-- 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+ Flat structured output definition used when creating or updating an+ evaluator.- - `parentObservationId`: `null`- - `experimentId`: `stringOptions`+ - `dataType` is required.- - `isExperimentItemRootSpan`: `boolean`+ - `scoreReasoningInstructions` and `scoreValueInstructions` are optional+ instructions.- - `calledToolNames`: `arrayOptions`+ - `minValue` and `maxValue` apply only to `NUMERIC` outputs. If both are+ set, `minValue` must not exceed `maxValue`.- - `toolCalls`: `number`, the number of tool calls on the observation+ - `categories` and `shouldAllowMultipleMatches` apply only to+ `CATEGORICAL` outputs.- - `datasetId`: `stringOptions`. Use dataset `id` values from `GET- /api/public/v2/datasets`, not dataset names.- EvaluationRuleReadFilterBase:- title: EvaluationRuleReadFilterBase+ - Do not send `version`; that is an internal storage detail.+ EvaluatorOutputDefinitionBase:+ title: EvaluatorOutputDefinitionBasetype: object- description: Stored filter returned verbatim by evaluation-rule read endpoints.properties:- type:+ scoreReasoningInstructions:type: string+ nullable: truedescription: >-- Stored filter type. This is not broken down into separate public- response types.- column:+ Optional instructions for deriving the reasoning returned with the+ score.+ scoreValueInstructions:type: string- operator:+ 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- value:- nullable: true- description: Stored filter value. Its shape depends on the filter type.+ const: BOOLEAN+ description: Boolean score output.required:- - type- - column- - operator- EvaluationRuleReadFilterWithKey:- title: EvaluationRuleReadFilterWithKey+ - dataType+ allOf:+ - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'+ PublicEvaluatorCategoricalScore:+ title: PublicEvaluatorCategoricalScoretype: objectproperties:- key:+ dataType:type: string- description: Stored object or legacy filter key.+ 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:- - key+ - dataType+ - categories+ - shouldAllowMultipleMatchesallOf:- - $ref: '#/components/schemas/EvaluationRuleReadFilterBase'- EvaluationRuleReadFilter:- title: EvaluationRuleReadFilter+ - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'+ PublicEvaluatorOutputDefinition:+ title: PublicEvaluatorOutputDefinitiononeOf:- - $ref: '#/components/schemas/EvaluationRuleReadFilterWithKey'- - $ref: '#/components/schemas/EvaluationRuleReadFilterBase'+ - 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: PublicEvaluatorCategoricalScoredescription: >-- Filter returned verbatim by evaluation-rule read endpoints.+ Flat evaluator output definition returned by the public API.- 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+ This response always includes `dataType` and never includes an internal+ output-definition `version`.++ Optional empty descriptions from legacy definitions are omitted.+ EvaluationRuleStringFilterOperator:+ title: EvaluationRuleStringFilterOperatortype: stringenum:- - 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+ - '='+ - contains+ - does not contain+ - starts with+ - ends with+ EvaluationRuleStringObjectFilterOperator:+ title: EvaluationRuleStringObjectFilterOperator+ type: string+ enum:+ - '='+ - contains+ - does not contain+ - starts with+ - ends with+ - is set+ - is not set+ EvaluationRuleNumberFilterOperator:+ title: EvaluationRuleNumberFilterOperator+ type: string+ enum:+ - '='+ - '>'+ - <+ - '>='+ - <=+ EvaluationRuleOptionsFilterOperator:+ title: EvaluationRuleOptionsFilterOperator+ type: string+ enum:+ - any of+ - none of+ EvaluationRuleArrayOptionsFilterOperator:+ title: EvaluationRuleArrayOptionsFilterOperator+ type: string+ enum:+ - any of+ - none of+ - all of+ EvaluationRuleBooleanFilterOperator:+ title: EvaluationRuleBooleanFilterOperator+ type: string+ enum:+ - '='+ - <>+ EvaluationRuleNullFilterOperator:+ title: EvaluationRuleNullFilterOperator+ type: string+ enum:+ - is null+ - is not null+ DateTimeEvaluationRuleFilter:+ title: DateTimeEvaluationRuleFiltertype: object- description: One request validation issue.properties:- code:+ column:type: string- description: Validator issue code.- message:+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'+ description: Comparison operator for datetime values.+ value:type: string- description: Human-readable explanation.- path:- type: array- items: {}- description: Path to the invalid request field.+ format: date-time+ description: Datetime value to compare against.required:- - code- - message- - path- PublicApiErrorDetails:- title: PublicApiErrorDetails+ - column+ - operator+ - value+ StringEvaluationRuleFilter:+ title: StringEvaluationRuleFiltertype: 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:+ column:type: string- format: date-time- nullable: true- description: Time when the current rate-limit window resets.- PublicApiError:- title: PublicApiError+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleStringFilterOperator'+ value:+ type: string+ required:+ - column+ - operator+ - value+ NumberEvaluationRuleFilter:+ title: NumberEvaluationRuleFiltertype: 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:+ column: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.+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'+ value:+ type: number+ format: doublerequired:- - message- - code- EvaluationRuleEvaluatorAssignmentInput:- title: EvaluationRuleEvaluatorAssignmentInput+ - column+ - operator+ - value+ StringOptionsEvaluationRuleFilter:+ title: StringOptionsEvaluationRuleFiltertype: objectproperties:- evaluatorId:+ column:type: string- description: >-- Stable evaluator identifier. The rule automatically uses that- evaluator's latest version.- variableMapping:+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleOptionsFilterOperator'+ value:type: arrayitems:- $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`.+ type: string+ description: One or more allowed string values.required:- - evaluatorId- EvaluatorAssignment:- title: EvaluatorAssignment+ - column+ - operator+ - value+ ArrayOptionsEvaluationRuleFilter:+ title: ArrayOptionsEvaluationRuleFiltertype: objectproperties:- evaluatorId:+ column:type: string- description: Stable identifier of the evaluator associated with this rule.- variableMapping:+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleArrayOptionsFilterOperator'+ value:type: arrayitems:- $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.+ type: string+ description: One or more array elements to match.required:- - evaluatorId- - variableMapping- EvaluationRule:- title: EvaluationRule+ - column+ - operator+ - value+ StringObjectEvaluationRuleFilter:+ title: StringObjectEvaluationRuleFiltertype: 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:+ column:type: stringdescription: >-- 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:+ Object-valued column to filter on. Currently only `metadata` is+ supported.+ key:type: string- format: date-time- description: Timestamp when the evaluation rule was created.- updatedAt:+ description: Top-level key inside the object-valued column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleStringObjectFilterOperator'+ description: Use `is set` / `is not set` to filter on key presence.+ value:type: string- format: date-time- description: Timestamp when the evaluation rule was last updated.+ description: >-+ Value to compare against. Ignored for `is set` / `is not set`; send+ `""`.required:- - id- - name- - createdBy- - enabled- - sampling- - filter- - evaluatorAssignments- - createdAt- - updatedAt- CreateEvaluationRuleRequest:- title: CreateEvaluationRuleRequest+ - column+ - key+ - operator+ - value+ NumberObjectEvaluationRuleFilter:+ title: NumberObjectEvaluationRuleFiltertype: objectproperties:- name:+ column: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:+ 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: numberformat: 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+ - column+ - key+ - operator+ - value+ CategoryOptionsEvaluationRuleFilter:+ title: CategoryOptionsEvaluationRuleFiltertype: object- description: At least one field must be provided.properties:- name:+ column: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:+ 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: arrayitems:- $ref: '#/components/schemas/EvaluationRule'- description: Evaluation rules for this page.- meta:- $ref: '#/components/schemas/CursorMeta'- description: Cursor pagination metadata.+ type: stringrequired:- - data- - meta- DeletedEvaluationRule:- title: DeletedEvaluationRule+ - column+ - key+ - operator+ - value+ BooleanEvaluationRuleFilter:+ title: BooleanEvaluationRuleFiltertype: object- description: Confirmation returned after successful evaluation-rule deletion.properties:- id:+ column:type: string- description: Identifier of the deleted evaluation rule.+ description: Column to filter on.+ operator:+ $ref: '#/components/schemas/EvaluationRuleBooleanFilterOperator'+ value:+ type: booleanrequired:- - id- Creator:- title: Creator+ - column+ - operator+ - value+ NullEvaluationRuleFilter:+ title: NullEvaluationRuleFiltertype: object- description: User who created the resource, or `null` when no user can be resolved.properties:- id:+ column:type: string- description: User identifier.- name:+ description: Column to filter on, for example `parentObservationId`.+ operator:+ $ref: '#/components/schemas/EvaluationRuleNullFilterOperator'+ value:type: string- nullable: true- description: User name, or `null` when unavailable.+ const: ''+ description: >-+ Required empty-string placeholder used by the runtime filter+ contract.required:- - id- - name- EvaluatorModelConfig:- title: EvaluatorModelConfig+ - column+ - operator+ - value+ PromptVariableMappingInput:+ title: PromptVariableMappingInputtype: objectdescription: >-- Explicit model configuration for an evaluator.+ Connects one prompt variable to data from an observation or experiment.- If the complete `modelConfig` is `null`, Langfuse uses the project's- default evaluation model.+ Manual mappings are used for `llm_as_judge` evaluators. `code`+ evaluators use a fixed runtime mapping managed by Langfuse.- If provided, the model must be available to the project when the- evaluator or evaluation rule is enabled.++ 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:- provider:+ variable:type: stringdescription: >-- Provider identifier, for example `openai` or `anthropic`.+ Prompt variable name without braces.- 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+ Example: for the prompt `Judge {{input}} against {{output}}`, use+ `input` and `output`.+ source:+ $ref: '#/components/schemas/PromptVariableMappingSource'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:+ 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- format: date-time- description: Timestamp when this evaluator version was created.- createdBy:- $ref: '#/components/schemas/Creator'nullable: truedescription: >-- User who created this version, or `null` when no user can be- resolved.+ 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:- - id- - version- - createdAt- - createdBy- LlmAsJudgeEvaluatorVersion:- title: LlmAsJudgeEvaluatorVersion+ - variable+ - source+ PromptVariableMappingRead:+ title: PromptVariableMappingReadtype: object+ description: |-+ Connects one prompt variable to source data.++ `source` is `null` when the mapping is incomplete.properties:- type:+ variable:+ type: string+ description: Prompt variable name without braces.+ source: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: truedescription: >-- Default variable mapping for this evaluator version, or `null` when- no default is configured.- modelConfig:- $ref: '#/components/schemas/EvaluatorModelConfig'+ Stored source field populating the variable, or `null` when the+ mapping is incomplete.+ jsonPath:+ type: stringnullable: 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.+ description: Optional JSONPath selector applied to the selected source.required:- - type- - prompt- - variables- - variableMapping- - modelConfig- - outputDefinition- allOf:- - $ref: '#/components/schemas/EvaluatorVersionBase'- CodeEvaluatorVersion:- title: CodeEvaluatorVersion+ - variable+ - source+ PromptVariableMapping:+ title: PromptVariableMapping+ oneOf:+ - $ref: '#/components/schemas/PromptVariableMappingRead'+ - $ref: '#/components/schemas/LegacyPromptVariableMapping'+ description: Connects one prompt variable to source data.+ LegacyPromptVariableMapping:+ title: LegacyPromptVariableMappingtype: 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:- type:+ mappingType:type: string- const: code- description: Evaluator type.- sourceCode:+ const: legacy+ description: Explicitly marks this as a legacy mapping.+ variable:type: string- description: Source code executed for each matched observation.- sourceCodeLanguage:- $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'- description: Runtime language used to execute the source code.+ 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:- - type- - sourceCode- - sourceCodeLanguage- allOf:- - $ref: '#/components/schemas/EvaluatorVersionBase'- EvaluatorVersion:- title: EvaluatorVersion+ - 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: EvaluationRuleFilteroneOf:- type: objectallOf:@@ -13351,11 +10104,11 @@ components:type:type: stringenum:- - llm_as_judge- - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'+ - datetime+ - $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'required:- type- title: LlmAsJudgeEvaluatorVersion+ title: DateTimeEvaluationRuleFilter- type: objectallOf:- type: object@@ -13363,185 +10116,47 @@ components:type:type: stringenum:- - code- - $ref: '#/components/schemas/CodeEvaluatorVersion'+ - string+ - $ref: '#/components/schemas/StringEvaluationRuleFilter'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:+ 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: objectallOf:- type: object@@ -13549,11 +10164,11 @@ components:type:type: stringenum:- - llm_as_judge- - $ref: '#/components/schemas/LlmAsJudgeEvaluator'+ - arrayOptions+ - $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'required:- type- title: LlmAsJudgeEvaluator+ title: ArrayOptionsEvaluationRuleFilter- type: objectallOf:- type: object@@ -13561,507 +10176,654 @@ components:type:type: stringenum:- - code- - $ref: '#/components/schemas/CodeEvaluator'+ - stringObject+ - $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'required:- type- title: CodeEvaluator+ 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: NullEvaluationRuleFilterdescription: >-- One evaluator that can be used for scoring.+ One filter condition used to decide whether a live-ingested observation+ should be evaluated.- 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.+ 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.- - `active`: the evaluator can run.+ - `datasetId` limits execution to experiments for the selected datasets.+ Use dataset IDs from `GET /api/public/v2/datasets`.- - `paused`: Langfuse paused execution until the underlying issue is- resolved.- CreateLlmAsJudgeEvaluatorRequest:- title: CreateLlmAsJudgeEvaluatorRequest++ 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: PublicApiErrortype: 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:- name:- type: string- description: >-- Human-readable evaluator name. Names are not identifiers and do not- need to be unique.- description:+ 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 human-readable evaluator description.- type:+ description: Optional structured validation or rate-limit context.+ required:+ - message+ - code+ EvaluationRuleEvaluatorAssignmentInput:+ title: EvaluationRuleEvaluatorAssignmentInput+ type: object+ properties:+ evaluatorId: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: truedescription: >-- Explicit model configuration. Set to `null` or omit to use the- project's default evaluation model.+ Stable evaluator identifier. The rule automatically uses that+ evaluator's latest version.variableMapping:type: arrayitems:$ref: '#/components/schemas/PromptVariableMappingInput'nullable: truedescription: >-- 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.+ 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:- - name- - type- - prompt- - outputDefinition- CreateCodeEvaluatorRequest:- title: CreateCodeEvaluatorRequest+ - evaluatorId+ EvaluatorAssignment:+ title: EvaluatorAssignmenttype: objectproperties:- name:- type: string- description: >-- Human-readable evaluator name. Names are not identifiers and do not- need to be unique.- description:+ evaluatorId:type: string+ description: Stable identifier of the evaluator associated with this rule.+ variableMapping:+ type: array+ items:+ $ref: '#/components/schemas/PromptVariableMapping'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.+ 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:- - 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+ - evaluatorId+ - variableMapping+ EvaluationRule:+ title: EvaluationRuletype: object- description: Metadata-only update. At least one field must be provided.+ 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: New human-readable evaluator name.- description:+ 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- nullable: true- description: New description. Set to `null` to clear it.- UpdateLlmAsJudgeEvaluatorRequest:- title: UpdateLlmAsJudgeEvaluatorRequest+ 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: CreateEvaluationRuleRequesttype: objectproperties: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'+ 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: doublenullable: truedescription: >-- Explicit model configuration. Set to `null` or omit to use the- project's default evaluation model.- variableMapping:+ 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: arrayitems:- $ref: '#/components/schemas/PromptVariableMappingInput'+ $ref: '#/components/schemas/EvaluationRuleFilter'nullable: truedescription: >-- Complete replacement default variable mapping, or `null` when no- default is configured.- outputDefinition:- $ref: '#/components/schemas/EvaluatorOutputDefinition'+ Conditions used to select observations. Defaults to an empty list,+ which matches every incoming observation.+ evaluatorAssignments:+ type: array+ items:+ $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'description: >-- Complete replacement output schema. Do not include an internal- persistence version.+ Evaluators to attach to this rule. Disabled rules may use an empty+ list as a draft.required:- - type- - prompt- - outputDefinition- UpdateCodeEvaluatorRequest:- title: UpdateCodeEvaluatorRequest+ - name+ - enabled+ - evaluatorAssignments+ UpdateEvaluationRuleRequest:+ title: UpdateEvaluationRuleRequesttype: object+ description: At least one field must be provided.properties:name:type: stringnullable: true- description: New human-readable evaluator name.- description:- type: string+ description: New human-readable rule name.+ enabled:+ type: booleannullable: 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:+ 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: arrayitems:- $ref: '#/components/schemas/Evaluator'- description: Evaluators for this page.- meta:- $ref: '#/components/schemas/CursorMeta'- description: Cursor pagination metadata.- required:- - data- - meta- EvaluatorVersionsPage:- title: EvaluatorVersionsPage+ $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: EvaluationRulesPagetype: objectproperties:data:type: arrayitems:- $ref: '#/components/schemas/EvaluatorVersion'- description: Evaluator versions for this page in newest-first order.+ $ref: '#/components/schemas/EvaluationRule'+ description: Evaluation rules for this page.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+ DeletedEvaluationRule:+ title: DeletedEvaluationRuletype: object- description: Confirmation returned after successful evaluator deletion.+ description: Confirmation returned after successful evaluation-rule deletion.properties:id:type: string- description: Identifier of the deleted evaluator.+ description: Identifier of the deleted evaluation rule.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+ Creator:+ title: Creatortype: 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- 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: truenullable: 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.+ description: User name, or `null` when unavailable.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+ EvaluatorModelConfig:+ title: EvaluatorModelConfigtype: 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:- 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:+ 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- nullable: true- description: Included when `fields=experimentMetadata` is requested.- scores:- type: array- items:- $ref: '#/components/schemas/ScoreV3'- nullable: truedescription: >-- Included only when `fields=scores` is requested. Contains item and- trace scores only; experiment-level scores are returned by the- experiments endpoint.+ Model identifier exposed by the provider, for example `gpt-4.1-mini`.required:- - id- - traceId- - startTime- - endTime- - level- - environment- - experimentId- - experimentName- - experimentItemId- FeedbackTargetType:- title: FeedbackTargetType+ - provider+ - model+ EvaluatorChatMessageRole:+ title: EvaluatorChatMessageRoletype: stringenum:- - skill- - mcp-tool- - cli- - docs- - public-api- - other- SubmitFeedbackRequest:- title: SubmitFeedbackRequest+ - system+ - user+ - assistant+ description: Role of an evaluator prompt message.+ EvaluatorChatMessage:+ title: EvaluatorChatMessagetype: object+ description: One chat message in an evaluator prompt.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:+ role:+ $ref: '#/components/schemas/EvaluatorChatMessageRole'+ content:type: string- description: >-- Concise feedback text approved by the user. Must be between 1 and- 3000 characters.- goal:+ 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- 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:+ 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: truedescription: >-- Optional HTTP(S) reference URL. Langfuse stores it as text for- triage and does not fetch it.+ User who created this version, or `null` when no user can be+ resolved.required:- - targetType- - target- - feedback- SubmitFeedbackResponse:- title: SubmitFeedbackResponse+ - id+ - version+ - createdAt+ - createdBy+ LlmAsJudgeEvaluatorVersion:+ title: LlmAsJudgeEvaluatorVersiontype: objectproperties:- id:+ type:type: string- description: Correlation ID for the submitted feedback.+ 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:- - id- HealthResponse:- title: HealthResponse+ - type+ - prompt+ - variables+ - variableMapping+ - modelConfig+ - outputDefinition+ allOf:+ - $ref: '#/components/schemas/EvaluatorVersionBase'+ CodeEvaluatorVersion:+ title: CodeEvaluatorVersiontype: objectproperties:- version:+ type:type: string- description: Langfuse server version- status:+ 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:- - version- - status- IngestionEvent:- title: IngestionEvent+ - type+ - sourceCode+ - sourceCodeLanguage+ allOf:+ - $ref: '#/components/schemas/EvaluatorVersionBase'+ EvaluatorVersion:+ title: EvaluatorVersiononeOf:- type: objectallOf:@@ -14070,95 +10832,11 @@ components:type:type: stringenum:- - 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'+ - llm_as_judge+ - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'required:- type- title: CreateObservationEvent+ title: LlmAsJudgeEvaluatorVersion- type: objectallOf:- type: object@@ -14166,778 +10844,703 @@ components:type:type: stringenum:- - 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+ - code+ - $ref: '#/components/schemas/CodeEvaluatorVersion'+ required:+ - type+ title: CodeEvaluatorVersion+ EvaluationRuleAssignment:+ title: EvaluationRuleAssignmenttype: object- description: Usage interface of OpenAI for improved compatibility.+ description: Evaluation-rule assignment associated with this evaluator.properties:- promptTokens:- type: integer- nullable: true- completionTokens:- type: integer- nullable: true- totalTokens:- type: integer+ evaluationRuleId:+ type: string+ description: Stable identifier of the assigned evaluation rule.+ variableMappingOverride:+ type: array+ items:+ $ref: '#/components/schemas/PromptVariableMapping'nullable: true- OptionalObservationBody:- title: OptionalObservationBody+ 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: EvaluatorBasetype: objectproperties:- traceId:+ id:type: string- nullable: true+ description: Stable identifier of this evaluator across all versions.name:type: string- nullable: true- startTime:+ description: >-+ Human-readable evaluator name. Names are not identifiers and do not+ need to be unique.+ description:type: string- format: date-time- nullable: true- metadata:- nullable: true- input:- nullable: true- output:nullable: true- level:- $ref: '#/components/schemas/ObservationLevel'+ description: Optional human-readable evaluator description.+ createdBy:+ $ref: '#/components/schemas/Creator'nullable: true- statusMessage:+ 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-timenullable: true- parentObservationId:+ description: Timestamp when the evaluator was paused, otherwise `null`.+ pausedReason:type: stringnullable: true- version:+ description: Machine-readable reason when `status=paused`, otherwise `null`.+ pausedMessage:type: stringnullable: true- environment:+ 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- nullable: true- CreateEventBody:- title: CreateEventBody- type: object- properties:- id:+ format: date-time+ description: Timestamp when the evaluator was created.+ updatedAt:type: string- nullable: true- allOf:- - $ref: '#/components/schemas/OptionalObservationBody'- UpdateEventBody:- title: UpdateEventBody- type: object- properties:- id:+ format: date-time+ description: Timestamp when the evaluator was last updated.+ versionId:type: string- required:- - id- allOf:- - $ref: '#/components/schemas/OptionalObservationBody'- CreateSpanBody:- title: CreateSpanBody- type: object- properties:- endTime:+ description: Stable identifier of the latest evaluator version.+ version:+ type: integer+ description: Monotonically increasing latest evaluator version number.+ versionCreatedAt:type: stringformat: date-time+ description: Timestamp when the latest evaluator version was created.+ versionCreatedBy:+ $ref: '#/components/schemas/Creator'nullable: true- allOf:- - $ref: '#/components/schemas/CreateEventBody'- UpdateSpanBody:- title: UpdateSpanBody+ 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: LlmAsJudgeEvaluatortype: objectproperties:- endTime:+ type:type: string- format: date-time+ 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+ - outputDefinitionallOf:- - $ref: '#/components/schemas/UpdateEventBody'- CreateGenerationBody:- title: CreateGenerationBody+ - $ref: '#/components/schemas/EvaluatorBase'+ CodeEvaluator:+ title: CodeEvaluatortype: objectproperties:- completionStartTime:- type: string- format: date-time- nullable: true- model:+ type: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:+ const: code+ description: Evaluator type.+ sourceCode:type: string- nullable: true- promptVersion:- type: integer- nullable: true+ 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+ - sourceCodeLanguageallOf:- - $ref: '#/components/schemas/CreateSpanBody'- UpdateGenerationBody:- title: UpdateGenerationBody+ - $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: CreateLlmAsJudgeEvaluatorRequesttype: objectproperties:- completionStartTime:+ name:type: string- format: date-time- nullable: true- model:+ description: >-+ Human-readable evaluator name. Names are not identifiers and do not+ need to be unique.+ description:type: stringnullable: true- modelParameters:- type: object- additionalProperties:- $ref: '#/components/schemas/MapValue'- nullable: true- usage:- $ref: '#/components/schemas/IngestionUsage'- nullable: true- promptName:+ 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- usageDetails:- $ref: '#/components/schemas/UsageDetails'- nullable: true- costDetails:- type: object- additionalProperties:- type: number- format: double- nullable: true- promptVersion:- type: integer+ 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- allOf:- - $ref: '#/components/schemas/UpdateSpanBody'- ObservationBody:- title: ObservationBody+ 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: CreateCodeEvaluatorRequesttype: objectproperties:- 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:+ description: >-+ Human-readable evaluator name. Names are not identifiers and do not+ need to be unique.+ description:type: stringnullable: true- parentObservationId:+ description: Optional human-readable evaluator description.+ type:type: string- nullable: true- environment:+ const: code+ description: Evaluator type.+ sourceCode:type: string- nullable: true+ 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- TraceBody:- title: TraceBody+ - 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: UpdateEvaluatorMetadataRequesttype: object+ description: Metadata-only update. At least one field must be provided.properties:- id:- type: string- nullable: true- timestamp:- type: string- format: date-time- nullable: truename:type: stringnullable: 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:+ description: New human-readable evaluator name.+ description:type: stringnullable: true- public:- type: boolean- nullable: true- description: Make trace publicly accessible via url- ScoreBody:- title: ScoreBody+ description: New description. Set to `null` to clear it.+ UpdateLlmAsJudgeEvaluatorRequest:+ title: UpdateLlmAsJudgeEvaluatorRequesttype: objectproperties:- id:- type: string- nullable: true- traceId:- type: string- nullable: true- sessionId:- type: string- nullable: true- observationId:+ name:type: stringnullable: true- datasetRunId:+ description: New human-readable evaluator name.+ description:type: stringnullable: true- name:+ 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: >-- The name of the score. Always overrides "output" for correction- scores.- environment:- type: string- nullable: true- queueId:- type: string+ Complete replacement user prompt string or an ordered list of chat+ messages.+ modelConfig:+ $ref: '#/components/schemas/EvaluatorModelConfig'nullable: truedescription: >-- 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'+ 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: truedescription: >-- 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+ Complete replacement default variable mapping, or `null` when no+ default is configured.+ outputDefinition:+ $ref: '#/components/schemas/EvaluatorOutputDefinition'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+ Complete replacement output schema. Do not include an internal+ persistence version.required:- - name- - value- BaseEvent:- title: BaseEvent+ - type+ - prompt+ - outputDefinition+ UpdateCodeEvaluatorRequest:+ title: UpdateCodeEvaluatorRequesttype: objectproperties:- id:+ name:type: string- description: UUID v4 that identifies the event- timestamp:+ nullable: true+ description: New human-readable evaluator name.+ description: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'+ 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:- - body- allOf:- - $ref: '#/components/schemas/BaseEvent'- UpdateObservationEvent:- title: UpdateObservationEvent- type: object+ - type+ - sourceCode+ - sourceCodeLanguage+ UpdateEvaluatorRequest:+ title: UpdateEvaluatorRequest+ oneOf:+ - $ref: '#/components/schemas/UpdateEvaluatorMetadataRequest'+ - $ref: '#/components/schemas/UpdateLlmAsJudgeEvaluatorRequest'+ - $ref: '#/components/schemas/UpdateCodeEvaluatorRequest'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+ Metadata-only update or complete flattened definition replacement. At+ least one field must be provided.+ EvaluatorsPage:+ title: EvaluatorsPagetype: objectproperties:- body:- $ref: '#/components/schemas/ScoreBody'+ data:+ type: array+ items:+ $ref: '#/components/schemas/Evaluator'+ description: Evaluators for this page.+ meta:+ $ref: '#/components/schemas/CursorMeta'+ description: Cursor pagination metadata.required:- - body- allOf:- - $ref: '#/components/schemas/BaseEvent'- CreateGenerationEvent:- title: CreateGenerationEvent+ - data+ - meta+ EvaluatorVersionsPage:+ title: EvaluatorVersionsPagetype: 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'+ 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:- - body- allOf:- - $ref: '#/components/schemas/BaseEvent'- UpdateGenerationEvent:- title: UpdateGenerationEvent+ - data+ - meta+ CursorMeta:+ title: CursorMetatype: 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+ description: Cursor pagination metadata.+ properties: {}allOf:- - $ref: '#/components/schemas/BaseEvent'- CreateSpanEvent:- title: CreateSpanEvent+ - $ref: '#/components/schemas/utilsCursorMetaResponse'+ DeletedEvaluator:+ title: DeletedEvaluatortype: 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.+ description: Confirmation returned after successful evaluator deletion.properties:- body:- $ref: '#/components/schemas/CreateSpanBody'+ id:+ type: string+ description: Identifier of the deleted evaluator.required:- - body- allOf:- - $ref: '#/components/schemas/BaseEvent'- UpdateSpanEvent:- title: UpdateSpanEvent+ - id+ ExperimentsResponse:+ title: ExperimentsResponsetype: 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'+ data:+ type: array+ items:+ $ref: '#/components/schemas/Experiment'+ meta:+ $ref: '#/components/schemas/ExperimentsResponseMeta'required:- - body- allOf:- - $ref: '#/components/schemas/BaseEvent'- CreateEventEvent:- title: CreateEventEvent+ - data+ - meta+ ExperimentsResponseMeta:+ title: ExperimentsResponseMetatype: 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+ description: Metadata for cursor-based pagination.+ properties: {}allOf:- - $ref: '#/components/schemas/BaseEvent'- IngestionSuccess:- title: IngestionSuccess+ - $ref: '#/components/schemas/utilsCursorMetaResponse'+ Experiment:+ title: Experimenttype: objectproperties:id:type: string- status:- type: integer- required:- - id- - status- IngestionError:- title: IngestionError- type: object- properties:- id:+ name:type: string- status:+ 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- message:+ description: Number of experiment items within the requested time range.+ datasetId:type: stringnullable: true- error:+ 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- - status- IngestionResponse:- title: IngestionResponse+ - name+ - description+ - startTime+ - endTime+ - itemCount+ - datasetId+ ExperimentItemsResponse:+ title: ExperimentItemsResponsetype: objectproperties:- successes:- type: array- items:- $ref: '#/components/schemas/IngestionSuccess'- errors:+ data:type: arrayitems:- $ref: '#/components/schemas/IngestionError'- _deprecation:- $ref: '#/components/schemas/Deprecation'- nullable: true+ $ref: '#/components/schemas/ExperimentItem'+ meta:+ $ref: '#/components/schemas/ExperimentsResponseMeta'required:- - successes- - errors- OpenAICompletionUsageSchema:- title: OpenAICompletionUsageSchema+ - data+ - meta+ ExperimentItem:+ title: ExperimentItemtype: object- description: OpenAI Usage schema from (Chat-)Completion APIsproperties:- prompt_tokens:- type: integer- completion_tokens:- type: integer- total_tokens:- type: integer- prompt_tokens_details:- type: object- additionalProperties:- type: integer- nullable: true+ 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: stringnullable: true- completion_tokens_details:+ 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:- type: integer- nullable: true+ additionalProperties: truenullable: 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:+ description: Included when `fields=metadata` is requested.+ experimentItemMetadata:type: object- additionalProperties:- type: integer- nullable: true+ additionalProperties: truenullable: true- output_tokens_details:+ description: Included when `fields=itemMetadata` is requested.+ experimentMetadata:type: object- additionalProperties:- type: integer- nullable: true+ 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:- - 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+ - 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: SubmitFeedbackRequesttype: objectproperties:- data:- type: array- items:- type: object- additionalProperties: true+ targetType:+ $ref: '#/components/schemas/FeedbackTargetType'+ description: Category of the thing the feedback is about.+ target:+ type: stringdescription: >-- 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'+ 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: stringnullable: true+ description: >-+ Optional HTTP(S) reference URL. Langfuse stores it as text for+ triage and does not fetch it.required:- - data- legacyObservations:- title: legacyObservations+ - targetType+ - target+ - feedback+ SubmitFeedbackResponse:+ title: SubmitFeedbackResponsetype: objectproperties:- data:- type: array- items:- $ref: '#/components/schemas/Observation'- meta:- $ref: '#/components/schemas/utilsMetaResponse'+ id:+ type: string+ description: Correlation ID for the submitted feedback.required:- - data- - meta- legacyObservationsViews:- title: legacyObservationsViews+ - id+ HealthResponse:+ title: HealthResponsetype: objectproperties:- data:- type: array- items:- $ref: '#/components/schemas/ObservationsView'- meta:- $ref: '#/components/schemas/utilsMetaResponse'- _deprecation:- $ref: '#/components/schemas/Deprecation'- nullable: true+ version:+ type: string+ description: Langfuse server version+ status:+ type: stringrequired:- - data- - meta+ - version+ - statusLlmConnection:title: LlmConnectiontype: object@@ -16535,11 +13138,148 @@ components: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+ nullable: true+ description: >-+ Description is shown across the Langfuse UI and can be used to e.g.+ explain the config categories in detail, why a numeric range was+ set, or provide additional context on config name or usage+ CreateScoresRequest:+ title: CreateScoresRequest+ type: array+ items:+ $ref: '#/components/schemas/CreateScoreRequest'+ CreateScoreRequest:+ title: CreateScoreRequest+ type: object+ properties:+ id:+ type: string+ nullable: true+ traceId:+ type: string+ nullable: true+ sessionId:+ type: string+ nullable: true+ observationId:+ type: string+ nullable: true+ datasetRunId:+ type: string+ nullable: true+ name:+ type: string+ value:+ $ref: '#/components/schemas/CreateScoreValue'+ description: >-+ The value of the score. Must be passed as string for categorical and+ text scores, and numeric for boolean and numeric scores. Boolean+ score values must equal either 1 or 0 (true or false). Text score+ values must be between 1 and 500 characters.+ comment:+ type: string+ nullable: true+ metadata:+ type: object+ additionalProperties: true+ nullable: true+ environment:+ type: string+ nullable: true+ description: >-+ The environment of the score. Can be any lowercase alphanumeric+ string with hyphens and underscores that does not start with+ 'langfuse'.+ queueId:+ type: string+ nullable: true+ description: >-+ The annotation queue referenced by the score. Indicates if score was+ initially created while processing annotation queue.+ dataType:+ $ref: '#/components/schemas/ScoreDataType'+ nullable: true+ description: >-+ The data type of the score. When passing a configId this field is+ inferred. Otherwise, this field must be passed or will default to+ numeric.+ configId:+ type: string+ nullable: true+ description: >-+ Reference a score config on a score. The unique langfuse identifier+ of a score config. When passing this field, the dataType and+ stringValue fields are automatically populated.+ source:+ $ref: '#/components/schemas/CreateScoreSource'+ nullable: true+ description: >-+ The source of the score. Defaults to API. Set to ANNOTATION to+ prefill scores (e.g. from an LLM) for a human reviewer to verify in+ an annotation queue. When source is ANNOTATION, a configId is+ required unless dataType is CORRECTION. EVAL is reserved for+ internal evaluator outputs and is not accepted on this endpoint.+ timestamp:+ type: string+ format: date-time+ nullable: true+ description: >-+ The timestamp of the score, as an ISO 8601 datetime with a timezone+ offset. Defaults to the time the request is received. To update an+ existing score, send it again with the same id and timestamp.+ required:+ - name+ - value+ CreateScoreSource:+ title: CreateScoreSource+ type: string+ enum:+ - API+ - ANNOTATION+ description: |-+ Source values accepted when creating a score via the public REST API.+ EVAL is reserved for internal evaluator outputs and is intentionally not+ exposed here — use commons.ScoreSource when reading scores.+ CreateScoresResponse:+ title: CreateScoresResponse+ oneOf:+ - $ref: '#/components/schemas/CreateScoreBatchResults'+ - $ref: '#/components/schemas/CreateScoreBatchResponse'+ CreateScoreBatchResponse:+ title: CreateScoreBatchResponse+ type: object+ description: Batch accepted (HTTP 202).+ properties:+ message:+ type: string+ const: Accepted+ required:+ - message+ CreateScoreBatchResults:+ title: CreateScoreBatchResults+ type: object+ description: Acceptance counts and errors (HTTP 207).+ properties:+ accepted:+ type: integer+ rejected:+ type: integer+ errors:+ type: array+ items:+ $ref: '#/components/schemas/CreateScoreBatchError'+ required:+ - accepted+ - rejected+ - errors+ CreateScoreBatchError:+ title: CreateScoreBatchError+ type: object+ properties:+ message:+ type: string+ required:+ - messageScoreSubjectTraceV3:title: ScoreSubjectTraceV3type: object@@ -16847,18 +13587,8 @@ components:required:- data- meta- CreateScoresRequest:- title: CreateScoresRequest- oneOf:- - $ref: '#/components/schemas/CreateScoreRequest'- - $ref: '#/components/schemas/CreateScoreBatchRequest'- CreateScoreBatchRequest:- title: CreateScoreBatchRequest- type: array- items:- $ref: '#/components/schemas/CreateScoreRequest'- CreateScoreRequest:- title: CreateScoreRequest+ ScoreBody:+ title: ScoreBodytype: objectproperties:id:@@ -16878,6 +13608,18 @@ components:nullable: truename: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: >-@@ -16889,286 +13631,25 @@ components:type: stringnullable: truemetadata:- type: object- additionalProperties: truenullable: 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: truedescription: >-- 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.+ When set, must match the score value's type. If not set, will be+ inferred from the score value or configconfigId:type: stringnullable: truedescription: >-- 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.+ 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 valuesrequired:- name- value- CreateScoreSource:- title: CreateScoreSource- type: string- enum:- - API- - ANNOTATION- description: |-- Source values accepted when creating a score via the public REST API.- EVAL is reserved for internal evaluator outputs and is intentionally not- exposed here — use commons.ScoreSource when reading scores.- CreateScoresResponse:- title: CreateScoresResponse- oneOf:- - $ref: '#/components/schemas/CreateScoreBatchResults'- - $ref: '#/components/schemas/CreateScoreResponse'- - $ref: '#/components/schemas/CreateScoreBatchResponse'- CreateScoreBatchResponse:- title: CreateScoreBatchResponse- type: object- description: Batch accepted (HTTP 202).- properties:- message:- type: string- const: Accepted- required:- - message- 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- CreateScoreBatchResults:- title: CreateScoreBatchResults- type: object- description: Acceptance counts and errors (HTTP 207).- properties:- accepted:- type: integer- rejected:- type: integer- errors:- type: array- items:- $ref: '#/components/schemas/CreateScoreBatchError'- required:- - accepted- - rejected- - errors- CreateScoreBatchError:- title: CreateScoreBatchError- type: object- properties:- message:- type: string- required:- - message- 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- - metaDeleteTraceResponse:title: DeleteTraceResponsetype: object@@ -17177,14 +13658,6 @@ components:type: stringrequired:- message- Sort:- title: Sort- type: object- properties:- id:- type: string- required:- - idunstableDashboardWidgetView:title: unstableDashboardWidgetViewtype: stringdiff --git a/web/src/__tests__/server/datasets-api.servertest.ts b/web/src/__tests__/server/datasets-api.servertest.tsindex c848bc9757..5d38e8c254 100644--- a/web/src/__tests__/server/datasets-api.servertest.ts+++ b/web/src/__tests__/server/datasets-api.servertest.ts@@ -1975,6 +1975,22 @@ describe("/api/public/datasets and /api/public/dataset-items API Endpoints", ()expect(updatedItem?.input).toEqual({ value: "version 2" });expect(updatedItem?.expectedOutput).toEqual({ result: "v2" });+ // Each response carries the version of the item it returns+ expect(new Date(item1Updated.body.version).getTime()).toBeGreaterThan(+ new Date(item1.body.version).getTime(),+ );+ expect(itemsV1.body.data[0].version).toEqual(item1.body.version);+ expect(updatedItem?.version).toEqual(item1Updated.body.version);++ const itemById = await makeZodVerifiedAPICall(+ GetDatasetItemV1Response,+ "GET",+ "/api/public/dataset-items/versioned-item-1",+ undefined,+ auth,+ );+ expect(itemById.body.version).toEqual(item1Updated.body.version);+// Test 4: Verify version parameter requires datasetNameconst invalidVersion = await makeAPICall("GET",diff --git a/web/src/__tests__/server/scores-api-v1.servertest.ts b/web/src/__tests__/server/scores-api-v1.servertest.tsindex d6751c9b32..c529ef16de 100644--- a/web/src/__tests__/server/scores-api-v1.servertest.ts+++ b/web/src/__tests__/server/scores-api-v1.servertest.ts@@ -271,6 +271,180 @@ describe("/api/public/scores API Endpoint", () => {});});+ it.each([+ ["with Z", "2026-01-15T10:20:30.123Z"],+ ["with a +02:00 offset", "2026-01-15T12:20:30.123+02:00"],+ ])("should store a single score timestamp %s", async (_, timestamp) => {+ const { projectId, auth } = await createOrgProjectAndApiKey();+ const scoreId = v4();++ const response = await makeAPICall(+ "POST",+ "/api/public/scores",+ {+ id: scoreId,+ traceId: v4(),+ name: "timestamped-score",+ value: 1,+ timestamp,+ },+ auth,+ );+ expect(response.status).toBe(200);++ await waitForExpect(async () => {+ const score = await getScoreById({ projectId, scoreId });+ expect(score?.timestamp).toEqual(new Date(timestamp));+ });+ });++ it("should default the score timestamp to now", async () => {+ const { projectId, auth } = await createOrgProjectAndApiKey();+ const scoreId = v4();+ const before = Date.now();++ const response = await makeAPICall(+ "POST",+ "/api/public/scores",+ { id: scoreId, traceId: v4(), name: "untimestamped-score", value: 1 },+ auth,+ );+ expect(response.status).toBe(200);++ await waitForExpect(async () => {+ const score = await getScoreById({ projectId, scoreId });+ expect(score?.timestamp.getTime()).toBeGreaterThanOrEqual(before);+ expect(score?.timestamp.getTime()).toBeLessThanOrEqual(Date.now());+ });+ });++ it.each([+ ["without an offset", "2026-01-15T10:20:30.123"],+ ["with a space separator", "2026-01-15 10:20:30"],+ ])("should reject a single score timestamp %s", async (_, timestamp) => {+ const { auth } = await createOrgProjectAndApiKey();++ const response = await makeAPICall(+ "POST",+ "/api/public/scores",+ {+ traceId: v4(),+ name: "bad-timestamp",+ value: 1,+ timestamp,+ },+ auth,+ );++ expect(response.status).toBe(400);+ });++ it("should apply per-item timestamps in a batch with mixed timestamps", async () => {+ const { projectId, auth } = await createOrgProjectAndApiKey();+ const traceId = v4();+ const [firstId, secondId, defaultId] = [v4(), v4(), v4()];+ const firstTimestamp = "2026-01-15T10:20:30.123Z";+ const secondTimestamp = "2025-06-01T08:00:00.000+02:00";+ const before = Date.now();++ const response = await makeAPICall(+ "POST",+ "/api/public/scores",+ [+ {+ id: firstId,+ traceId,+ name: "batch-ts",+ value: 1,+ timestamp: firstTimestamp,+ },+ {+ id: secondId,+ traceId,+ name: "batch-ts",+ value: 2,+ timestamp: secondTimestamp,+ },+ { id: defaultId, traceId, name: "batch-ts", value: 3 },+ ],+ auth,+ );++ expect(response.status).toBe(202);++ await waitForExpect(async () => {+ const scores = await getScoresByIds(projectId, [+ firstId,+ secondId,+ defaultId,+ ]);+ const timestampById = new Map(+ scores.map((score) => [score.id, score.timestamp.getTime()]),+ );+ expect(timestampById.get(firstId)).toBe(+ new Date(firstTimestamp).getTime(),+ );+ expect(timestampById.get(secondId)).toBe(+ new Date(secondTimestamp).getTime(),+ );+ expect(timestampById.get(defaultId)).toBeGreaterThanOrEqual(before);+ });+ });++ it("should accept a batch body larger than the 1 MB default limit", async () => {+ const { auth } = await createOrgProjectAndApiKey();+ const comment = "x".repeat(400_000);++ const response = await makeAPICall(+ "POST",+ "/api/public/scores",+ [0, 1, 2].map((index) => ({+ traceId: v4(),+ name: `large-batch-${index}`,+ value: index,+ comment,+ })),+ auth,+ );++ expect(response.status).toBe(202);+ });++ it("should reject only the batch item with an invalid timestamp", async () => {+ const { projectId, auth } = await createOrgProjectAndApiKey();+ const validId = v4();++ const response = await makeAPICall<{+ accepted: number;+ rejected: number;+ errors: { message: string }[];+ }>(+ "POST",+ "/api/public/scores",+ [+ { id: validId, traceId: v4(), name: "valid", value: 1 },+ {+ traceId: v4(),+ name: "invalid-timestamp",+ value: 1,+ timestamp: "2026-01-15T10:20:30",+ },+ ],+ auth,+ );++ expect(response.status).toBe(207);+ expect(response.body).toEqual({+ accepted: 1,+ rejected: 1,+ errors: [{ message: expect.stringContaining("timestamp") }],+ });+ await waitForExpect(async () => {+ const scores = await getScoresByIds(projectId, [validId]);+ expect(scores).toHaveLength(1);+ });+ });+it("should summarize accepted and rejected scores in a partially failed batch", async () => {const { auth } = await createOrgProjectAndApiKey();const response = await makeAPICall<{diff --git a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts b/web/src/__tests__/server/unit/openapi-deprecations.servertest.tsindex 97ea3daceb..43a37f8be0 100644--- a/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts+++ b/web/src/__tests__/server/unit/openapi-deprecations.servertest.ts@@ -40,7 +40,6 @@ type OpenApiDocument = {schemas: Record<string, OpenApiSchema>;};};-type FernUnion = Record<string, { docs?: string; type: string }>;const definitionDirectory = path.resolve(process.cwd(),@@ -218,16 +217,6 @@ service:definitionDirectory,)) {const operation = `${method.toUpperCase()} ${endpointPath}`;- const isIngestion =- method === "post" && endpointPath === "/api/public/ingestion";-- // Ingestion is not removed: v4-only write mode rejects traces, scores stay.- if (isIngestion) {- expect(message, operation).toContain(V3_SUNSET_HUMAN);- expect(message, operation).not.toContain("will be removed");- expect(message, operation).not.toContain("becomes unavailable");- continue;- }expect(message, operation).toContain(`will be removed on ${V3_SUNSET_HUMAN}.`,@@ -279,29 +268,23 @@ service:});it("leads with the ingestion sunset and names the write successors", () => {- const ingestion = getFernDeprecatedOperations(definitionDirectory).find(- ({ method, endpointPath }) =>- method === "post" && endpointPath === "/api/public/ingestion",+ const message = INGESTION_DEPRECATION.message;+ expect(message).toContain(`shut down on ${V3_SUNSET_HUMAN}`);+ expect(message).toContain("except for score events");+ expect(message).toContain("rejects all other event types");+ expect(message).toContain("POST /api/public/scores");+ expect(message).toContain(+ "prefer upgrading to the current Python and JS SDKs",+ );+ expect(message).toContain("custom auto-instrumentation");+ expect(message).toContain("curl");+ expect(message).toContain("POST /api/public/otel/v1/traces");+ expect(message).toContain(+ "The only path to live data is OpenTelemetry ingestion",+ );+ expect(message).toContain(+ "other public APIs may have data delays of several minutes",);-- for (const message of [INGESTION_DEPRECATION.message, ingestion?.message]) {- expect(message).toContain(`shut down on ${V3_SUNSET_HUMAN}`);- expect(message).toContain("except for score events");- expect(message).toContain("rejects all other event types");- expect(message).toContain("POST /api/public/scores");- expect(message).toContain(- "prefer upgrading to the current Python and JS SDKs",- );- expect(message).toContain("custom auto-instrumentation");- expect(message).toContain("curl");- expect(message).toContain("POST /api/public/otel/v1/traces");- expect(message).toContain(- "The only path to live data is OpenTelemetry ingestion",- );- expect(message).toContain(- "other public APIs may have data delays of several minutes",- );- }// Read guidance points at the live v2 surfaces and their docs.expect(INGESTION_DEPRECATION.message).toContain(@@ -316,73 +299,6 @@ service:expect(INGESTION_DEPRECATION.message).toContain("https://langfuse.com/docs/api-and-data-platform/features/observations-api",);- expect(ingestion?.message).toContain(- "https://langfuse.com/docs/api-and-data-platform/features/scores-api",- );- expect(ingestion?.message).toContain(- "https://langfuse.com/docs/api-and-data-platform/features/observations-api",- );- expect(ingestion?.message).toContain(- "https://langfuse.com/docs/metrics/features/metrics-api",- );- });-- it("warns every sunset ingestion event type in the request body", () => {- const ingestionDefinition = parse(- fs.readFileSync(path.join(definitionDirectory, "ingestion.yml"), "utf8"),- ) as {- types: { IngestionEvent: { union: FernUnion } };- };- const ingestionEvents = ingestionDefinition.types.IngestionEvent.union;- const openApi = parseSpec(fs.readFileSync(openApiPath, "utf8"));- const supportedEventTypes = new Set(["score-create"]);- const expectedEventTypes = new Set([- "trace-create",- "score-create",- "span-create",- "span-update",- "generation-create",- "generation-update",- "event-create",- "observation-create",- "observation-update",- ]);-- expect(new Set(Object.keys(ingestionEvents))).toEqual(expectedEventTypes);-- for (const [eventType, event] of Object.entries(ingestionEvents)) {- const generatedSchema = openApi.components.schemas[event.type];-- if (supportedEventTypes.has(eventType)) {- expect(event.docs, eventType).not.toContain("Sunset warning");- expect(generatedSchema.description ?? "", eventType).not.toContain(- "Sunset warning",- );- continue;- }-- // Every rejected event type carries the full endpoint guidance, so a- // caller reading one variant does not have to find the endpoint docs.- for (const description of [event.docs, generatedSchema.description]) {- expect(description, eventType).toContain("Sunset warning");- expect(description, eventType).toContain(- `shut down on ${V3_SUNSET_HUMAN}`,- );- expect(description, eventType).toContain(- "rejects all other event types, including this one",- );- expect(description, eventType).toContain("POST /api/public/scores");- expect(description, eventType).toContain(- "POST /api/public/otel/v1/traces",- );- expect(description, eventType).toContain(- "The only path to live data is OpenTelemetry ingestion",- );- expect(description, eventType).toContain(- "other public APIs may have data delays of several minutes",- );- }- }});it("supports deprecated endpoints at a service base path", () => {diff --git a/web/src/__tests__/server/unit/python-sdk-deprecations.servertest.ts b/web/src/__tests__/server/unit/python-sdk-deprecations.servertest.tsindex 6d92c99f44..14be0dba38 100644--- a/web/src/__tests__/server/unit/python-sdk-deprecations.servertest.ts+++ b/web/src/__tests__/server/unit/python-sdk-deprecations.servertest.ts@@ -102,23 +102,7 @@ describe("Python SDK deprecations", () => {({ resourcePath, methodName }) =>`${resourcePath.replaceAll(path.sep, "/")}:${methodName}`,),- ).toEqual([- "dataset_run_items:create",- "dataset_run_items:list",- "datasets:get_run",- "datasets:delete_run",- "datasets:get_runs",- "ingestion:batch",- "legacy/metrics_v1:metrics",- "legacy/observations_v1:get",- "legacy/observations_v1:get_many",- "scores:get_many",- "scores:get_by_id",- "sessions:list",- "sessions:get",- "trace:get",- "trace:list",- ]);+ ).toEqual([]);});it("decorates sync, async, raw, and async-raw endpoint methods", () => {diff --git a/web/src/__tests__/server/unit/typescript-sdk-deprecations.servertest.ts b/web/src/__tests__/server/unit/typescript-sdk-deprecations.servertest.tsindex 6bde5d7858..923cc56997 100644--- a/web/src/__tests__/server/unit/typescript-sdk-deprecations.servertest.ts+++ b/web/src/__tests__/server/unit/typescript-sdk-deprecations.servertest.ts@@ -151,23 +151,7 @@ describe("TypeScript SDK deprecations", () => {({ generatedPath, methodName }) =>`${generatedPath.replaceAll(path.sep, "/")}:${methodName}`,),- ).toEqual([- "api/resources/datasetRunItems/client/Client.ts:create",- "api/resources/datasetRunItems/client/Client.ts:list",- "api/resources/datasets/client/Client.ts:getRun",- "api/resources/datasets/client/Client.ts:deleteRun",- "api/resources/datasets/client/Client.ts:getRuns",- "api/resources/ingestion/client/Client.ts:batch",- "api/resources/legacy/resources/metricsV1/client/Client.ts:metrics",- "api/resources/legacy/resources/observationsV1/client/Client.ts:get",- "api/resources/legacy/resources/observationsV1/client/Client.ts:getMany",- "api/resources/scores/client/Client.ts:getMany",- "api/resources/scores/client/Client.ts:getById",- "api/resources/sessions/client/Client.ts:list",- "api/resources/sessions/client/Client.ts:get",- "api/resources/trace/client/Client.ts:get",- "api/resources/trace/client/Client.ts:list",- ]);+ ).toEqual([]);expect(deprecations.filter((entry) => entry.kind === "property")diff --git a/web/src/features/public-api/server/scores-api-service.ts b/web/src/features/public-api/server/scores-api-service.tsindex e33e05e1b5..fbdfd1a449 100644--- a/web/src/features/public-api/server/scores-api-service.ts+++ b/web/src/features/public-api/server/scores-api-service.ts@@ -217,6 +217,22 @@ function determineTraceJoinRequirement(return { includeTrace, needsTraceJoin };}+function toScoreCreateEvent(body: unknown) {+ const isRecord =+ typeof body === "object" && body !== null && !Array.isArray(body);++ const { timestamp, ...scoreBody } = isRecord+ ? (body as Record<string, unknown>)+ : {};++ return {+ id: randomUUID(),+ type: eventTypes.SCORE_CREATE,+ timestamp: timestamp ?? new Date().toISOString(),+ body: isRecord ? scoreBody : body,+ };+}+export class ScoresApiService {constructor(private readonly apiVersion: "v1" | "v2") {}@@ -246,14 +262,7 @@ export class ScoresApiService {: undefined;const result = await processEventBatch(- [- {- id: randomUUID(),- type: eventTypes.SCORE_CREATE,- timestamp: new Date().toISOString(),- body: { ...body, id: scoreId },- },- ],+ [toScoreCreateEvent({ ...body, id: scoreId })],auth,{ attribution },);@@ -289,14 +298,11 @@ export class ScoresApiService {auth: AuthHeaderValidVerificationResultIngestion;attribution: IngestionAttribution;}) {- const events = bodies.map((body) => ({- id: randomUUID(),- type: eventTypes.SCORE_CREATE,- timestamp: new Date().toISOString(),- body,- }));-- const result = await processEventBatch(events, auth, { attribution });+ const result = await processEventBatch(+ bodies.map((body) => toScoreCreateEvent(body)),+ auth,+ { attribution },+ );return { result };}diff --git a/web/src/features/public-api/types/datasets.ts b/web/src/features/public-api/types/datasets.tsindex dd153c488b..85cbc0c2c2 100644--- a/web/src/features/public-api/types/datasets.ts+++ b/web/src/features/public-api/types/datasets.ts@@ -94,6 +94,7 @@ const APIDatasetItem = zdatasetId: z.string(),createdAt: z.coerce.date(),updatedAt: z.coerce.date(),+ version: z.coerce.date(),mediaReferences: z.array(APIDatasetItemMediaReference),}).strict();@@ -111,8 +112,10 @@ export const transformDbDatasetItemDomainToAPIDatasetItem = (dbDatasetItem: DatasetItemDomain & {datasetName: string;},-): Omit<z.infer<typeof APIDatasetItem>, "mediaReferences"> =>- removeObjectKeys(dbDatasetItem, ["projectId", "validFrom"]);+): Omit<z.infer<typeof APIDatasetItem>, "mediaReferences"> => {+ const { validFrom, ...item } = dbDatasetItem;+ return { ...removeObjectKeys(item, ["projectId"]), version: validFrom };+};export const transformDbDatasetRunItemToAPIDatasetRunItemCh = (dbDatasetRunItem: DatasetRunItemDomain,diff --git a/web/src/pages/api/public/scores/index.ts b/web/src/pages/api/public/scores/index.tsindex a43db81f09..1c07b1c12c 100644--- a/web/src/pages/api/public/scores/index.ts+++ b/web/src/pages/api/public/scores/index.ts@@ -16,6 +16,15 @@ import { ScoresApiService } from "@/src/features/public-api/server/scores-api-seimport { SCORES_DEPRECATION } from "@/src/features/public-api/server/deprecations";import { randomUUID } from "crypto";import { clampToDataAccessDays } from "@/src/features/entitlements/server";++export const config = {+ api: {+ bodyParser: {+ sizeLimit: "4.5mb",+ },+ },+};+export default withMiddlewares({POST: createAuthedProjectAPIRoute({name: "Create Score",@@ -23,6 +32,7 @@ export default withMiddlewares({bodySchema: PostScoresBodyV1,responseSchema: PostScoresResponseV1,allowedAccessLevels: ["project", "scores"],+ rateLimitResource: "ingestion",fn: async ({ body, auth, req, res }) => {if (auth.scope.isIngestionSuspended) {throw new ForbiddenError(diff --git a/worker/src/__tests__/otelReplay.integration.test.ts b/worker/src/__tests__/otelReplay.integration.test.tsindex 7a51b08a1d..0b824cbe1d 100644--- a/worker/src/__tests__/otelReplay.integration.test.ts+++ b/worker/src/__tests__/otelReplay.integration.test.ts@@ -725,14 +725,20 @@ describe(imageBytes.toString("base64"),"@@@langfuseMedia:type=image/png|id=overflow-media-id|source=bytes@@@",);+ // A string value that looks like JSON keeps its per-key encoding.+ // The reference path does not scan inside that encoding and leaves+ // its media inline; only the early path extracts it.+ const expandedJsonString = JSON.stringify(+ JSON.stringify({ image: expandedImage }),+ );+ const earlyExpandedValues = {+ json_string: expandedJsonString,+ escaped_json_string: expandedJsonString,+ quoted_provider: JSON.stringify(expandedProvider),+ };expectSdkMetadataExpansion(comparison,- uploadOutcome === "success"- ? {- escaped_json_string: JSON.stringify({ image: expandedImage }),- quoted_provider: expandedProvider,- }- : {},+ uploadOutcome === "success" ? earlyExpandedValues : {},);expect(comparison.earlyTs.sideEffects).toEqual(comparison.originalTs.sideEffects,@@ -757,10 +763,13 @@ describe(uploadOutcome === "success"? "@@@langfuseMedia:type=image/png|id=overflow-media-id|source=base64_data_uri@@@": dataUri;- const expectedJsonString =- uploadOutcome === "success"- ? JSON.stringify({ image: expectedImage })- : structuredMetadata.jsonString;+ const inlineJsonLookingValues = {+ json_string: JSON.stringify(structuredMetadata.jsonString),+ escaped_json_string: JSON.stringify(+ structuredMetadata.escapedJsonString,+ ),+ quoted_provider: JSON.stringify(structuredMetadata.providerJson),+ };expect(comparison.originalTs.storedRows).toHaveLength(1);const originalMetadata = Object.fromEntries(eventMetadataByPath(comparison.originalTs.storedRows[0]),@@ -768,9 +777,7 @@ describe(expect(originalMetadata).toMatchObject({quoted: "quoted value","asset.attachment.image": expectedImage,- json_string: expectedJsonString,- escaped_json_string: structuredMetadata.escapedJsonString,- quoted_provider: structuredMetadata.providerJson,+ ...inlineJsonLookingValues,truncated: '{"value":"cut',"collision.key": "blob wins",});@@ -785,9 +792,7 @@ describe(asset: JSON.stringify({attachment: { image: expectedImage },}),- json_string: expectedJsonString,- escaped_json_string: structuredMetadata.escapedJsonString,- quoted_provider: structuredMetadata.providerJson,+ ...inlineJsonLookingValues,truncated: '{"value":"cut',collision: JSON.stringify({ key: "blob wins" }),"collision.key": "dotted loses",@@ -797,10 +802,7 @@ describe(const earlyMetadata = Object.fromEntries(eventMetadataByPath(comparison.earlyTs.storedRows[0]),);- expect(earlyMetadata).toMatchObject({- escaped_json_string: JSON.stringify({ image: expandedImage }),- quoted_provider: expandedProvider,- });+ expect(earlyMetadata).toMatchObject(earlyExpandedValues);}} finally {preparation.mockRestore();