Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

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.yml
index 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: string
concurrency:
- 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: true
permissions:
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 repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
@@ -77,7 +103,7 @@ jobs:
id: prepare-python-sdk
run: |
# 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-python
cd ../langfuse-python
git config user.name "langfuse-bot"
@@ -135,7 +161,7 @@ jobs:
id: prepare-typescript-sdk
run: |
# 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-js
cd ../langfuse-js
# Configure git
@@ -163,9 +189,15 @@ jobs:
fi
fi
- # 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 enable
pnpm install
+ if [ -f scripts/patch-generated-request-placeholders.mjs ]; then
+ node scripts/patch-generated-request-placeholders.mjs
+ fi
pnpm 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; do
if [ -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; do
if [ -n "$pr_number" ] && [ "$pr_number" != "$NEW_PR_NUMBER" ]; then
"$GH_BIN" pr close --repo langfuse/langfuse-js "$pr_number"
fi
diff --git a/fern/apis/server/definition/commons.yml b/fern/apis/server/definition/commons.yml
index 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 - APIObservationV2
ObservationV2:
docs: |
@@ -434,83 +229,6 @@ types:
properties:
value: double
label: 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 - APIScoreSchemaV2
BaseScore:
properties:
@@ -675,6 +393,9 @@ types:
datasetName: string
createdAt: datetime
updatedAt: 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: string
docs: 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 - APIModelDefinition
Model:
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: 400
diff --git a/fern/apis/server/definition/dataset-run-items.yml b/fern/apis/server/definition/dataset-run-items.yml
deleted file mode 100644
index 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.yml
index d43b61a333..db825959de 100644
--- a/fern/apis/server/definition/datasets.yml
+++ b/fern/apis/server/definition/datasets.yml
@@ -33,48 +33,6 @@ service:
path: /v2/datasets
request: CreateDatasetRequest
response: 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: string
diff --git a/fern/apis/server/definition/experiments.yml b/fern/apis/server/definition/experiments.yml
index 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.json
imports:
commons: ./commons.yml
- scoresV3: ./scores-v3.yml
+ scores: ./scores.yml
pagination: ./utils/pagination.yml
service:
@@ -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.yml
deleted file mode 100644
index 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
- - OpenAIResponseUsageSchema
diff --git a/fern/apis/server/definition/legacy/metrics-v1.yml b/fern/apis/server/definition/legacy/metrics-v1.yml
deleted file mode 100644
index 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.yml
deleted file mode 100644
index 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.yml
deleted file mode 100644
index 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 score
diff --git a/fern/apis/server/definition/scores-v3.yml b/fern/apis/server/definition/scores-v3.yml
deleted file mode 100644
index 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: GetScoresV3Meta
diff --git a/fern/apis/server/definition/scores.yml b/fern/apis/server/definition/scores.yml
index 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.json
imports:
- pagination: ./utils/pagination.yml
commons: ./commons.yml
+ pagination: ./utils/pagination.yml
service:
auth: true
base-path: /api/public
endpoints:
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: POST
path: /scores
request: CreateScoresRequest
response: 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/scores
request:
- name: GetScoresRequest
+ name: GetScoresV3Request
query-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: GetScoresV3Response
types:
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
- CreateScoreBatchResponse
CreateScoreBatchResponse:
@@ -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: datetime
environment:
- 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: BaseScoreV3
properties:
- trace: optional<GetScoresResponseTraceData>
+ value:
+ type: double
+ docs: The numeric value of the score.
- GetScoresResponseDataCategorical:
- extends: commons.CategoricalScore
+ BooleanScoreV3:
+ extends: BaseScoreV3
properties:
- trace: optional<GetScoresResponseTraceData>
+ value:
+ type: boolean
+ docs: The boolean value of the score.
- GetScoresResponseDataBoolean:
- extends: commons.BooleanScore
+ CategoricalScoreV3:
+ extends: BaseScoreV3
properties:
- trace: optional<GetScoresResponseTraceData>
+ value:
+ type: string
+ docs: The string category value of the score.
- GetScoresResponseDataCorrection:
- extends: commons.CorrectionScore
+ TextScoreV3:
+ extends: BaseScoreV3
properties:
- trace: optional<GetScoresResponseTraceData>
+ value:
+ type: string
+ docs: The text content of the score.
- GetScoresResponseDataText:
- extends: commons.TextScore
+ CorrectionScoreV3:
+ extends: BaseScoreV3
properties:
- trace: optional<GetScoresResponseTraceData>
+ value:
+ type: string
+ docs: The correction content of the score. Empty string if not set.
- GetScoresResponseData:
+ ScoreV3:
discriminant: dataType
union:
- 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.CursorMetaResponse
properties:
- 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.yml
deleted file mode 100644
index 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.yml
index 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.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. 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.TraceWithFullDetails
delete:
docs: Delete a specific trace
method: DELETE
@@ -33,162 +12,6 @@ service:
type: string
docs: The unique langfuse identifier of the trace to delete
response: 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: Traces
deleteMultiple:
docs: Delete multiple traces
method: DELETE
@@ -203,14 +26,6 @@ service:
response: DeleteTraceResponse
types:
- Traces:
- properties:
- data: list<commons.TraceWithDetails>
- meta: pagination.MetaResponse
- _deprecation: optional<commons.Deprecation>
DeleteTraceResponse:
properties:
message: string
- Sort:
- properties:
- id: string
diff --git a/packages/shared/src/features/scores/interfaces/api/shared.ts b/packages/shared/src/features/scores/interfaces/api/shared.ts
index 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.ts
index 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.ts
index 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.ts
index 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.yml
index 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_upsert
tags:
- - Ingestion
+ - LlmConnections
parameters: []
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_delete
tags:
- - LegacyMetricsV1
+ - LlmConnections
parameters:
- - name: query
- in: query
- description: >-
- JSON string containing the query parameters with the following
- structure:
-
- ```json
-
- {
- "view": string, // Required. One of "traces", "observations", "scores-numeric", "scores-boolean", "scores-categorical"
- "dimensions": [ // Optional. Default: []
- {
- "field": string // Field to group by, e.g. "name", "userId", "sessionId"
- }
- ],
- "metrics": [ // Required. At least one metric must be provided
- {
- "measure": string, // What to measure, e.g. "count", "latency", "value"
- "aggregation": string // How to aggregate, e.g. "count", "sum", "avg", "p95", "histogram"
- }
- ],
- "filters": [ // Optional. Default: []
- {
- "column": string, // Column to filter on
- "operator": string, // Operator, e.g. "=", ">", "<", "contains"
- "value": any, // Value to compare against
- "type": string, // Data type, e.g. "string", "number", "stringObject"
- "key": string // Required only when filtering on metadata
- }
- ],
- "timeDimension": { // Optional. Default: null. If provided, results will be grouped by time
- "granularity": string // One of "minute", "hour", "day", "week", "month", "auto"
- },
- "fromTimestamp": string, // Required. ISO datetime string for start of time range
- "toTimestamp": string, // Required. ISO datetime string for end of time range
- "orderBy": [ // Optional. Default: null
- {
- "field": string, // Field to order by
- "direction": string // "asc" or "desc"
- }
- ],
- "config": { // Optional. Query-specific configuration
- "bins": number, // Optional. Number of bins for histogram (1-100), default: 10
- "row_limit": number // Optional. Row limit for results (1-1000)
- }
- }
-
- ```
+ - name: id
+ in: path
required: true
schema:
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_get
tags:
- - LegacyObservationsV1
+ - Media
parameters:
- - name: observationId
+ - name: mediaId
in: 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 record
required: true
schema:
type: string
+ responses:
+ '204':
+ description: ''
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ security: *ref_0
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/PatchMediaBody'
+ /api/public/media:
+ post:
+ description: Get a presigned upload URL for a media record
+ operationId: media_getUploadUrl
+ tags:
+ - Media
+ parameters: []
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/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_create
tags:
- - 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_list
tags:
- - LlmConnections
+ - Models
parameters:
- name: page
in: 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_upsert
tags:
- - LlmConnections
- parameters: []
- responses:
- '200':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/LlmConnection'
- '400':
- description: ''
- content:
- application/json:
- schema: {}
- '401':
- description: ''
- content:
- application/json:
- schema: {}
- '403':
- description: ''
- content:
- application/json:
- schema: {}
- '404':
- description: ''
- content:
- application/json:
- schema: {}
- '405':
- description: ''
- content:
- application/json:
- schema: {}
- security: *ref_0
- requestBody:
- required: true
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/UpsertLlmConnectionRequest'
- /api/public/llm-connections/{id}:
- delete:
- description: >-
- Delete an LLM connection by id. Evaluators that depend on the deleted
- connection are automatically paused.
- operationId: llmConnections_delete
- tags:
- - LlmConnections
+ - Models
parameters:
- name: id
in: 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_get
tags:
- - Media
+ - Models
parameters:
- - name: mediaId
+ - name: id
in: path
- description: The unique langfuse identifier of a media record
required: true
schema:
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_delete
tags:
- - Media
+ - Models
parameters:
- - name: mediaId
+ - name: id
in: path
- description: The unique langfuse identifier of a media record
required: true
schema:
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: false
schema:
type: string
+ nullable: true
responses:
'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_exportTraces
tags:
- - Models
+ - Opentelemetry
parameters: []
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_getOrganizationMemberships
tags:
- - Models
- parameters:
- - name: page
- in: query
- description: page number, starts at 1
- required: false
- schema:
- type: integer
- nullable: true
- - name: limit
- in: query
- description: limit of items per page
- required: false
- schema:
- type: integer
- nullable: true
+ - 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_updateOrganizationMembership
tags:
- - 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_deleteOrganizationMembership
tags:
- - 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:
+ - Organizations
parameters:
- - name: id
+ - name: projectId
in: path
required: true
schema:
@@ -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_updateProjectMembership
tags:
- - Models
+ - Organizations
parameters:
- - name: id
+ - name: projectId
in: path
required: true
schema:
type: string
responses:
- '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_deleteProjectMembership
tags:
- - Observations
+ - Organizations
parameters:
- - name: fields
- in: query
- description: >-
- Comma-separated list of field groups to include in the response.
-
- Available groups: core, basic, time, io, metadata, model, usage,
- prompt, metrics, trace_context.
-
- If not specified, `core` and `basic` field groups are returned.
-
- Example: "basic,usage,model"
- required: false
- schema:
- type: string
- nullable: true
- - name: expandMetadata
- in: query
- description: |-
- Comma-separated list of metadata keys to return non-truncated.
- By default, metadata values over 200 characters are truncated.
- Use this parameter to retrieve full values for specific keys.
- Example: "key1,key2"
- required: false
- schema:
- type: string
- nullable: true
- - name: limit
- in: query
- description: Number of items to return per page. Maximum 1000, default 50.
- required: false
- schema:
- type: integer
- nullable: true
- - name: cursor
- in: query
- description: >-
- Base64-encoded cursor for pagination. Use the cursor from the
- previous response to get the next page.
- required: false
- schema:
- type: string
- nullable: true
- - name: parseIoAsJson
- in: query
- description: |-
- **Deprecated.** Setting this to `true` will return a 400 error.
- Input/output fields are always returned as raw strings.
- Remove this parameter or set it to `false`.
- required: false
- schema:
- type: boolean
- nullable: true
- - name: name
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: userId
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: sessionId
- in: query
- description: Filter by session ID.
- required: false
- schema:
- type: string
- nullable: true
- - name: type
- in: query
- description: >-
- Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT",
- "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING",
- "GUARDRAIL")
- required: false
- schema:
- type: string
- nullable: true
- - name: traceId
- in: query
- required: false
+ - name: projectId
+ in: path
+ required: true
schema:
type: string
- nullable: true
- - name: level
- in: query
- description: >-
- Optional filter for observations with a specific level (e.g.
- "DEBUG", "DEFAULT", "WARNING", "ERROR").
- required: false
- schema:
- $ref: '#/components/schemas/ObservationLevel'
- nullable: true
- - name: parentObservationId
- in: query
- description: >-
- Filter by the physical parent observation ID.
-
- An empty value matches only observations without a physical parent.
- Use `isRootObservation` to include observations marked as app roots
- by the SDK, which may retain a non-null `parentObservationId`.
- required: false
- schema:
- type: string
- nullable: true
- - name: isRootObservation
- in: query
- description: >-
- Filter by whether an observation is a logical root.
-
- Root observations include observations without a physical parent and
- observations marked as app roots by the SDK.
-
- An app-root observation may have `isRootObservation=true` and a
- non-null `parentObservationId`.
- required: false
- schema:
- type: boolean
- nullable: true
- - name: environment
- in: query
- description: >-
- Optional filter for observations where the environment is one of the
- provided values.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
- - name: fromStartTime
- in: query
- description: >-
- Retrieve only observations with a start_time on or after this
- datetime (ISO 8601).
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: toStartTime
- in: query
- description: >-
- Retrieve only observations with a start_time before this datetime
- (ISO 8601).
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: version
- in: query
- description: Optional filter to only include observations with a certain version.
- required: false
- schema:
- type: string
- nullable: true
- - name: filter
- in: query
- description: >-
- JSON string containing an array of filter conditions. When provided,
- this takes precedence over query parameter filters (userId, name,
- type, level, environment, fromStartTime, ...).
-
-
- ## Filter Structure
-
- Each filter condition has the following structure:
-
- ```json
-
- [
- {
- "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
- "column": string, // Required. Column to filter on (see available columns below)
- "operator": string, // Required. Operator based on type:
- // - datetime: ">", "<", ">=", "<="
- // - string: "=", "contains", "does not contain", "starts with", "ends with", "matches"
- // - stringOptions: "any of", "none of"
- // - categoryOptions: "any of", "none of"
- // - arrayOptions: "any of", "none of", "all of"
- // - number: "=", ">", "<", ">=", "<="
- // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "matches", "is set", "is not set"
- // - numberObject: "=", ">", "<", ">=", "<="
- // - boolean: "=", "<>"
- // - null: "is null", "is not null"
- "value": any, // Required (except for null type). Value to compare against. Type depends on filter type
- "key": string // Required only for stringObject, numberObject, and categoryOptions types when filtering on nested fields like metadata
- }
- ]
-
- ```
-
-
- ## Available Columns
-
-
- ### Core Observation Fields
-
- - `id` (string) - Observation ID
-
- - `type` (string) - Observation type (SPAN, GENERATION, EVENT)
-
- - `name` (string) - Observation name
-
- - `traceId` (string) - Associated trace ID
-
- - `startTime` (datetime) - Observation start time
-
- - `endTime` (datetime) - Observation end time
-
- - `environment` (string) - Environment tag
-
- - `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
-
- - `statusMessage` (string) - Status message
-
- - `version` (string) - Version tag
-
- - `userId` (string) - User ID
-
- - `sessionId` (string) - Session ID
-
- - `isRootObservation` (boolean) - Whether the observation is a
- logical root. Observations marked as app roots by the SDK may retain
- a non-null parentObservationId.
-
-
- ### Trace-Related Fields
-
- - `traceName` (string) - Name of the parent trace
-
- - `traceTags` (arrayOptions) - Tags from the parent trace
-
- - `tags` (arrayOptions) - Alias for traceTags
-
-
- ### Performance Metrics
-
- - `latency` (number) - Latency in seconds (calculated: end_time -
- start_time)
-
- - `timeToFirstToken` (number) - Time to first token in seconds
-
- - `tokensPerSecond` (number) - Output tokens per second
-
-
- ### Token Usage
-
- - `inputTokens` (number) - Number of input tokens
-
- - `outputTokens` (number) - Number of output tokens
-
- - `totalTokens` (number) - Total tokens (alias: `tokens`)
-
-
- ### Cost Metrics
-
- - `inputCost` (number) - Input cost in USD
-
- - `outputCost` (number) - Output cost in USD
-
- - `totalCost` (number) - Total cost in USD
-
-
- ### Model Information
-
- - `model` (string) - Provided model name (alias:
- `providedModelName`)
-
- - `promptName` (string) - Associated prompt name
-
- - `promptVersion` (number) - Associated prompt version
-
-
- ### Structured Data
-
- - `input` (string) - Observation input. Supports accelerated indexed
- literal search with the `matches` operator.
-
- - `output` (string) - Observation output. Supports accelerated
- indexed literal search with the `matches` operator.
-
- - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
- key-value pairs. Use `key` parameter to filter on specific metadata
- keys.
-
-
- The `matches` operator is only supported for `input`, `output`, and
- stringObject `metadata` filters. It performs indexed literal search
- with token-boundary pruning using the events table text indexes.
- Case sensitivity differs by target: `input` and `output` matches are
- case-insensitive, while metadata value matches are case-sensitive.
- Unlike SQL `LIKE`, `%` and `_` are treated as literal characters.
- Use `contains` for legacy substring semantics where the API allows
- it. Any v2 `input` or `output` filter must be accompanied by at
- least one `=` or `matches` filter on `input` or `output`; standalone
- `contains`, `starts with`, `ends with`, and `does not contain`
- filters on these columns are rejected.
-
-
- ## Filter Examples
-
- ```json
-
- [
- {
- "type": "string",
- "column": "type",
- "operator": "=",
- "value": "GENERATION"
- },
- {
- "type": "number",
- "column": "latency",
- "operator": ">=",
- "value": 2.5
- },
- {
- "type": "stringObject",
- "column": "metadata",
- "key": "environment",
- "operator": "=",
- "value": "production"
- },
- {
- "type": "string",
- "column": "output",
- "operator": "matches",
- "value": "needle"
- },
- {
- "type": "boolean",
- "column": "isRootObservation",
- "operator": "=",
- "value": true
- }
- ]
-
- ```
- required: false
- schema:
- type: string
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/ObservationsV2Response'
+ $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_getOrganizationProjects
tags:
- - Opentelemetry
+ - Organizations
parameters: []
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_getOrganizationApiKeys
tags:
- Organizations
parameters: []
@@ -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_get
tags:
- - Organizations
+ - Projects
parameters: []
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_create
tags:
- - Organizations
+ - Projects
parameters: []
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_update
tags:
- - Organizations
+ - Projects
parameters:
- name: projectId
in: 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_delete
tags:
- - Organizations
+ - Projects
parameters:
- name: projectId
in: path
@@ -5054,12 +4439,12 @@ paths:
schema:
type: string
responses:
- '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_getApiKeys
tags:
- - Organizations
+ - Projects
parameters:
- name: projectId
in: 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_createApiKey
tags:
- - Organizations
- parameters: []
+ - Projects
+ parameters:
+ - name: projectId
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'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_deleteApiKey
tags:
- Projects
- parameters: []
+ parameters:
+ - name: projectId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: apiKeyId
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/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_update
tags:
- - 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: integer
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/Project'
+ $ref: '#/components/schemas/Prompt'
'400':
description: ''
content:
@@ -5318,41 +4714,67 @@ paths:
schema:
type: object
properties:
- name:
- type: string
- metadata:
- type: object
- additionalProperties: true
- nullable: true
- description: Optional metadata for the project
- retention:
- type: integer
+ newLabels:
+ type: array
+ items:
+ type: string
description: >-
- 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_get
tags:
- - Projects
+ - Prompts
parameters:
- - name: projectId
+ - name: promptName
in: path
+ description: >-
+ The name of the prompt. If the prompt is in a folder (e.g.,
+ "folder/subfolder/prompt-name"),
+
+ the folder path must be URL encoded.
required: true
schema:
type: string
+ - name: version
+ in: query
+ description: Version of the prompt to be retrieved.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: label
+ in: query
+ description: >-
+ Label of the prompt to be retrieved. Defaults to "production" if no
+ label or version is set.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: resolve
+ in: query
+ description: >-
+ Resolve prompt dependencies before returning the prompt. Defaults to
+ `true`. Set to `false` to return the raw stored prompt with
+ dependency tags intact. This bypasses prompt caching and is intended
+ for debugging or one-off jobs, not production runtime fetches.
+ required: false
+ schema:
+ type: boolean
+ nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/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:
- - name
delete:
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_delete
tags:
- - Projects
+ - Prompts
parameters:
- - name: projectId
+ - 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:
- '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_list
tags:
- - Projects
+ - Prompts
parameters:
- - name: projectId
- in: path
- required: true
+ - name: name
+ in: query
+ required: false
schema:
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_0
post:
- 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_create
tags:
- - 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_getServiceProviderConfig
tags:
- - 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_getResourceTypes
tags:
- - PromptVersion
- parameters:
- - name: name
- in: path
- description: >-
- The name of the prompt. If the prompt is in a folder (e.g.,
- "folder/subfolder/prompt-name"),
-
- the folder path must be URL encoded.
- required: true
- schema:
- type: string
- - name: version
- in: path
- description: Version of the prompt to update
- required: true
- schema:
- type: integer
+ - 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_getSchemas
tags:
- - Prompts
- parameters:
- - name: promptName
- in: path
- description: >-
- The name of the prompt. If the prompt is in a folder (e.g.,
- "folder/subfolder/prompt-name"),
-
- the folder path must be URL encoded.
- required: true
- schema:
- type: string
- - name: version
- in: query
- description: Version of the prompt to be retrieved.
- required: false
- schema:
- type: integer
- nullable: true
- - name: label
- in: query
- description: >-
- Label of the prompt to be retrieved. Defaults to "production" if no
- label or version is set.
- required: false
- schema:
- type: string
- nullable: true
- - name: resolve
- in: query
- description: >-
- Resolve prompt dependencies before returning the prompt. Defaults to
- `true`. Set to `false` to return the raw stored prompt with
- dependency tags intact. This bypasses prompt caching and is intended
- for debugging or one-off jobs, not production runtime fetches.
- required: false
- schema:
- type: boolean
- nullable: true
+ - 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_listUsers
tags:
- - Prompts
+ - Scim
parameters:
- - name: name
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: label
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: tag
+ - name: filter
in: query
+ description: Filter expression (e.g. userName eq "value")
required: false
schema:
type: string
nullable: true
- - name: page
+ - name: startIndex
in: query
- description: page number, starts at 1
+ description: 1-based index of the first result to return (default 1)
required: false
schema:
type: integer
nullable: true
- - name: limit
+ - name: count
in: query
- description: limit of items per page
+ description: Maximum number of results to return (default 100)
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'
+ $ref: '#/components/schemas/ScimUsersListResponse'
'400':
description: ''
content:
@@ -5998,10 +5248,12 @@ paths:
schema: {}
security: *ref_0
post:
- 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_createUser
tags:
- - Prompts
+ - Scim
parameters: []
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_create
tags:
- - ScoresV3
- parameters:
- - name: limit
- in: query
- description: >-
- Number of items per page. Maximum 100, default 50. Requests with a
- limit greater than 100 return HTTP 400.
- required: false
- schema:
- type: integer
- nullable: true
- - name: cursor
- in: query
- description: >-
- URL-safe base64 (base64url) cursor for pagination. Use the cursor
- from the previous response to get the next page. Absent on the final
- page.
- required: false
- schema:
- type: string
- nullable: true
- - name: fields
- in: query
- description: >-
- Comma-separated field groups to include in addition to the
- always-returned core fields. Allowed: details, subject, annotation —
- see the endpoint description for the fields each group adds. Unknown
+ - Scores
+ parameters: []
+ responses:
+ '200':
+ description: ''
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateScoresResponse'
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ security: *ref_0
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CreateScoresRequest'
+ /api/public/scores/{scoreId}:
+ delete:
+ description: Delete a score (supports both trace and session scores)
+ operationId: scores_delete
+ tags:
+ - Scores
+ parameters:
+ - name: scoreId
+ in: path
+ description: The unique langfuse identifier of a score
+ required: true
+ schema:
+ type: string
+ responses:
+ '204':
+ description: ''
+ '400':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '401':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '403':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '404':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ '405':
+ description: ''
+ content:
+ application/json:
+ schema: {}
+ security: *ref_0
+ /api/public/v3/scores:
+ get:
+ description: |-
+ Get a list of scores with a polymorphic `value` field (v3).
+
+ The `value` field type depends on `dataType`:
+ - `NUMERIC` → number
+ - `BOOLEAN` → boolean
+ - `CATEGORICAL`, `TEXT`, `CORRECTION` → string
+
+ The response always includes the core fields: id, projectId, name,
+ value, dataType, source, timestamp, environment, createdAt, updatedAt.
+
+ Additional field groups can be requested via the `fields` parameter:
+ - `details` — adds comment, configId, metadata
+ - `subject` — adds the subject object describing the entity the score
+ is attached to: kind (trace, observation, session, or experiment),
+ id, and traceId for observation-level scores
+ - `annotation` — adds authorUserId, queueId
+
+ Unknown group names return HTTP 400.
+ operationId: scores_getMany
+ tags:
+ - Scores
+ parameters:
+ - name: limit
+ in: query
+ description: >-
+ Number of items per page. Maximum 100, default 50. Requests with a
+ limit greater than 100 return HTTP 400.
+ required: false
+ schema:
+ type: integer
+ nullable: true
+ - name: cursor
+ in: query
+ description: >-
+ URL-safe base64 (base64url) cursor for pagination. Use the cursor
+ from the previous response to get the next page. Absent on the final
+ page.
+ required: false
+ schema:
+ type: string
+ nullable: true
+ - name: fields
+ in: query
+ description: >-
+ Comma-separated field groups to include in addition to the
+ always-returned core fields. Allowed: details, subject, annotation —
+ see the endpoint description for the fields each group adds. Unknown
names return HTTP 400.
required: false
schema:
@@ -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_delete
tags:
- - 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:
+ - Trace
parameters: []
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_list
tags:
- - Scores
+ - UnstableDashboardWidgets
parameters:
- name: page
in: query
- description: Page number, starts at 1.
+ description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- name: limit
in: query
- description: >-
- Limit of items per page. Maximum 100. Defaults to 50. Requests with
- a limit greater than 100 return HTTP 400. If you encounter api
- issues due to too large page sizes, try to reduce the limit.
+ description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
type: integer
nullable: true
- - name: userId
- in: query
- description: Retrieve only scores with this userId associated to the trace.
- required: false
- schema:
- type: string
- nullable: true
- - name: name
- in: query
- description: Retrieve only scores with this name.
- required: false
- schema:
- type: string
- nullable: true
- - name: fromTimestamp
- in: query
- description: >-
- Optional filter to only include scores created on or after a certain
- datetime (ISO 8601)
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: toTimestamp
- in: query
- description: >-
- Optional filter to only include scores created before a certain
- datetime (ISO 8601)
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: environment
- in: query
- description: >-
- Optional filter for scores where the environment is one of the
- provided values.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
- - name: source
- in: query
- description: Retrieve only scores from a specific source.
- required: false
- schema:
- $ref: '#/components/schemas/ScoreSource'
- nullable: true
- - name: operator
- in: query
- description: Retrieve only scores with <operator> value.
- required: false
- schema:
- type: string
- nullable: true
- - name: value
- in: query
- description: Retrieve only scores with <operator> value.
- required: false
- schema:
- type: number
- format: double
- nullable: true
- - name: scoreIds
- in: query
- description: Comma-separated list of score IDs to limit the results to.
- required: false
- schema:
- type: string
- nullable: true
- - name: configId
- in: query
- description: Retrieve only scores with a specific configId.
- required: false
- schema:
- type: string
- nullable: true
- - name: sessionId
- in: query
- description: Retrieve only scores with a specific sessionId.
- required: false
- schema:
- type: string
- nullable: true
- - name: datasetRunId
- in: query
- description: Retrieve only scores with a specific datasetRunId.
- required: false
- schema:
- type: string
- nullable: true
- - name: traceId
- in: query
- description: Retrieve only scores with a specific traceId.
- required: false
- schema:
- type: string
- nullable: true
- - name: observationId
- in: query
- description: Comma-separated list of observation IDs to filter scores by.
- required: false
- schema:
- type: string
- nullable: true
- - name: queueId
- in: query
- description: Retrieve only scores with a specific annotation queueId.
- required: false
- schema:
- type: string
- nullable: true
- - name: dataType
- in: query
- description: Retrieve only scores with a specific dataType.
- required: false
- schema:
- $ref: '#/components/schemas/ScoreDataType'
- nullable: true
- - name: traceTags
- in: query
- description: >-
- Only scores linked to traces that include all of these tags will be
- returned.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
- - name: fields
- in: query
- description: >-
- Comma-separated list of field groups to include in the response.
- Available field groups: 'score' (core score fields), 'trace' (trace
- properties: userId, tags, environment, sessionId). If not specified,
- both 'score' and 'trace' are returned by default. Example: 'score'
- to exclude trace data, 'score,trace' to include both. Note: When
- filtering by trace properties (using userId or traceTags
- parameters), the 'trace' field group must be included, otherwise a
- 400 error will be returned.
- required: false
- schema:
- type: string
- nullable: true
- - name: filter
- in: query
- description: >-
- A JSON stringified array of filter objects. Each object requires
- type, column, operator, and value. Supports filtering by score
- metadata using the stringObject type. Example:
- [{"type":"stringObject","column":"metadata","key":"user_id","operator":"=","value":"abc123"}].
- Supported types: stringObject (metadata key-value filtering),
- string, number, datetime, stringOptions, arrayOptions. Supported
- operators for stringObject: =, contains, does not contain, starts
- with, ends with, is set, is not set. Use is set / is not set to
- filter on metadata key presence. An empty value for contains, starts
- with, or ends with is treated as is set (key presence).
- required: false
- schema:
- type: string
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/GetScoresResponse'
+ $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_create
tags:
- - 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_get
tags:
- - Sessions
+ - UnstableDashboardWidgets
parameters:
- - name: page
- in: query
- description: Page number, starts at 1
- required: false
- schema:
- type: integer
- nullable: true
- - name: limit
- in: query
- description: >-
- Limit of items per page. If you encounter api issues due to too
- large page sizes, try to reduce the limit.
- required: false
- schema:
- type: integer
- nullable: true
- - name: fromTimestamp
- in: query
- description: >-
- Optional filter to only include sessions created on or after a
- certain datetime (ISO 8601)
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: toTimestamp
- in: query
- description: >-
- Optional filter to only include sessions created before a certain
- datetime (ISO 8601)
- required: false
+ - name: widgetId
+ in: path
+ required: true
schema:
type: string
- format: date-time
- nullable: true
- - name: environment
- in: query
- description: >-
- Optional filter for sessions where the environment is one of the
- provided values.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/PaginatedSessions'
+ $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_update
tags:
- - Sessions
+ - UnstableDashboardWidgets
parameters:
- - name: sessionId
+ - name: widgetId
in: path
- description: The unique id of a session
required: true
schema:
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_delete
tags:
- - Trace
+ - UnstableDashboardWidgets
parameters:
- - name: traceId
+ - name: widgetId
in: path
- description: The unique langfuse identifier of a trace
required: true
schema:
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: page
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'.
+ description: 1-based page number. Defaults to `1`.
required: false
schema:
- type: string
+ type: integer
+ nullable: true
+ - name: limit
+ in: query
+ description: Maximum number of items per page. Defaults to `50`.
+ required: false
+ schema:
+ type: integer
nullable: true
responses:
'200':
@@ -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_create
tags:
- - 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:
+ - UnstableDashboards
parameters:
- - name: traceId
+ - name: dashboardId
in: path
- description: The unique langfuse identifier of the trace to delete
required: true
schema:
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_update
tags:
- - Trace
+ - UnstableDashboards
parameters:
- - name: page
- in: query
- description: Page number, starts at 1
- required: false
- schema:
- type: integer
- nullable: true
- - name: limit
- in: query
- description: >-
- Limit of items per page. If you encounter api issues due to too
- large page sizes, try to reduce the limit.
- required: false
- schema:
- type: integer
- nullable: true
- - name: userId
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: name
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: sessionId
- in: query
- required: false
- schema:
- type: string
- nullable: true
- - name: fromTimestamp
- in: query
- description: >-
- Optional filter to only include traces with a trace.timestamp on or
- after a certain datetime (ISO 8601)
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: toTimestamp
- in: query
- description: >-
- Optional filter to only include traces with a trace.timestamp before
- a certain datetime (ISO 8601)
- required: false
- schema:
- type: string
- format: date-time
- nullable: true
- - name: orderBy
- in: query
- description: >-
- Format of the string [field].[asc/desc]. Fields: id, timestamp,
- name, userId, release, version, public, bookmarked, sessionId.
- Example: timestamp.asc
- required: false
+ - name: dashboardId
+ in: path
+ required: true
schema:
type: string
- nullable: true
- - name: tags
- in: query
- description: Only traces that include all of these tags will be returned.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
- - name: version
- in: query
- description: Optional filter to only include traces with a certain version.
- required: false
- schema:
- type: string
- nullable: true
- - name: release
- in: query
- description: Optional filter to only include traces with a certain release.
- required: false
- schema:
- type: string
- nullable: true
- - name: environment
- in: query
- description: >-
- Optional filter for traces where the environment is one of the
- provided values.
- required: false
- schema:
- type: array
- items:
- type: string
- nullable: true
- - name: fields
- in: query
- description: >-
- Comma-separated list of fields to include in the response. Available
- field groups: 'core' (always included), 'io' (input, output,
- metadata), 'scores', 'observations', 'metrics'. If not specified,
- all fields are returned. Example: 'core,scores,metrics'. Note:
- Excluded 'observations' or 'scores' fields return empty arrays;
- excluded 'metrics' returns -1 for 'totalCost' and 'latency'.
- required: false
- schema:
- type: string
- nullable: true
- - name: filter
- in: query
- description: >-
- JSON string containing an array of filter conditions. When provided,
- this takes precedence over query parameter filters (userId, name,
- sessionId, tags, version, release, environment, fromTimestamp,
- toTimestamp).
-
-
- ## Filter Structure
-
- Each filter condition has the following structure:
-
- ```json
-
- [
- {
- "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "booleanObject", "boolean", "null"
- "column": string, // Required. Column to filter on (see available columns below)
- "operator": string, // Required. Operator based on type:
- // - datetime: ">", "<", ">=", "<="
- // - string: "=", "contains", "does not contain", "starts with", "ends with"
- // - stringOptions: "any of", "none of"
- // - categoryOptions: "any of", "none of"
- // - arrayOptions: "any of", "none of", "all of"
- // - number: "=", ">", "<", ">=", "<="
- // - stringObject: "=", "contains", "does not contain", "starts with", "ends with", "is set", "is not set"
- // - numberObject: "=", ">", "<", ">=", "<="
- // - booleanObject: "=", "<>"
- // - boolean: "=", "<>"
- // - null: "is null", "is not null"
- "value": any, // Required (except for null type). Value to compare against. Type depends on filter type
- "key": string // Required only for stringObject, numberObject, booleanObject, and categoryOptions types when filtering on nested fields like metadata or score names
- }
- ]
-
- ```
-
-
- ## Available Columns
-
-
- ### Core Trace Fields
-
- - `id` (string) - Trace ID
-
- - `name` (string) - Trace name
-
- - `timestamp` (datetime) - Trace timestamp
-
- - `userId` (string) - User ID
-
- - `sessionId` (string) - Session ID
-
- - `environment` (string) - Environment tag
-
- - `version` (string) - Version tag
-
- - `release` (string) - Release tag
-
- - `tags` (arrayOptions) - Array of tags
-
- - `bookmarked` (boolean) - Bookmark status
-
-
- ### Structured Data
-
- - `metadata` (stringObject/numberObject/categoryOptions) - Metadata
- key-value pairs. Use `key` parameter to filter on specific metadata
- keys.
-
-
- ### Aggregated Metrics (from observations)
-
- These metrics are aggregated from all observations within the trace:
-
- - `latency` (number) - Latency in seconds (time from first
- observation start to last observation end)
-
- - `inputTokens` (number) - Total input tokens across all
- observations
-
- - `outputTokens` (number) - Total output tokens across all
- observations
-
- - `totalTokens` (number) - Total tokens (alias: `tokens`)
-
- - `inputCost` (number) - Total input cost in USD
-
- - `outputCost` (number) - Total output cost in USD
-
- - `totalCost` (number) - Total cost in USD
-
-
- ### Observation Level Aggregations
-
- These fields aggregate observation levels within the trace:
-
- - `level` (string) - Highest severity level (ERROR > WARNING >
- DEFAULT > DEBUG)
-
- - `warningCount` (number) - Count of WARNING level observations
-
- - `errorCount` (number) - Count of ERROR level observations
-
- - `defaultCount` (number) - Count of DEFAULT level observations
-
- - `debugCount` (number) - Count of DEBUG level observations
-
-
- ### Scores (requires join with scores table)
-
- - `scores_avg` (number) - Average of numeric scores (alias:
- `scores`)
-
- - `score_categories` (categoryOptions) - Categorical score values
-
- - `score_booleans` (booleanObject) - Boolean score values. Use `key`
- for the score name and a boolean `value`, e.g. `{"type":
- "booleanObject", "column": "score_booleans", "key": "is_correct",
- "operator": "=", "value": true}`. The `<>` operator also matches
- traces without a score of that name.
-
-
- ## Filter Examples
-
- ```json
-
- [
- {
- "type": "datetime",
- "column": "timestamp",
- "operator": ">=",
- "value": "2024-01-01T00:00:00Z"
- },
- {
- "type": "string",
- "column": "userId",
- "operator": "=",
- "value": "user-123"
- },
- {
- "type": "number",
- "column": "totalCost",
- "operator": ">=",
- "value": 0.01
- },
- {
- "type": "arrayOptions",
- "column": "tags",
- "operator": "all of",
- "value": ["production", "critical"]
- },
- {
- "type": "stringObject",
- "column": "metadata",
- "key": "customer_tier",
- "operator": "=",
- "value": "enterprise"
- }
- ]
-
- ```
-
-
- ## Performance Notes
-
- - Filtering on `userId`, `sessionId`, or `metadata` may enable skip
- indexes for better query performance
-
- - Score filters require a join with the scores table and may impact
- query performance
- required: false
- schema:
- type: string
- nullable: true
responses:
'200':
description: ''
content:
application/json:
schema:
- $ref: '#/components/schemas/Traces'
+ $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_delete
tags:
- - Trace
- parameters: []
+ - UnstableDashboards
+ parameters:
+ - name: dashboardId
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'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_addPlacement
tags:
- - UnstableDashboardWidgets
+ - UnstableDashboards
parameters:
- - name: page
- in: query
- description: 1-based page number. Defaults to `1`.
- required: false
- schema:
- type: integer
- nullable: true
- - name: limit
- in: query
- description: Maximum number of items per page. Defaults to `50`.
- required: false
+ - name: dashboardId
+ in: path
+ required: true
schema:
- type: integer
- nullable: true
+ type: string
responses:
'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_updatePlacement
tags:
- - UnstableDashboardWidgets
- parameters: []
+ - 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/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_deletePlacement
tags:
- - UnstableDashboardWidgets
+ - UnstableDashboards
parameters:
- - name: widgetId
+ - name: dashboardId
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: placementId
in: path
required: true
schema:
@@ -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_list
tags:
- - UnstableDashboardWidgets
+ - UnstableSkills
parameters:
- - 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: false
schema:
type: string
+ format: date-time
+ nullable: true
responses:
'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_createVersion
tags:
- - 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_get
tags:
- - UnstableDashboards
+ - UnstableSkills
parameters:
- - name: page
+ - name: skillName
+ in: path
+ required: true
+ schema:
+ type: string
+ - name: version
in: query
- description: 1-based page number. Defaults to `1`.
required: false
schema:
type: integer
nullable: true
- - name: limit
+ - name: label
in: query
- description: Maximum number of items per page. Defaults to `50`.
required: false
schema:
- type: integer
+ type: string
nullable: true
responses:
'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_update
tags:
- - UnstableDashboards
- parameters: []
+ - UnstableSkills
+ parameters:
+ - name: skillName
+ in: path
+ required: true
+ schema:
+ type: string
responses:
'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_0
requestBody:
required: true
content:
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_getFileContents
tags:
- - UnstableDashboards
+ - UnstableSkills
parameters:
- - 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: true
schema:
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_setLabels
tags:
- - UnstableDashboards
+ - UnstableSkills
parameters:
- - name: dashboardId
+ - 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/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_0
requestBody:
required: true
content:
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_deleteVersion
tags:
- - UnstableDashboards
+ - UnstableSkills
parameters:
- - name: dashboardId
+ - name: skillName
in: path
required: true
schema:
type: string
- responses:
- '200':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstableDeleteDashboardResponse'
- '400':
- description: ''
- content:
- application/json:
- schema: {}
- '401':
- description: ''
- content:
- application/json:
- schema: {}
- '403':
- description: ''
- content:
- application/json:
- schema: {}
- '404':
- description: ''
- content:
- application/json:
- schema: {}
- '405':
- description: ''
- content:
- application/json:
- schema: {}
- '429':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- '500':
- description: ''
- content:
- application/json:
- schema:
- $ref: '#/components/schemas/unstablePublicApiError'
- security: *ref_0
- /api/public/unstable/dashboards/{dashboardId}/placements:
- post:
- description: |-
- Add a placement to a dashboard grid (see `DashboardPlacement` for
- grid semantics).
-
- `id` and the position fields are optional: when omitted, the
- placement gets a server-generated id and is appended below all
- existing tiles as a 6x6 tile. Returns the created placement.
-
- The referenced widget must exist in the same project or be a
- Langfuse-managed widget. The API returns `409` if a placement with
- the same `id` already exists on the dashboard.
- operationId: unstable_dashboards_addPlacement
- tags:
- - UnstableDashboards
- parameters:
- - name: dashboardId
+ - name: skillVersion
in: path
required: true
schema:
- type: string
+ type: integer
responses:
'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: true
createdAt:
type: string
format: date-time
@@ -9636,1432 +7373,934 @@ components:
format: date-time
required:
- id
- - projectId
- - type
- - bucketName
- - endpoint
- - region
- - accessKeyId
- - prefix
- - exportFrequency
- - enabled
- - forcePathStyle
- - fileType
- - exportMode
- - exportStartDate
- - compressed
- - exportSource
- - exportFieldGroups
- - nextSyncAt
- - lastSyncAt
- - lastError
- - lastErrorAt
+ - 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: AnnotationQueueItem
type: object
properties:
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: string
format: date-time
nullable: 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: string
format: date-time
- nullable: true
- description: When the last error occurred. Cleared on successful export.
required:
- id
- - projectId
- - syncStatus
- - enabled
- - lastSyncAt
- - nextSyncAt
- - lastError
- - lastErrorAt
- BlobStorageIntegrationDeletionResponse:
- title: BlobStorageIntegrationDeletionResponse
- type: object
- properties:
- message:
- type: string
- required:
- - message
- CreateCommentRequest:
- title: CreateCommentRequest
- type: object
- properties:
- projectId:
- type: string
- description: The id of the project to attach the comment to.
- objectType:
- type: string
- description: >-
- The type of the object to attach the comment to (trace, observation,
- session, prompt).
- objectId:
- type: string
- description: >-
- The id of the object to attach the comment to. If this does not
- reference a valid existing object, an error will be thrown.
- content:
- type: string
- description: >-
- The content of the comment. May include markdown. Currently limited
- to 5000 characters.
- authorUserId:
- type: string
- nullable: true
- description: >-
- The id of the user who created the comment. Must be a member of the
- organization that owns the project, otherwise an error will be
- thrown.
- required:
- - projectId
- - objectType
+ - 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: PaginatedAnnotationQueues
type: object
properties:
data:
type: array
items:
- $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: CreateAnnotationQueueRequest
type: object
properties:
- id:
- type: string
- description: The unique identifier of a trace
- timestamp:
- type: string
- format: date-time
- description: The timestamp when the trace was created
name:
type: string
- nullable: true
- description: The name of the trace
- input:
- nullable: true
- description: The input data of the trace. Can be any JSON.
- output:
- nullable: true
- description: The output data of the trace. Can be any JSON.
- sessionId:
- type: string
- nullable: true
- description: The session identifier associated with the trace
- release:
- type: string
- nullable: true
- description: The release version of the application when the trace was created
- version:
- type: string
- nullable: true
- description: The version of the trace
- userId:
+ description:
type: string
nullable: 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: array
items:
type: string
- description: The tags associated with the trace.
- public:
- type: boolean
- description: Public traces are accessible via url without login
- environment:
- type: string
- description: >-
- The environment from which this trace originated. Can be any
- lowercase alphanumeric string with hyphens and underscores that does
- not start with 'langfuse'.
required:
- - id
- - timestamp
- name
- - sessionId
- - release
- - version
- - userId
- - tags
- - public
- - environment
- TraceWithDetails:
- title: TraceWithDetails
+ - scoreConfigIds
+ CreateAnnotationQueueItemRequest:
+ title: CreateAnnotationQueueItemRequest
type: object
properties:
- 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: string
required:
- - htmlPath
- allOf:
- - $ref: '#/components/schemas/Trace'
- TraceWithFullDetails:
- title: TraceWithFullDetails
+ - success
+ - message
+ AnnotationQueueAssignmentRequest:
+ title: AnnotationQueueAssignmentRequest
type: object
properties:
- 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: true
required:
- - htmlPath
- - observations
- - scores
- allOf:
- - $ref: '#/components/schemas/Trace'
- Session:
- title: Session
+ - userId
+ DeleteAnnotationQueueAssignmentResponse:
+ title: DeleteAnnotationQueueAssignmentResponse
type: object
properties:
- id:
+ success:
+ type: boolean
+ required:
+ - success
+ CreateAnnotationQueueAssignmentResponse:
+ title: CreateAnnotationQueueAssignmentResponse
+ type: object
+ properties:
+ userId:
type: string
- createdAt:
+ queueId:
type: string
- format: date-time
projectId:
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: CreateBlobStorageIntegrationRequest
type: object
properties:
- 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 integration
type:
+ $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: string
nullable: 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: string
nullable: true
- description: The parent observation ID
- promptId:
+ description: Access key ID for authentication. Not used for GOOGLE_CLOUD_STORAGE.
+ secretAccessKey:
type: string
nullable: true
- description: The prompt ID associated with the observation
- usageDetails:
- type: object
- additionalProperties:
- type: integer
description: >-
- The usage details of the observation. Key is the name of the usage
- metric, value is the number of units consumed. The total key is the
- sum of all (non-total) usage metrics or the total value ingested.
- costDetails:
- type: object
- additionalProperties:
- type: number
- format: double
- description: >-
- The cost details of the observation. Key is the name of the cost
- metric, value is the cost in USD. The total key is the sum of all
- (non-total) cost metrics or the total value ingested.
- environment:
- type: string
- description: >-
- The environment from which this observation originated. Can be any
- lowercase alphanumeric string with hyphens and underscores that does
- not start with 'langfuse'.
- required:
- - id
- - traceId
- - type
- - name
- - startTime
- - endTime
- - completionStartTime
- - model
- - modelParameters
- - input
- - version
- - 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: string
nullable: true
- description: The name of the prompt associated with the observation
- promptVersion:
- type: integer
- nullable: true
- description: The version of the prompt associated with the observation
- modelId:
+ 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-time
nullable: true
description: >-
- (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: boolean
nullable: true
description: >-
- (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: true
description: >-
- (Deprecated. Use usageDetails and costDetails instead.) The
- calculated total cost in USD
- latency:
- type: number
- format: double
- nullable: true
- description: The latency in seconds.
- timeToFirstToken:
- type: number
- format: double
+ 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: BlobStorageIntegrationResponse
type: object
- description: >-
- An observation from the v2 API with field-group-based selection.
-
- Core fields are always present. Other fields are included only when
- their field group is requested.
- properties:
- id:
- type: string
- description: The unique identifier of the observation
- traceId:
- type: string
- nullable: true
- description: The trace ID associated with the observation
- startTime:
- type: string
- format: date-time
- description: The start time of the observation
- endTime:
+ properties:
+ id:
type: string
- format: date-time
- nullable: true
- description: The end time of the observation
projectId:
type: string
- description: The project ID this observation belongs to
- parentObservationId:
- type: string
- nullable: true
- description: >-
- The physical parent observation ID, if present.
-
- Observations marked as app roots by the SDK may retain a non-null
- parent ID.
type:
+ $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: string
nullable: 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: string
nullable: 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: string
format: date-time
nullable: true
- description: The last update timestamp of the observation
- input:
- nullable: true
- description: The input data of the observation
- output:
- nullable: true
- description: The output data of the observation
- metadata:
- type: object
- additionalProperties: true
- nullable: true
- description: Additional metadata of the observation
- model:
- type: string
- nullable: true
- description: The model name as provided by the user
- internalModelId:
- type: string
- nullable: true
- description: The internal model ID matched by Langfuse
- modelParameters:
- nullable: true
- description: The parameters of the model used for the observation
- usageDetails:
- type: object
- additionalProperties:
- type: integer
- nullable: true
- description: >-
- The usage details of the observation. Key is the usage metric name,
- value is the number of units consumed.
- costDetails:
- type: object
- additionalProperties:
- type: number
- format: double
- nullable: true
- description: >-
- The cost details of the observation. Key is the cost metric name,
- value is the cost in USD.
- totalCost:
- type: number
- format: double
- nullable: true
- description: The total cost of the observation in USD
- usagePricingTierName:
- type: string
+ compressed:
+ type: boolean
+ exportSource:
+ $ref: '#/components/schemas/BlobStorageExportSource'
+ exportFieldGroups:
+ type: array
+ items:
+ $ref: '#/components/schemas/BlobStorageExportFieldGroup'
nullable: true
description: >-
- The name of the pricing tier applied to this observation's usage
- costs
- promptId:
- type: string
- nullable: true
- description: The prompt ID associated with the observation
- promptName:
- type: string
- nullable: true
- description: The prompt name associated with the observation
- promptVersion:
- type: integer
- nullable: true
- description: The prompt version associated with the observation
- latency:
- type: number
- format: double
- nullable: true
- description: The latency in seconds
- timeToFirstToken:
- type: number
- format: double
- nullable: true
- description: The time to first token in seconds
- modelId:
+ 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
- description: >-
- The matched model ID. Null when the `model` field group is not
- requested.
- inputPrice:
+ lastSyncAt:
type: string
+ format: date-time
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:
+ lastError:
type: string
nullable: true
- description: >-
- The output token price (USD per unit) from the matched model,
- serialized as a decimal string (e.g. "0.0001"). Null when the
- `model` field group is not requested.
- totalPrice:
+ lastErrorAt:
type: string
+ format: date-time
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:
+ 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-time
required:
- id
- - traceId
- - startTime
- - endTime
- projectId
- - parentObservationId
- type
- - modelId
- - inputPrice
- - outputPrice
- - totalPrice
- Usage:
- title: Usage
- type: object
- description: >-
- (Deprecated. Use usageDetails and costDetails instead.) Standard
- interface for usage and cost
- properties:
- input:
- type: integer
- description: Number of input units (e.g. tokens)
- output:
- type: integer
- description: Number of output units (e.g. tokens)
- total:
- type: integer
- description: Defaults to input+output if not set
- unit:
- type: string
- nullable: true
- description: Unit of measurement
- inputCost:
- type: number
- format: double
- nullable: true
- description: USD input cost
- outputCost:
- type: number
- format: double
- nullable: true
- description: USD output cost
- totalCost:
- type: number
- format: double
- nullable: true
- description: USD total cost, defaults to input+output
+ - 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: BlobStorageIntegrationStatusResponse
type: object
- description: Configuration for a score
properties:
id:
type: string
- name:
+ projectId:
type: string
- createdAt:
+ syncStatus:
+ $ref: '#/components/schemas/BlobStorageSyncStatus'
+ enabled:
+ type: boolean
+ lastSyncAt:
type: string
format: 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: string
format: date-time
- projectId:
- type: string
- dataType:
- $ref: '#/components/schemas/ScoreConfigDataType'
- isArchived:
- type: boolean
- description: Whether the score config is archived. Defaults to false
- minValue:
- type: number
- format: double
nullable: true
- description: >-
- Sets minimum value for numerical scores. If not set, the minimum
- value defaults to -∞
- maxValue:
- type: number
- format: double
+ description: When the next export is scheduled. Null if no sync has occurred yet.
+ lastError:
+ type: string
nullable: true
description: >-
- Sets maximum value for numerical scores. If not set, the maximum
- value defaults to +∞
- categories:
- type: array
- items:
- $ref: '#/components/schemas/ConfigCategory'
- nullable: true
- description: Configures custom categories for categorical scores
- description:
+ Raw error message from the storage provider (S3/Azure/GCS) if the
+ last export failed. Cleared on successful export.
+ lastErrorAt:
type: string
+ format: date-time
nullable: true
- description: 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: BlobStorageIntegrationDeletionResponse
type: object
properties:
- value:
- type: number
- format: double
- label:
+ message:
type: string
required:
- - value
- - label
- BaseScoreV1:
- title: BaseScoreV1
+ - message
+ CreateCommentRequest:
+ title: CreateCommentRequest
type: object
properties:
- id:
- type: string
- traceId:
- type: string
- name:
- type: string
- source:
- $ref: '#/components/schemas/ScoreSource'
- observationId:
- type: string
- nullable: true
- description: The observation ID associated with the score
- timestamp:
- type: string
- format: date-time
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- authorUserId:
+ 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: 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:
+ 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: true
description: >-
- 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: true
description: >-
- 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: CreateCommentResponse
type: object
properties:
- value:
- type: number
- format: double
- description: The numeric value of the score
+ id:
+ type: string
+ description: The id of the created object in Langfuse
required:
- - value
- allOf:
- - $ref: '#/components/schemas/BaseScoreV1'
- BooleanScoreV1:
- title: BooleanScoreV1
+ - id
+ GetCommentsResponse:
+ title: GetCommentsResponse
type: object
properties:
- value:
- type: number
- format: double
- description: >-
- The numeric value of the score. Equals 1 for "True" and 0 for "False"
- stringValue:
- type: string
- description: >-
- The string representation of the score value. Is inferred from the
- numeric value and equals "True" or "False"
+ 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: Deprecation
type: 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: string
description: >-
- 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: true
description: >-
- The string representation of the score value. If no config is
- linked, can be any string. Otherwise, must map to a config category
- required:
- - value
- - stringValue
- allOf:
- - $ref: '#/components/schemas/BaseScoreV1'
- TextScoreV1:
- title: TextScoreV1
- type: object
- properties:
- stringValue:
+ 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: ObservationV2
type: object
+ description: >-
+ An observation from the v2 API with field-group-based selection.
+
+ Core fields are always present. Other fields are included only when
+ their field group is requested.
properties:
id:
type: string
+ description: The unique identifier of the observation
traceId:
type: string
nullable: true
- description: The trace ID associated with the 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-time
nullable: 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: string
nullable: 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: boolean
nullable: 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: string
format: date-time
+ nullable: true
+ description: The completion start time of the observation
createdAt:
type: string
format: date-time
+ nullable: true
+ description: The creation timestamp of the observation
updatedAt:
type: string
format: date-time
- authorUserId:
- type: string
nullable: 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 observation
metadata:
type: object
additionalProperties: true
nullable: true
- description: Metadata associated with the score
- configId:
+ description: Additional metadata of the observation
+ model:
type: string
nullable: true
- description: >-
- Reference a score config on a score. When set, config and score name
- must be equal and value must comply to optionally defined numerical
- range
- queueId:
+ 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 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: true
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:
+ The cost details of the observation. Key is the cost metric name,
+ value is the cost in USD.
+ totalCost:
type: number
format: 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: true
description: >-
- The string representation of the score value. If no config is
- linked, can be any string. Otherwise, must map to a config category
- required:
- - value
- - stringValue
- allOf:
- - $ref: '#/components/schemas/BaseScore'
- CorrectionScore:
- title: CorrectionScore
- type: object
- properties:
- value:
- type: number
- format: double
- description: The numeric value of the score. Always 0 for correction scores.
- stringValue:
+ 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: number
format: double
- title: DoubleNumber
- - type: string
- title: String
- description: >-
- The value of the score. Must be passed as string for categorical and
- text scores, and numeric for boolean and numeric scores
- Comment:
- title: Comment
- type: object
- properties:
- id:
- type: string
- projectId:
+ 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: string
nullable: true
- description: The user ID of the comment author
+ description: The release version of the parent trace
required:
- id
+ - traceId
+ - startTime
+ - endTime
- projectId
- - createdAt
- - updatedAt
- - objectType
- - objectId
- - content
- Dataset:
- title: Dataset
+ - 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:
- 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: string
nullable: 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: double
nullable: true
- description: JSON Schema for validating dataset item inputs
- expectedOutputSchema:
- type: object
- additionalProperties: true
+ description: USD input cost
+ outputCost:
+ type: number
+ format: double
nullable: true
- description: JSON Schema for validating dataset item expected outputs
- projectId:
- type: string
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
+ description: USD output cost
+ totalCost:
+ type: number
+ format: double
+ nullable: true
+ description: USD total cost, defaults to input+output
required:
- - id
- - name
- - description
- - metadata
- - inputSchema
- - expectedOutputSchema
- - projectId
- - createdAt
- - updatedAt
- DatasetItem:
- title: DatasetItem
+ - input
+ - output
+ - total
+ - unit
+ ScoreConfig:
+ title: ScoreConfig
type: object
+ description: Configuration for a score
properties:
id:
type: string
- status:
- $ref: '#/components/schemas/DatasetStatus'
- input:
- description: Input data for the dataset item
- expectedOutput:
- description: Expected output for the dataset item
- metadata:
- description: Metadata associated with the dataset item
- sourceTraceId:
- type: string
- nullable: true
- description: The trace ID that sourced this dataset item
- sourceObservationId:
- type: string
- nullable: true
- description: The observation ID that sourced this dataset item
- datasetId:
- type: string
- datasetName:
+ name:
type: string
createdAt:
type: string
@@ -11069,2280 +8308,1794 @@ components:
updatedAt:
type: string
format: 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: array
items:
- $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 config
required:
- 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: ConfigCategory
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:
+ value:
+ type: number
+ format: double
+ label:
type: string
- description: The expiry date and time of the download URL
required:
- - mediaId
- - contentType
- - contentLength
- - url
- - urlExpiry
- DatasetRunItem:
- title: DatasetRunItem
+ - value
+ - label
+ BaseScore:
+ title: BaseScore
type: object
properties:
id:
type: string
- datasetRunId:
- type: string
- datasetRunName:
- type: string
- datasetItemId:
- type: string
traceId:
type: string
- observationId:
- type: string
nullable: true
- description: The observation ID associated with this run item
- createdAt:
- type: string
- format: date-time
- updatedAt:
- type: string
- format: date-time
- required:
- - id
- - datasetRunId
- - datasetRunName
- - datasetItemId
- - traceId
- - observationId
- - createdAt
- - updatedAt
- DatasetRun:
- title: DatasetRun
- type: object
- properties:
- id:
+ 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: string
nullable: 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-time
createdAt:
type: string
format: date-time
- description: The date and time when the dataset run was created
updatedAt:
type: string
format: date-time
- description: The date and time when the dataset run was last updated
- required:
- - id
- - name
- - description
- - metadata
- - datasetId
- - datasetName
- - createdAt
- - updatedAt
- DatasetRunWithItems:
- title: DatasetRunWithItems
- type: object
- properties:
- datasetRunItems:
- type: array
- items:
- $ref: '#/components/schemas/DatasetRunItem'
- _deprecation:
- $ref: '#/components/schemas/Deprecation'
- nullable: true
- required:
- - datasetRunItems
- allOf:
- - $ref: '#/components/schemas/DatasetRun'
- Model:
- title: Model
- type: object
- description: >-
- Model definition used for transforming usage into USD cost and/or
- tokenization.
-
-
- Models can have either simple flat pricing or tiered pricing:
-
- - Flat pricing: Single price per usage type (legacy, but still
- supported)
-
- - Tiered pricing: Multiple pricing tiers with conditional matching based
- on usage patterns or observation attributes
-
-
- The pricing tiers approach is recommended for models with usage-based
- pricing variations.
-
- When using tiered pricing, the flat price fields (inputPrice,
- outputPrice, prices) are populated
-
- from the default tier for backward compatibility.
- properties:
- id:
- type: string
- modelName:
- type: string
- description: >-
- Name of the model definition. If multiple with the same name exist,
- they are applied in the following order: (1) custom over built-in,
- (2) newest according to startTime where
- model.startTime<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: string
nullable: 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: true
nullable: true
- description: Deprecated. See 'prices' instead. Price (USD) per output unit
- totalPrice:
- type: number
- format: double
+ description: Metadata associated with the score
+ configId:
+ type: string
nullable: true
description: >-
- 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: string
nullable: true
description: >-
- Optional. Tokenizer to be applied to observations which match to
- this model. See docs for more details.
- tokenizerConfig:
- description: >-
- Optional. Configuration for the selected tokenizer. Needs to be
- JSON. See docs for more details.
- isLangfuseManaged:
- type: boolean
- createdAt:
+ 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: NumericScore
type: object
properties:
- price:
+ value:
type: number
format: double
+ description: The numeric value of the score
required:
- - price
- PricingTierCondition:
- title: PricingTierCondition
- oneOf:
- - $ref: '#/components/schemas/PricingTierUsageCondition'
- - $ref: '#/components/schemas/PricingTierAttributeCondition'
- description: >-
- Condition for matching a pricing tier against usage details or
- observation attributes.
-
-
- Usage-detail conditions treat usageDetailPattern as a regex, sum all
- matching usage values, and compare the sum to the numeric value.
- Model-parameter and metadata conditions match an exact top-level key
- against one or more string values.
- PricingTierUsageCondition:
- title: PricingTierUsageCondition
+ - value
+ allOf:
+ - $ref: '#/components/schemas/BaseScore'
+ BooleanScore:
+ title: BooleanScore
type: 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: number
format: double
- description: Numeric threshold for the summed matching usage values.
- caseSensitive:
- type: boolean
- description: Whether the usage-detail regex is case-sensitive.
- required:
- - usageDetailPattern
- - operator
- - value
- - caseSensitive
- PricingTierAttributeCondition:
- title: PricingTierAttributeCondition
- type: object
+ description: The numeric value of the score. Always 0 for correction scores.
+ stringValue:
+ type: string
+ description: The string representation of the correction content
+ required:
+ - value
+ - stringValue
+ allOf:
+ - $ref: '#/components/schemas/BaseScore'
+ TextScore:
+ title: TextScore
+ type: object
+ properties:
+ stringValue:
+ type: string
+ description: The text content of the score (1-500 characters)
+ required:
+ - stringValue
+ allOf:
+ - $ref: '#/components/schemas/BaseScore'
+ Score:
+ title: Score
+ oneOf:
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ dataType:
+ type: string
+ enum:
+ - NUMERIC
+ - $ref: '#/components/schemas/NumericScore'
+ required:
+ - dataType
+ title: NumericScore
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ dataType:
+ type: string
+ enum:
+ - CATEGORICAL
+ - $ref: '#/components/schemas/CategoricalScore'
+ required:
+ - dataType
+ title: CategoricalScore
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ dataType:
+ type: string
+ enum:
+ - BOOLEAN
+ - $ref: '#/components/schemas/BooleanScore'
+ required:
+ - dataType
+ title: BooleanScore
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ dataType:
+ type: string
+ enum:
+ - CORRECTION
+ - $ref: '#/components/schemas/CorrectionScore'
+ required:
+ - dataType
+ title: CorrectionScore
+ - type: object
+ allOf:
+ - type: object
+ properties:
+ dataType:
+ type: string
+ enum:
+ - TEXT
+ - $ref: '#/components/schemas/TextScore'
+ required:
+ - dataType
+ title: TextScore
+ properties:
+ _deprecation:
+ $ref: '#/components/schemas/Deprecation'
+ nullable: true
+ CreateScoreValue:
+ title: CreateScoreValue
+ oneOf:
+ - type: number
+ format: double
+ title: DoubleNumber
+ - type: string
+ title: String
description: >-
- 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: object
properties:
- 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 author
required:
- - source
- - key
- - operator
- - values
- PricingTierAttributeSource:
- title: PricingTierAttributeSource
- type: string
- enum:
- - model_parameters
- - metadata
- PricingTierConditionInput:
- title: PricingTierConditionInput
- oneOf:
- - $ref: '#/components/schemas/PricingTierUsageConditionInput'
- - $ref: '#/components/schemas/PricingTierAttributeCondition'
- description: Condition input for matching a pricing tier.
- PricingTierUsageConditionInput:
- title: PricingTierUsageConditionInput
+ - id
+ - projectId
+ - createdAt
+ - updatedAt
+ - objectType
+ - objectId
+ - content
+ Dataset:
+ title: Dataset
type: 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: boolean
nullable: 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-time
required:
- - usageDetailPattern
- - operator
- - value
- PricingTier:
- title: PricingTier
+ - id
+ - name
+ - description
+ - metadata
+ - inputSchema
+ - expectedOutputSchema
+ - projectId
+ - createdAt
+ - updatedAt
+ DatasetItem:
+ title: DatasetItem
type: object
- description: >-
- Pricing tier definition with conditional pricing based on usage
- thresholds or observation attributes.
-
-
- Pricing tiers enable accurate cost tracking for LLM providers that
- charge different rates based on usage patterns or request attributes.
-
- For example, some providers charge higher rates when context size
- exceeds certain thresholds or when an accelerated service tier is
- selected.
-
-
- How tier matching works:
-
- 1. Tiers are evaluated in ascending priority order (priority 1 before
- priority 2, etc.)
-
- 2. The first tier where ALL conditions match is selected
-
- 3. If no conditional tiers match, the default tier is used as a fallback
-
- 4. The default tier has priority 0 and no conditions
-
-
- Why priorities matter:
-
- - Lower priority numbers are evaluated first, allowing you to define
- specific cases before general ones
-
- - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
- "medium usage" (>100K tokens), Priority 0 for default
-
- - Without proper ordering, a less specific condition might match before
- a more specific one
-
-
- Every model must have exactly one default tier to ensure cost
- calculation always succeeds.
properties:
id:
type: string
- description: Unique identifier for the pricing tier
- name:
+ 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: array
items:
- $ref: '#/components/schemas/PricingTierCondition'
- description: >-
- Array of conditions that must ALL be met for this tier to match (AND
- logic).
-
-
- The default tier must have an empty conditions array. Conditional
- tiers should have one or more conditions
-
- that define when this tier's pricing applies.
-
-
- Multiple conditions enable complex matching scenarios (e.g., "high
- input tokens AND low output tokens").
- prices:
- type: object
- additionalProperties:
- type: number
- format: double
+ $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: Model
type: object
description: >-
- 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: 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
+ Name of the model definition. If multiple with the same name exist,
+ they are applied in the following order: (1) custom over built-in,
+ (2) newest according to startTime where
+ model.startTime<observation.startTime
+ matchPattern:
+ type: string
+ description: >-
+ Regex pattern which matches this model definition to
+ generation.model. Useful in case of fine-tuned models. If you want
+ to exact match, use `(?i)^modelname$`
+ startDate:
+ type: string
+ format: date-time
+ nullable: true
+ description: Apply only to generations which are newer than this ISO date.
+ unit:
+ $ref: '#/components/schemas/ModelUsageUnit'
+ nullable: true
+ description: Unit used by this model.
+ inputPrice:
+ type: number
+ format: double
+ nullable: true
+ description: Deprecated. See 'prices' instead. Price (USD) per input unit
+ outputPrice:
+ type: number
+ format: double
+ nullable: true
+ description: Deprecated. See 'prices' instead. Price (USD) per output unit
+ totalPrice:
+ type: number
+ format: double
nullable: true
description: >-
- 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: true
description: >-
- 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: array
items:
- $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: PricingTierCondition
oneOf:
- - type: string
- nullable: true
- title: String
- - type: integer
- nullable: true
- title: Integer
- - type: number
- format: float
- nullable: true
- title: FloatNumber
- - type: boolean
- nullable: true
- title: Boolean
- - type: array
- items:
- type: string
- nullable: true
- title: Array
- CommentObjectType:
- title: CommentObjectType
- type: string
- enum:
- - TRACE
- - OBSERVATION
- - SESSION
- - PROMPT
- DatasetStatus:
- title: DatasetStatus
- type: string
- enum:
- - ACTIVE
- - ARCHIVED
- ScoreSource:
- title: ScoreSource
- type: string
- enum:
- - ANNOTATION
- - API
- - EVAL
- ScoreConfigDataType:
- title: ScoreConfigDataType
- type: string
- enum:
- - NUMERIC
- - BOOLEAN
- - CATEGORICAL
- - TEXT
- ScoreDataType:
- title: ScoreDataType
- type: string
- enum:
- - NUMERIC
- - BOOLEAN
- - CATEGORICAL
- - CORRECTION
- - TEXT
- DeleteDatasetItemResponse:
- title: DeleteDatasetItemResponse
+ - $ref: '#/components/schemas/PricingTierUsageCondition'
+ - $ref: '#/components/schemas/PricingTierAttributeCondition'
+ description: >-
+ Condition for matching a pricing tier against usage details or
+ observation attributes.
+
+
+ Usage-detail conditions treat usageDetailPattern as a regex, sum all
+ matching usage values, and compare the sum to the numeric value.
+ Model-parameter and metadata conditions match an exact top-level key
+ against one or more string values.
+ PricingTierUsageCondition:
+ title: PricingTierUsageCondition
type: object
+ description: Condition that sums usage details whose keys match a regex.
properties:
- 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: PricingTierAttributeCondition
type: 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: PricingTierUsageConditionInput
type: 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: PricingTier
type: object
+ description: >-
+ Pricing tier definition with conditional pricing based on usage
+ thresholds or observation attributes.
+
+
+ Pricing tiers enable accurate cost tracking for LLM providers that
+ charge different rates based on usage patterns or request attributes.
+
+ For example, some providers charge higher rates when context size
+ exceeds certain thresholds or when an accelerated service tier is
+ selected.
+
+
+ How tier matching works:
+
+ 1. Tiers are evaluated in ascending priority order (priority 1 before
+ priority 2, etc.)
+
+ 2. The first tier where ALL conditions match is selected
+
+ 3. If no conditional tiers match, the default tier is used as a fallback
+
+ 4. The default tier has priority 0 and no conditions
+
+
+ Why priorities matter:
+
+ - Lower priority numbers are evaluated first, allowing you to define
+ specific cases before general ones
+
+ - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for
+ "medium usage" (>100K tokens), Priority 0 for default
+
+ - Without proper ordering, a less specific condition might match before
+ a more specific one
+
+
+ Every model must have exactly one default tier to ensure cost
+ calculation always succeeds.
properties:
- 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: true
description: >-
- traceId should always be provided. For compatibility with older SDK
- versions it can also be inferred from the provided observationId.
- datasetVersion:
- type: string
- format: date-time
- nullable: true
+ Name of the pricing tier for display and identification purposes.
+
+
+ Examples: "Standard", "High Volume Tier", "Large Context", "Extended
+ Context Tier"
+ isDefault:
+ type: boolean
description: >-
- 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: integer
description: >-
- Optional timestamp to set the createdAt field of the dataset run
- item. If not provided or null, defaults to current timestamp.
- required:
- - runName
- - datasetItemId
- PaginatedDatasetRunItems:
- title: PaginatedDatasetRunItems
- type: object
- properties:
- data:
- type: array
- items:
- $ref: '#/components/schemas/DatasetRunItem'
- meta:
- $ref: '#/components/schemas/utilsMetaResponse'
- _deprecation:
- $ref: '#/components/schemas/Deprecation'
- nullable: true
- required:
- - data
- - meta
- PaginatedDatasets:
- title: PaginatedDatasets
- type: object
- properties:
- data:
+ Priority for tier matching evaluation. Lower numbers = higher
+ priority (evaluated first).
+
+
+ The default tier must always have priority 0. Conditional tiers
+ should have priority 1, 2, 3, etc.
+
+
+ Example ordering:
+
+ - Priority 0: Default tier (no conditions, always matches as
+ fallback)
+
+ - Priority 1: High usage tier (e.g., >200K tokens)
+
+ - Priority 2: Medium usage tier (e.g., >100K tokens)
+
+
+ This ensures more specific conditions are checked before general
+ ones.
+ conditions:
type: array
items:
- $ref: '#/components/schemas/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: double
description: >-
- 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: PricingTierInput
type: object
- properties:
- message:
- type: string
- required:
- - message
- EvaluatorType:
- title: EvaluatorType
- type: string
- enum:
- - llm_as_judge
- - code
- description: |-
- The evaluator type.
-
- The public API supports LLM-as-a-judge and code evaluators.
- CodeEvaluatorSourceCodeLanguage:
- title: CodeEvaluatorSourceCodeLanguage
- type: string
- enum:
- - PYTHON
- - TYPESCRIPT
- description: Code evaluator runtime language.
- PromptVariableMappingSource:
- title: PromptVariableMappingSource
- type: string
- enum:
- - input
- - output
- - metadata
- - tool_calls
- - expected_output
- - experiment_item_metadata
description: >-
- Source field used to populate a prompt variable.
+ 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: double
description: >-
- Optional instructions for deriving the reasoning returned with the
- score.
- scoreValueInstructions:
- type: string
- nullable: true
- description: Optional instructions for deriving the score value.
- PublicEvaluatorNumericScore:
- title: PublicEvaluatorNumericScore
- type: object
- properties:
- dataType:
- type: string
- const: NUMERIC
- description: Numeric score output.
- minValue:
- type: number
- format: double
- nullable: true
- description: Optional inclusive minimum value.
- maxValue:
- type: number
- format: double
- nullable: true
- description: Optional inclusive maximum value.
- required:
- - dataType
- allOf:
- - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
- PublicEvaluatorBooleanScore:
- title: PublicEvaluatorBooleanScore
- type: object
- properties:
- dataType:
- type: string
- const: BOOLEAN
- description: Boolean score output.
- required:
- - dataType
- allOf:
- - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
- PublicEvaluatorCategoricalScore:
- title: PublicEvaluatorCategoricalScore
- type: object
- properties:
- dataType:
- type: string
- const: CATEGORICAL
- description: Categorical score output.
- categories:
- type: array
- items:
- type: string
- description: Allowed category values. At least two unique values are required.
- shouldAllowMultipleMatches:
- type: boolean
- description: Whether the evaluator may return more than one category.
- required:
- - dataType
- - categories
- - shouldAllowMultipleMatches
- allOf:
- - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
- PublicEvaluatorOutputDefinition:
- title: PublicEvaluatorOutputDefinition
- oneOf:
- - type: object
- allOf:
- - type: object
- properties:
- dataType:
- type: string
- enum:
- - NUMERIC
- - $ref: '#/components/schemas/PublicEvaluatorNumericScore'
- required:
- - dataType
- title: PublicEvaluatorNumericScore
- - type: object
- allOf:
- - type: object
- properties:
- dataType:
- type: string
- enum:
- - BOOLEAN
- - $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
- required:
- - dataType
- title: PublicEvaluatorBooleanScore
- - type: object
- allOf:
- - type: object
- properties:
- dataType:
- type: string
- enum:
- - CATEGORICAL
- - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
- required:
- - dataType
- title: PublicEvaluatorCategoricalScore
- description: >-
- Flat evaluator output definition returned by the public API.
+ 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: PricingTierOperator
type: string
enum:
- - '='
- - 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: ObservationLevel
type: string
enum:
- - '='
- - 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: CommentObjectType
type: string
enum:
- - '='
- - '>'
- - <
- - '>='
- - <=
- EvaluationRuleOptionsFilterOperator:
- title: EvaluationRuleOptionsFilterOperator
+ - TRACE
+ - OBSERVATION
+ - SESSION
+ - PROMPT
+ DatasetStatus:
+ title: DatasetStatus
type: string
enum:
- - any of
- - none of
- EvaluationRuleArrayOptionsFilterOperator:
- title: EvaluationRuleArrayOptionsFilterOperator
+ - ACTIVE
+ - ARCHIVED
+ ScoreSource:
+ title: ScoreSource
type: string
enum:
- - any of
- - none of
- - all of
- EvaluationRuleBooleanFilterOperator:
- title: EvaluationRuleBooleanFilterOperator
+ - ANNOTATION
+ - API
+ - EVAL
+ ScoreConfigDataType:
+ title: ScoreConfigDataType
type: string
enum:
- - '='
- - <>
- EvaluationRuleNullFilterOperator:
- title: EvaluationRuleNullFilterOperator
+ - NUMERIC
+ - BOOLEAN
+ - CATEGORICAL
+ - TEXT
+ ScoreDataType:
+ title: ScoreDataType
type: string
enum:
- - is null
- - is not null
- DateTimeEvaluationRuleFilter:
- title: DateTimeEvaluationRuleFilter
- type: object
- properties:
- column:
- type: string
- description: Column to filter on.
- operator:
- $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
- description: Comparison operator for datetime values.
- value:
- type: string
- format: date-time
- description: Datetime value to compare against.
- required:
- - column
- - operator
- - value
- StringEvaluationRuleFilter:
- title: StringEvaluationRuleFilter
- type: object
- properties:
- column:
- type: string
- description: Column to filter on.
- operator:
- $ref: '#/components/schemas/EvaluationRuleStringFilterOperator'
- value:
- type: string
- required:
- - column
- - operator
- - value
- NumberEvaluationRuleFilter:
- title: NumberEvaluationRuleFilter
+ - NUMERIC
+ - BOOLEAN
+ - CATEGORICAL
+ - CORRECTION
+ - TEXT
+ OpenAIUsage:
+ title: OpenAIUsage
type: 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: DeleteDatasetItemResponse
type: object
properties:
- 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 deletion
required:
- - column
- - operator
- - value
- ArrayOptionsEvaluationRuleFilter:
- title: ArrayOptionsEvaluationRuleFilter
+ - message
+ CreateDatasetItemRequest:
+ title: CreateDatasetItemRequest
type: object
properties:
- 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: true
description: >-
- Value to compare against. Ignored for `is set` / `is not set`; send
- `""`.
- required:
- - column
- - key
- - operator
- - value
- NumberObjectEvaluationRuleFilter:
- title: NumberObjectEvaluationRuleFilter
- type: object
- properties:
- column:
- type: string
- description: Object-valued column to filter on.
- key:
- type: string
- description: Key inside the object-valued column to filter on.
- operator:
- $ref: '#/components/schemas/EvaluationRuleNumberFilterOperator'
- value:
- type: number
- format: double
+ Dataset items are upserted on their id. Id needs to be unique
+ (project-level), cannot be reused across datasets, and must be at
+ most 255 characters.
+ status:
+ $ref: '#/components/schemas/DatasetStatus'
+ nullable: true
+ description: Defaults to ACTIVE for newly created items
required:
- - 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: array
items:
- type: string
+ $ref: '#/components/schemas/DatasetItem'
+ meta:
+ $ref: '#/components/schemas/utilsMetaResponse'
required:
- - column
- - key
- - operator
- - value
- BooleanEvaluationRuleFilter:
- title: BooleanEvaluationRuleFilter
+ - data
+ - meta
+ PaginatedDatasets:
+ title: PaginatedDatasets
type: object
properties:
- 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: CreateDatasetRequest
type: object
properties:
- 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: true
description: >-
- Required empty-string placeholder used by the runtime filter
- contract.
- required:
- - column
- - operator
- - value
- PromptVariableMappingInput:
- title: PromptVariableMappingInput
- type: object
- description: >-
- Connects one prompt variable to data from an observation or experiment.
-
-
- Manual mappings are used for `llm_as_judge` evaluators. `code`
- evaluators use a fixed runtime mapping managed by Langfuse.
-
-
- How to build a valid mapping list:
-
- 1. Create the evaluator or fetch it with `GET /evaluators/{id}`.
-
- 2. Read the evaluator `variables` array.
-
- 3. Add exactly one mapping object for each variable in that array.
-
- 4. Use the variable name exactly as returned, without braces such as
- `{{` or `}}`.
-
- 5. Choose the source field that should populate the variable.
-
-
- `jsonPath` is optional. Use it only when the selected source is a JSON
- object and you want to extract one nested field before inserting it into
- the evaluator prompt.
-
-
- Invalid, missing, or duplicate mappings return a validation error.
- Malformed JSONPath expressions are also rejected.
- properties:
- variable:
- type: string
+ JSON Schema for validating dataset item inputs. When set, all new
+ and existing dataset items will be validated against this schema.
+ expectedOutputSchema:
+ nullable: true
description: >-
- 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: EvaluatorOutputScoreType
type: string
enum:
- - trace
- - span
- - generation
- - event
- - agent
- - tool
- - chain
- - retriever
- - evaluator
- - embedding
- - guardrail
- - dataset_item
+ - NUMERIC
+ - BOOLEAN
+ - CATEGORICAL
description: >-
- **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: EvaluatorOutputDefinition
oneOf:
- type: object
allOf:
- type: object
properties:
- type:
- type: string
- enum:
- - datetime
- - $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'
- required:
- - type
- title: DateTimeEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - string
- - $ref: '#/components/schemas/StringEvaluationRuleFilter'
- required:
- - type
- title: StringEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - number
- - $ref: '#/components/schemas/NumberEvaluationRuleFilter'
- required:
- - type
- title: NumberEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - stringOptions
- - $ref: '#/components/schemas/StringOptionsEvaluationRuleFilter'
- required:
- - type
- title: StringOptionsEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - categoryOptions
- - $ref: '#/components/schemas/CategoryOptionsEvaluationRuleFilter'
- required:
- - type
- title: CategoryOptionsEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - arrayOptions
- - $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'
- required:
- - type
- title: ArrayOptionsEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - stringObject
- - $ref: '#/components/schemas/StringObjectEvaluationRuleFilter'
- required:
- - type
- title: StringObjectEvaluationRuleFilter
- - type: object
- allOf:
- - type: object
- properties:
- type:
+ dataType:
type: string
enum:
- - numberObject
- - $ref: '#/components/schemas/NumberObjectEvaluationRuleFilter'
+ - NUMERIC
+ - $ref: '#/components/schemas/PublicEvaluatorNumericScore'
required:
- - type
- title: NumberObjectEvaluationRuleFilter
+ - dataType
+ title: PublicEvaluatorNumericScore
- type: object
allOf:
- type: object
properties:
- type:
+ dataType:
type: string
enum:
- - boolean
- - $ref: '#/components/schemas/BooleanEvaluationRuleFilter'
+ - BOOLEAN
+ - $ref: '#/components/schemas/PublicEvaluatorBooleanScore'
required:
- - type
- title: BooleanEvaluationRuleFilter
+ - dataType
+ title: PublicEvaluatorBooleanScore
- type: object
allOf:
- type: object
properties:
- type:
+ dataType:
type: string
enum:
- - 'null'
- - $ref: '#/components/schemas/NullEvaluationRuleFilter'
+ - CATEGORICAL
+ - $ref: '#/components/schemas/PublicEvaluatorCategoricalScore'
required:
- - type
- title: NullEvaluationRuleFilter
+ - dataType
+ title: PublicEvaluatorCategoricalScore
description: >-
- One filter condition used to decide whether a live-ingested observation
- should be evaluated.
-
-
- All filters must be satisfied for the rule to run. Experiment scope is
- expressed with filters rather than a separate target field:
-
- - `isExperimentItemRootSpan = true` limits execution to experiment item
- roots.
-
- - `datasetId` limits execution to experiments for the selected datasets.
- Use dataset IDs from `GET /api/public/v2/datasets`.
-
-
- Pick the filter `type` first, as it determines the required fields and
- value shape. Use `key` only for object filters such as `metadata`.
-
-
- Operator quick reference by filter `type`:
-
- - `string`: `"="`, `contains`, `does not contain`, `starts with`, `ends
- with`
-
- - `number`: `"="`, `">"`, `"<"`, `">="`, `"<="`
-
- - `datetime`: `"="`, `">"`, `"<"`, `">="`, `"<="`
-
- - `stringOptions`: `any of`, `none of`
-
- - `arrayOptions`: `any of`, `none of`, `all of`
-
- - `stringObject`: `"="`, `contains`, `does not contain`, `starts with`,
- `ends with`, `is set`, `is not set` (use `is set` / `is not set` for key
- presence; an empty value for `contains`, `starts with`, or `ends with`
- is treated as `is set`)
-
- - `boolean`: `"="`, `"<>"`
-
- - `null`: `is null`, `is not null`
-
-
- Supported columns. Each column accepts exactly one filter `type`;
- sending a column with a different `type` is rejected with `400`.
-
- - `type`: `stringOptions`, values `SPAN`, `EVENT`, `GENERATION`,
- `AGENT`, `TOOL`, `CHAIN`, `RETRIEVER`, `EVALUATOR`, `EMBEDDING`,
- `GUARDRAIL`
-
- - `name`: `stringOptions`
-
- - `environment`: `stringOptions`
-
- - `level`: `stringOptions`, values `DEBUG`, `DEFAULT`, `WARNING`,
- `ERROR`
-
- - `version`: `string`
-
- - `traceName`: `stringOptions`
-
- - `userId`: `string`
-
- - `sessionId`: `string`
-
- - `tags`: `arrayOptions`
-
- - `metadata`: `stringObject`, requires `key`
-
- - `isRootObservation`: `boolean`; true when the observation has no
- parent or is explicitly marked as an application root
+ 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: EvaluatorOutputDefinitionBase
type: object
- description: Stored filter returned verbatim by evaluation-rule read endpoints.
properties:
- type:
+ scoreReasoningInstructions:
type: string
+ nullable: true
description: >-
- 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: PublicEvaluatorCategoricalScore
type: object
properties:
- 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
+ - shouldAllowMultipleMatches
allOf:
- - $ref: '#/components/schemas/EvaluationRuleReadFilterBase'
- EvaluationRuleReadFilter:
- title: EvaluationRuleReadFilter
+ - $ref: '#/components/schemas/EvaluatorOutputDefinitionBase'
+ PublicEvaluatorOutputDefinition:
+ title: PublicEvaluatorOutputDefinition
oneOf:
- - $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: PublicEvaluatorCategoricalScore
description: >-
- 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: EvaluationRuleStringFilterOperator
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
+ - '='
+ - contains
+ - does not contain
+ - starts with
+ - ends with
+ EvaluationRuleStringObjectFilterOperator:
+ title: EvaluationRuleStringObjectFilterOperator
+ type: string
+ enum:
+ - '='
+ - contains
+ - does not contain
+ - starts with
+ - ends with
+ - is set
+ - is not set
+ EvaluationRuleNumberFilterOperator:
+ title: EvaluationRuleNumberFilterOperator
+ type: string
+ enum:
+ - '='
+ - '>'
+ - <
+ - '>='
+ - <=
+ EvaluationRuleOptionsFilterOperator:
+ title: EvaluationRuleOptionsFilterOperator
+ type: string
+ enum:
+ - any of
+ - none of
+ EvaluationRuleArrayOptionsFilterOperator:
+ title: EvaluationRuleArrayOptionsFilterOperator
+ type: string
+ enum:
+ - any of
+ - none of
+ - all of
+ EvaluationRuleBooleanFilterOperator:
+ title: EvaluationRuleBooleanFilterOperator
+ type: string
+ enum:
+ - '='
+ - <>
+ EvaluationRuleNullFilterOperator:
+ title: EvaluationRuleNullFilterOperator
+ type: string
+ enum:
+ - is null
+ - is not null
+ DateTimeEvaluationRuleFilter:
+ title: DateTimeEvaluationRuleFilter
type: object
- 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: StringEvaluationRuleFilter
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:
+ 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: NumberEvaluationRuleFilter
type: object
- description: >-
- Standard error response for the stable evaluators and evaluation-rules
- API.
-
-
- Use the HTTP status for the broad failure class and `code` for
- programmatic handling. `details` is included when field-level validation
- or retry information is available.
properties:
- message:
+ 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: double
required:
- - message
- - code
- EvaluationRuleEvaluatorAssignmentInput:
- title: EvaluationRuleEvaluatorAssignmentInput
+ - column
+ - operator
+ - value
+ StringOptionsEvaluationRuleFilter:
+ title: StringOptionsEvaluationRuleFilter
type: object
properties:
- 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: array
items:
- $ref: '#/components/schemas/PromptVariableMappingInput'
- nullable: true
- description: >-
- Rule-specific prompt-variable mapping.
-
-
- Set to `null` or omit to inherit the evaluator's latest default
- mapping. Code evaluators use the fixed runtime mapping and should
- use `null`.
+ type: string
+ description: One or more allowed string values.
required:
- - evaluatorId
- EvaluatorAssignment:
- title: EvaluatorAssignment
+ - column
+ - operator
+ - value
+ ArrayOptionsEvaluationRuleFilter:
+ title: ArrayOptionsEvaluationRuleFilter
type: object
properties:
- 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: array
items:
- $ref: '#/components/schemas/PromptVariableMapping'
- nullable: true
- description: >-
- Stored rule-specific override, or `null` when the evaluator's latest
- default mapping is inherited. Legacy mappings are returned as an
- explicit `legacy` variant.
+ type: string
+ description: One or more array elements to match.
required:
- - evaluatorId
- - variableMapping
- EvaluationRule:
- title: EvaluationRule
+ - column
+ - operator
+ - value
+ StringObjectEvaluationRuleFilter:
+ title: StringObjectEvaluationRuleFilter
type: object
- description: >-
- Live evaluation rule for incoming observations.
-
-
- A rule determines which evaluators should be used, which observations
- should trigger scoring, how often scoring should run, and which
- observation fields should populate prompt variables.
properties:
- id:
- type: string
- description: Stable evaluation-rule identifier.
- name:
+ column:
type: string
description: >-
- Human-readable rule name. This is independent from evaluator names
- and does not need to be unique.
- createdBy:
- $ref: '#/components/schemas/Creator'
- nullable: true
- description: User who created this rule, or `null` when no user can be resolved.
- enabled:
- type: boolean
- description: Whether live execution is enabled for this rule.
- sampling:
- type: number
- format: double
- description: |-
- Fraction of matching observations that should be evaluated.
-
- Must be between `0` and `1`.
- - `1` evaluates every matching observation.
- - `0.25` evaluates approximately 25% of matching observations.
- filter:
- type: array
- items:
- $ref: '#/components/schemas/EvaluationRuleReadFilter'
- description: >-
- List of stored filter conditions returned verbatim. Filters with a
- `key` use the keyed response shape; all others use the base shape.
- These response shapes are not broken down by internal filter type.
- An empty list matches every incoming object.
- evaluatorAssignments:
- type: array
- items:
- $ref: '#/components/schemas/EvaluatorAssignment'
- description: Evaluators attached to this rule in deterministic assignment order.
- createdAt:
+ 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: NumberObjectEvaluationRuleFilter
type: object
properties:
- 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: number
format: double
- nullable: true
- description: >-
- Fraction of matching observations to evaluate. Omit this field to
- use the default of `1`, which evaluates every match. `null` is not
- accepted.
- filter:
- type: array
- items:
- $ref: '#/components/schemas/EvaluationRuleFilter'
- nullable: true
- description: >-
- Conditions used to select observations. Defaults to an empty list,
- which matches every incoming observation.
- evaluatorAssignments:
- type: array
- items:
- $ref: '#/components/schemas/EvaluationRuleEvaluatorAssignmentInput'
- description: >-
- Evaluators to attach to this rule. Disabled rules may use an empty
- list as a draft.
required:
- - name
- - enabled
- - evaluatorAssignments
- UpdateEvaluationRuleRequest:
- title: UpdateEvaluationRuleRequest
+ - column
+ - key
+ - operator
+ - value
+ CategoryOptionsEvaluationRuleFilter:
+ title: CategoryOptionsEvaluationRuleFilter
type: 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: array
items:
- $ref: '#/components/schemas/EvaluationRule'
- description: Evaluation rules for this page.
- meta:
- $ref: '#/components/schemas/CursorMeta'
- description: Cursor pagination metadata.
+ type: string
required:
- - data
- - meta
- DeletedEvaluationRule:
- title: DeletedEvaluationRule
+ - column
+ - key
+ - operator
+ - value
+ BooleanEvaluationRuleFilter:
+ title: BooleanEvaluationRuleFilter
type: 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: boolean
required:
- - id
- Creator:
- title: Creator
+ - column
+ - operator
+ - value
+ NullEvaluationRuleFilter:
+ title: NullEvaluationRuleFilter
type: 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: PromptVariableMappingInput
type: object
description: >-
- 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: string
description: >-
- 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: true
description: >-
- 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: PromptVariableMappingRead
type: 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: true
description: >-
- 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: string
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.
+ 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: LegacyPromptVariableMapping
type: object
+ description: >-
+ **Deprecated:** Connects one prompt variable to data from a legacy trace
+ or dataset evaluation rule.
+
+
+ `langfuseObject` selects the object kind. `objectName` separately
+ selects a named observation and is `null` for trace and dataset-item
+ mappings.
properties:
- 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: EvaluationRuleFilter
oneOf:
- type: object
allOf:
@@ -13351,11 +10104,11 @@ components:
type:
type: string
enum:
- - llm_as_judge
- - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'
+ - datetime
+ - $ref: '#/components/schemas/DateTimeEvaluationRuleFilter'
required:
- type
- title: LlmAsJudgeEvaluatorVersion
+ title: DateTimeEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -13363,185 +10116,47 @@ components:
type:
type: string
enum:
- - 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: object
allOf:
- type: object
@@ -13549,11 +10164,11 @@ components:
type:
type: string
enum:
- - llm_as_judge
- - $ref: '#/components/schemas/LlmAsJudgeEvaluator'
+ - arrayOptions
+ - $ref: '#/components/schemas/ArrayOptionsEvaluationRuleFilter'
required:
- type
- title: LlmAsJudgeEvaluator
+ title: ArrayOptionsEvaluationRuleFilter
- type: object
allOf:
- type: object
@@ -13561,507 +10176,654 @@ components:
type:
type: string
enum:
- - 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: NullEvaluationRuleFilter
description: >-
- 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: PublicApiError
type: object
+ description: >-
+ Standard error response for the stable evaluators and evaluation-rules
+ API.
+
+
+ Use the HTTP status for the broad failure class and `code` for
+ programmatic handling. `details` is included when field-level validation
+ or retry information is available.
properties:
- 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: true
description: >-
- 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: array
items:
$ref: '#/components/schemas/PromptVariableMappingInput'
nullable: true
description: >-
- Default prompt-variable mapping, or `null` when no default is
- configured.
- outputDefinition:
- $ref: '#/components/schemas/EvaluatorOutputDefinition'
- description: >-
- Structured output schema returned by this evaluator. Do not include
- an internal persistence version.
+ 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: EvaluatorAssignment
type: object
properties:
- 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: EvaluationRule
type: 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: CreateEvaluationRuleRequest
type: object
properties:
name:
type: string
- nullable: true
- description: New human-readable evaluator name.
- description:
- type: string
- nullable: true
- description: New description. Set to `null` to clear it.
- type:
- type: string
- const: llm_as_judge
- description: Evaluator type. The type of an existing evaluator cannot change.
- prompt:
- $ref: '#/components/schemas/EvaluatorChatPromptInput'
description: >-
- Complete replacement user prompt string or an ordered list of chat
- messages.
- modelConfig:
- $ref: '#/components/schemas/EvaluatorModelConfig'
+ Human-readable rule name. Names are not identifiers and do not need
+ to be unique.
+ enabled:
+ type: boolean
+ description: >-
+ Whether live execution should start immediately. Enabled rules
+ require at least one evaluator assignment.
+ sampling:
+ type: number
+ format: double
nullable: true
description: >-
- 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: array
items:
- $ref: '#/components/schemas/PromptVariableMappingInput'
+ $ref: '#/components/schemas/EvaluationRuleFilter'
nullable: true
description: >-
- 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: UpdateEvaluationRuleRequest
type: object
+ description: At least one field must be provided.
properties:
name:
type: string
nullable: true
- description: New human-readable evaluator name.
- description:
- type: string
+ description: New human-readable rule name.
+ enabled:
+ type: boolean
nullable: true
- description: New description. Set to `null` to clear it.
- type:
- type: string
- const: code
- description: Evaluator type. The type of an existing evaluator cannot change.
- sourceCode:
- type: string
- description: Complete replacement source code.
- sourceCodeLanguage:
- $ref: '#/components/schemas/CodeEvaluatorSourceCodeLanguage'
- description: Runtime language used to execute the source code.
- required:
- - type
- - sourceCode
- - sourceCodeLanguage
- UpdateEvaluatorRequest:
- title: UpdateEvaluatorRequest
- oneOf:
- - $ref: '#/components/schemas/UpdateEvaluatorMetadataRequest'
- - $ref: '#/components/schemas/UpdateLlmAsJudgeEvaluatorRequest'
- - $ref: '#/components/schemas/UpdateCodeEvaluatorRequest'
- description: >-
- Metadata-only update or complete flattened definition replacement. At
- least one field must be provided.
- EvaluatorsPage:
- title: EvaluatorsPage
- type: object
- properties:
- data:
+ 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/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: EvaluationRulesPage
type: object
properties:
data:
type: array
items:
- $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: DeletedEvaluationRule
type: 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: Creator
type: object
+ description: User who created the resource, or `null` when no user can be resolved.
properties:
id:
type: string
+ description: User identifier.
name:
type: string
- description:
- type: string
- nullable: true
- startTime:
- type: string
- format: date-time
- description: |-
- Start of the experiment, i.e. the earliest event within the
- requested time range. Clipped to `fromStartTime` when the
- experiment started before the requested range.
- endTime:
- type: string
- format: date-time
- description: |-
- End of the experiment, i.e. the latest event end within the
- requested time range.
- itemCount:
- type: integer
- description: Number of experiment items within the requested time range.
- datasetId:
- type: string
- nullable: true
- description: Null when the experiment is not associated with a dataset.
- metadata:
- type: object
- additionalProperties: true
nullable: true
- description: Included only when `fields=metadata` is requested.
- scores:
- type: array
- items:
- $ref: '#/components/schemas/ScoreV3'
- nullable: true
- description: >-
- Included only when `fields=scores` is requested. Contains scores
- directly attached to the experiment.
+ 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: EvaluatorModelConfig
type: object
+ description: >-
+ Explicit model configuration for an evaluator.
+
+
+ If the complete `modelConfig` is `null`, Langfuse uses the project's
+ default evaluation model.
+
+ If provided, the model must be available to the project when the
+ evaluator or evaluation rule is enabled.
properties:
- 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: true
description: >-
- 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: EvaluatorChatMessageRole
type: string
enum:
- - skill
- - mcp-tool
- - cli
- - docs
- - public-api
- - other
- SubmitFeedbackRequest:
- title: SubmitFeedbackRequest
+ - system
+ - user
+ - assistant
+ description: Role of an evaluator prompt message.
+ EvaluatorChatMessage:
+ title: EvaluatorChatMessage
type: 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: true
description: >-
- 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: LlmAsJudgeEvaluatorVersion
type: object
properties:
- 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: CodeEvaluatorVersion
type: object
properties:
- 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: EvaluatorVersion
oneOf:
- type: object
allOf:
@@ -14070,95 +10832,11 @@ components:
type:
type: string
enum:
- - trace-create
- - $ref: '#/components/schemas/TraceEvent'
- required:
- - type
- title: TraceEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - score-create
- - $ref: '#/components/schemas/ScoreEvent'
- required:
- - type
- title: ScoreEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - span-create
- - $ref: '#/components/schemas/CreateSpanEvent'
- required:
- - type
- title: CreateSpanEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - span-update
- - $ref: '#/components/schemas/UpdateSpanEvent'
- required:
- - type
- title: UpdateSpanEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - generation-create
- - $ref: '#/components/schemas/CreateGenerationEvent'
- required:
- - type
- title: CreateGenerationEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - generation-update
- - $ref: '#/components/schemas/UpdateGenerationEvent'
- required:
- - type
- title: UpdateGenerationEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - event-create
- - $ref: '#/components/schemas/CreateEventEvent'
- required:
- - type
- title: CreateEventEvent
- - type: object
- allOf:
- - type: object
- properties:
- type:
- type: string
- enum:
- - observation-create
- - $ref: '#/components/schemas/CreateObservationEvent'
+ - llm_as_judge
+ - $ref: '#/components/schemas/LlmAsJudgeEvaluatorVersion'
required:
- type
- title: CreateObservationEvent
+ title: LlmAsJudgeEvaluatorVersion
- type: object
allOf:
- type: object
@@ -14166,778 +10844,703 @@ components:
type:
type: string
enum:
- - observation-update
- - $ref: '#/components/schemas/UpdateObservationEvent'
- required:
- - type
- title: UpdateObservationEvent
- ObservationType:
- title: ObservationType
- type: string
- enum:
- - SPAN
- - GENERATION
- - EVENT
- - AGENT
- - TOOL
- - CHAIN
- - RETRIEVER
- - EVALUATOR
- - EMBEDDING
- - GUARDRAIL
- IngestionUsage:
- title: IngestionUsage
- oneOf:
- - $ref: '#/components/schemas/Usage'
- - $ref: '#/components/schemas/OpenAIUsage'
- OpenAIUsage:
- title: OpenAIUsage
+ - code
+ - $ref: '#/components/schemas/CodeEvaluatorVersion'
+ required:
+ - type
+ title: CodeEvaluatorVersion
+ EvaluationRuleAssignment:
+ title: EvaluationRuleAssignment
type: 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: EvaluatorBase
type: object
properties:
- 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-time
nullable: true
- parentObservationId:
+ description: Timestamp when the evaluator was paused, otherwise `null`.
+ pausedReason:
type: string
nullable: true
- version:
+ description: Machine-readable reason when `status=paused`, otherwise `null`.
+ pausedMessage:
type: string
nullable: 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: string
format: 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: LlmAsJudgeEvaluator
type: object
properties:
- 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
+ - outputDefinition
allOf:
- - $ref: '#/components/schemas/UpdateEventBody'
- CreateGenerationBody:
- title: CreateGenerationBody
+ - $ref: '#/components/schemas/EvaluatorBase'
+ CodeEvaluator:
+ title: CodeEvaluator
type: object
properties:
- 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
+ - sourceCodeLanguage
allOf:
- - $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: CreateLlmAsJudgeEvaluatorRequest
type: object
properties:
- 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: string
nullable: 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: CreateCodeEvaluatorRequest
type: object
properties:
- id:
- type: string
- nullable: true
- traceId:
- type: string
- nullable: true
- type:
- $ref: '#/components/schemas/ObservationType'
name:
type: string
- nullable: true
- startTime:
- type: string
- format: date-time
- nullable: true
- endTime:
- type: string
- format: date-time
- nullable: true
- completionStartTime:
- type: string
- format: date-time
- nullable: true
- model:
- type: string
- nullable: true
- modelParameters:
- type: object
- additionalProperties:
- $ref: '#/components/schemas/MapValue'
- nullable: true
- input:
- nullable: true
- version:
- type: string
- nullable: true
- metadata:
- nullable: true
- output:
- nullable: true
- usage:
- $ref: '#/components/schemas/Usage'
- nullable: true
- level:
- $ref: '#/components/schemas/ObservationLevel'
- nullable: true
- statusMessage:
+ description: >-
+ Human-readable evaluator name. Names are not identifiers and do not
+ need to be unique.
+ description:
type: string
nullable: 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: UpdateEvaluatorMetadataRequest
type: 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: true
name:
type: string
nullable: true
- userId:
- type: string
- nullable: true
- input:
- nullable: true
- output:
- nullable: true
- sessionId:
- type: string
- nullable: true
- release:
- type: string
- nullable: true
- version:
- type: string
- nullable: true
- metadata:
- nullable: true
- tags:
- type: array
- items:
- type: string
- nullable: true
- environment:
+ description: New human-readable evaluator name.
+ description:
type: string
nullable: 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: UpdateLlmAsJudgeEvaluatorRequest
type: object
properties:
- id:
- type: string
- nullable: true
- traceId:
- type: string
- nullable: true
- sessionId:
- type: string
- nullable: true
- observationId:
+ name:
type: string
nullable: true
- datasetRunId:
+ description: New human-readable evaluator name.
+ description:
type: string
nullable: 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: true
description: >-
- The annotation queue referenced by the score. Indicates if score was
- initially created while processing annotation queue.
- value:
- $ref: '#/components/schemas/CreateScoreValue'
- description: >-
- The value of the score. Must be passed as string for categorical and
- text scores, and numeric for boolean and numeric scores. Boolean
- score values must equal either 1 or 0 (true or false). Text score
- values must be between 1 and 500 characters.
- comment:
- type: string
- nullable: true
- metadata:
- nullable: true
- dataType:
- $ref: '#/components/schemas/ScoreDataType'
+ Explicit model configuration. Set to `null` or omit to use the
+ project's default evaluation model.
+ variableMapping:
+ type: array
+ items:
+ $ref: '#/components/schemas/PromptVariableMappingInput'
nullable: true
description: >-
- 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: UpdateCodeEvaluatorRequest
type: object
properties:
- 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: EvaluatorsPage
type: object
properties:
- 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: EvaluatorVersionsPage
type: object
- description: >-
- Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
- shut down on November 16, 2026, except for score events: from that date
- it accepts only `score-create` events and rejects all other event types,
- including this one. To write scores, prefer `POST /api/public/scores`;
- see the [Scores API
- docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
- To write traces and observations, always prefer upgrading to the current
- Python and JS SDKs. If you use custom auto-instrumentation, send them to
- the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
- example with curl; see the [OpenTelemetry integration
- docs](https://langfuse.com/integrations/native/opentelemetry). To read
- data back, use the v4 read APIs; see the [Observations API
- docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
- and the [Metrics API
- docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
- path to live data is OpenTelemetry ingestion combined with `GET
- /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
- public APIs may have data delays of several minutes.
properties:
- body:
- $ref: '#/components/schemas/CreateGenerationBody'
+ 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: CursorMeta
type: object
- description: >-
- Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
- shut down on November 16, 2026, except for score events: from that date
- it accepts only `score-create` events and rejects all other event types,
- including this one. To write scores, prefer `POST /api/public/scores`;
- see the [Scores API
- docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
- To write traces and observations, always prefer upgrading to the current
- Python and JS SDKs. If you use custom auto-instrumentation, send them to
- the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
- example with curl; see the [OpenTelemetry integration
- docs](https://langfuse.com/integrations/native/opentelemetry). To read
- data back, use the v4 read APIs; see the [Observations API
- docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
- and the [Metrics API
- docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
- path to live data is OpenTelemetry ingestion combined with `GET
- /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
- public APIs may have data delays of several minutes.
- properties:
- body:
- $ref: '#/components/schemas/UpdateGenerationBody'
- required:
- - body
+ description: Cursor pagination metadata.
+ properties: {}
allOf:
- - $ref: '#/components/schemas/BaseEvent'
- CreateSpanEvent:
- title: CreateSpanEvent
+ - $ref: '#/components/schemas/utilsCursorMetaResponse'
+ DeletedEvaluator:
+ title: DeletedEvaluator
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.
+ 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: ExperimentsResponse
type: object
- description: >-
- Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
- shut down on November 16, 2026, except for score events: from that date
- it accepts only `score-create` events and rejects all other event types,
- including this one. To write scores, prefer `POST /api/public/scores`;
- see the [Scores API
- docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
- To write traces and observations, always prefer upgrading to the current
- Python and JS SDKs. If you use custom auto-instrumentation, send them to
- the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
- example with curl; see the [OpenTelemetry integration
- docs](https://langfuse.com/integrations/native/opentelemetry). To read
- data back, use the v4 read APIs; see the [Observations API
- docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
- and the [Metrics API
- docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
- path to live data is OpenTelemetry ingestion combined with `GET
- /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
- public APIs may have data delays of several minutes.
properties:
- body:
- $ref: '#/components/schemas/UpdateSpanBody'
+ 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: ExperimentsResponseMeta
type: object
- description: >-
- Sunset warning: this is the deprecated Langfuse v3 ingestion API. It is
- shut down on November 16, 2026, except for score events: from that date
- it accepts only `score-create` events and rejects all other event types,
- including this one. To write scores, prefer `POST /api/public/scores`;
- see the [Scores API
- docs](https://langfuse.com/docs/api-and-data-platform/features/scores-api).
- To write traces and observations, always prefer upgrading to the current
- Python and JS SDKs. If you use custom auto-instrumentation, send them to
- the OpenTelemetry endpoint (`POST /api/public/otel/v1/traces`), for
- example with curl; see the [OpenTelemetry integration
- docs](https://langfuse.com/integrations/native/opentelemetry). To read
- data back, use the v4 read APIs; see the [Observations API
- docs](https://langfuse.com/docs/api-and-data-platform/features/observations-api)
- and the [Metrics API
- docs](https://langfuse.com/docs/metrics/features/metrics-api). The only
- path to live data is OpenTelemetry ingestion combined with `GET
- /api/public/v2/observations` and `GET /api/public/v2/metrics`. All other
- public APIs may have data delays of several minutes.
- properties:
- body:
- $ref: '#/components/schemas/CreateEventBody'
- required:
- - body
+ description: Metadata for cursor-based pagination.
+ properties: {}
allOf:
- - $ref: '#/components/schemas/BaseEvent'
- IngestionSuccess:
- title: IngestionSuccess
+ - $ref: '#/components/schemas/utilsCursorMetaResponse'
+ Experiment:
+ title: Experiment
type: object
properties:
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: string
nullable: 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: ExperimentItemsResponse
type: object
properties:
- successes:
- type: array
- items:
- $ref: '#/components/schemas/IngestionSuccess'
- errors:
+ data:
type: array
items:
- $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: ExperimentItem
type: object
- description: OpenAI Usage schema from (Chat-)Completion APIs
properties:
- prompt_tokens:
- type: integer
- completion_tokens:
- type: integer
- total_tokens:
- type: integer
- prompt_tokens_details:
- type: object
- additionalProperties:
- type: integer
- nullable: true
+ 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
- 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: true
nullable: true
- required:
- - prompt_tokens
- - completion_tokens
- - total_tokens
- OpenAIResponseUsageSchema:
- title: OpenAIResponseUsageSchema
- type: object
- description: OpenAI Usage schema from Response API
- properties:
- input_tokens:
- type: integer
- output_tokens:
- type: integer
- total_tokens:
- type: integer
- input_tokens_details:
+ description: Included when `fields=metadata` is requested.
+ experimentItemMetadata:
type: object
- additionalProperties:
- type: integer
- nullable: true
+ additionalProperties: true
nullable: 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: SubmitFeedbackRequest
type: object
properties:
- data:
- type: array
- items:
- type: object
- additionalProperties: true
+ targetType:
+ $ref: '#/components/schemas/FeedbackTargetType'
+ description: Category of the thing the feedback is about.
+ target:
+ type: string
description: >-
- The metrics data. Each item in the list contains the metric values
- and dimensions requested in the query.
-
- Format varies based on the query parameters.
-
- Histograms will return an array with [lower, upper, height] tuples.
- _deprecation:
- $ref: '#/components/schemas/Deprecation'
+ The specific instance within targetType: the skill name, MCP tool
+ name, CLI command, API endpoint path, or docs page path (e.g.
+ 'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be
+ between 1 and 200 characters.
+ feedback:
+ type: string
+ description: >-
+ Concise feedback text approved by the user. Must be between 1 and
+ 3000 characters.
+ goal:
+ type: string
+ nullable: true
+ description: >-
+ Optional user-approved goal or use case they were trying to achieve.
+ Must be between 1 and 1500 characters when provided. Do not include
+ secrets, customer data, trace payloads, or broad unrelated context.
+ referenceUrl:
+ type: string
nullable: true
+ description: >-
+ Optional HTTP(S) reference URL. Langfuse stores it as text for
+ triage and does not fetch it.
required:
- - data
- legacyObservations:
- title: legacyObservations
+ - targetType
+ - target
+ - feedback
+ SubmitFeedbackResponse:
+ title: SubmitFeedbackResponse
type: object
properties:
- 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: HealthResponse
type: object
properties:
- 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: string
required:
- - data
- - meta
+ - version
+ - status
LlmConnection:
title: LlmConnection
type: 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:
+ - message
ScoreSubjectTraceV3:
title: ScoreSubjectTraceV3
type: 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: ScoreBody
type: object
properties:
id:
@@ -16878,6 +13608,18 @@ components:
nullable: true
name:
type: string
+ description: >-
+ The name of the score. Always overrides "output" for correction
+ scores.
+ environment:
+ type: string
+ nullable: true
+ queueId:
+ type: string
+ nullable: true
+ description: >-
+ The annotation queue referenced by the score. Indicates if score was
+ initially created while processing annotation queue.
value:
$ref: '#/components/schemas/CreateScoreValue'
description: >-
@@ -16889,286 +13631,25 @@ components:
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.
+ When set, must match the score value's type. If not set, will be
+ inferred from the score value or config
configId:
type: string
nullable: true
description: >-
- Reference a score config on a score. 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 values
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/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
- - meta
DeleteTraceResponse:
title: DeleteTraceResponse
type: object
@@ -17177,14 +13658,6 @@ components:
type: string
required:
- message
- Sort:
- title: Sort
- type: object
- properties:
- id:
- type: string
- required:
- - id
unstableDashboardWidgetView:
title: unstableDashboardWidgetView
type: string
diff --git a/web/src/__tests__/server/datasets-api.servertest.ts b/web/src/__tests__/server/datasets-api.servertest.ts
index 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 datasetName
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 = z
datasetId: 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.ts
index 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-se
import { 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.ts
index 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();