From 4469d4d75095d4ed224aa8fafb4d8dec23643b4d Mon Sep 17 00:00:00 2001 From: Ben Bachem <10088265+bezbac@users.noreply.github.com> Date: Mon, 3 Aug 2026 16:59:27 +0200 Subject: [PATCH] feat: deprecate legacy API actions --- README.md | 16 +- openapi.yml | 10325 +++++++++++++++++------------- pnpm-lock.yaml | 304 + scripts/openapi-deprecations.ts | 29 + scripts/patch-openapi.ts | 54 +- src/cli.ts | 7 +- 6 files changed, 6376 insertions(+), 4359 deletions(-) create mode 100644 pnpm-lock.yaml create mode 100644 scripts/openapi-deprecations.ts diff --git a/README.md b/README.md index 691022b..27a47a1 100644 --- a/README.md +++ b/README.md @@ -51,19 +51,17 @@ langfuse --public-key pk-lf-... --secret-key sk-lf-... api prompts list langfuse api __schema # List actions for a resource -langfuse api traces --help +langfuse api observations --help -# List traces -langfuse api traces list --limit 10 - -# Get a specific trace -langfuse api traces get +# List traces via the observations API +langfuse api observations list --limit 10 \ + --filter '[{"type":"boolean","column":"isRootObservation","operator":"=","value":true}]' # JSON output (for piping/scripting) -langfuse api traces list --limit 5 --json +langfuse api prompts list --limit 5 --json # Preview curl command -langfuse api traces list --limit 5 --curl +langfuse api prompts list --limit 5 --curl # Prompts langfuse api prompts list @@ -73,8 +71,6 @@ langfuse api prompts get --name my-prompt langfuse api datasets list langfuse api dataset-items list --dataset-name my-dataset -# Scores -langfuse api score-v2s get-scores --limit 20 ``` ## Agent Usage diff --git a/openapi.yml b/openapi.yml index 8bd6144..e3f061f 100644 --- a/openapi.yml +++ b/openapi.yml @@ -1177,6 +1177,8 @@ paths: application/json: schema: $ref: '#/components/schemas/CreateDatasetRunItemRequest' + deprecated: true + summary: '[DEPRECATED] Legacy API action' get: description: List dataset run items operationId: datasetRunItems_list @@ -1240,6 +1242,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/v2/datasets: get: description: Get all datasets @@ -1434,6 +1438,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' delete: description: Delete a dataset run and all its run items. This action is irreversible. operationId: datasets_deleteRun @@ -1483,6 +1489,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/datasets/{datasetName}/runs: get: description: Get dataset runs @@ -1542,6 +1550,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/experiments: get: description: |- @@ -1794,6 +1804,57 @@ paths: application/json: schema: {} security: *ref_0 + /api/public/feedback: + post: + description: >- + Submit explicit user-approved feedback about Langfuse skills, MCP tools, + CLI, docs, or public API. Do not include secrets, credentials, customer + data, trace payloads, or unrelated use-case details. + operationId: feedback_submit + tags: + - Feedback + parameters: [] + responses: + '201': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFeedbackResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitFeedbackRequest' /api/public/health: get: description: Check health of API and database @@ -1958,7 +2019,7 @@ paths: ```json { - "view": string, // Required. One of "traces", "observations", "scores-numeric", "scores-categorical" + "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" @@ -2033,6 +2094,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/observations/{observationId}: get: description: Get a observation @@ -2054,7 +2117,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ObservationsView' + $ref: '#/components/schemas/ObservationsViewSingle' '400': description: '' content: @@ -2081,6 +2144,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/observations: get: description: >- @@ -2369,52 +2434,8 @@ paths: application/json: schema: {} security: *ref_0 - /api/public/scores: - post: - description: Create a score (supports both trace and session scores) - operationId: legacy_scoreV1_create - tags: - - LegacyScoreV1 - parameters: [] - responses: - '200': - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/legacyCreateScoreResponse' - '400': - description: '' - content: - application/json: - schema: {} - '401': - description: '' - content: - application/json: - schema: {} - '403': - description: '' - content: - application/json: - schema: {} - '404': - description: '' - content: - application/json: - schema: {} - '405': - description: '' - content: - application/json: - schema: {} - security: *ref_0 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/legacyCreateScoreRequest' + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/scores/{scoreId}: delete: description: Delete a score (supports both trace and session scores) @@ -2753,11 +2774,14 @@ paths: ## V2 Differences - - Supports `observations`, `scores-numeric`, and `scores-categorical` - views only (traces view not supported) + - 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 @@ -2807,6 +2831,10 @@ paths: - `promptVersion` - Version of the prompt used + - `isRootObservation` - Boolean semantic-root status. `true` includes + physical roots and app roots whose SDK parent is external (so + `parentObservationId` may be non-null). + - `startTimeMonth` - Month of start_time in YYYY-MM format @@ -2888,6 +2916,24 @@ paths: - `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 @@ -2920,7 +2966,7 @@ paths: - `parentObservationId` - Use parentObservationId filter instead - **scores-numeric / scores-categorical views:** + **scores-numeric / scores-boolean / scores-categorical views:** - `id` - Use specific filters to narrow down results @@ -2959,7 +3005,7 @@ paths: ```json { - "view": string, // Required. One of "observations", "scores-numeric", "scores-categorical" + "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) @@ -3006,6 +3052,22 @@ paths: } ``` + + + 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 @@ -3256,7 +3318,7 @@ paths: parentObservationId, type - `basic` - name, level, statusMessage, version, environment, - bookmarked, public, userId, sessionId + bookmarked, public, userId, sessionId, isRootObservation - `time` - completionStartTime, createdAt, updatedAt @@ -3354,6 +3416,13 @@ paths: 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: >- @@ -3381,10 +3450,30 @@ paths: 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: >- @@ -3489,6 +3578,10 @@ paths: - `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 @@ -3592,6 +3685,12 @@ paths: "column": "output", "operator": "matches", "value": "needle" + }, + { + "type": "boolean", + "column": "isRootObservation", + "operator": "=", + "value": true } ] @@ -5619,6 +5718,54 @@ paths: application/json: schema: {} security: *ref_0 + /api/public/scores: + post: + description: >- + Create a score (supports trace, observation, session, and dataset run + scores) + operationId: scores_create + tags: + - Scores + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScoreResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScoreRequest' /api/public/v2/scores: get: description: |- @@ -5844,6 +5991,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/v2/scores/{scoreId}: get: description: |- @@ -5894,6 +6043,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/sessions: get: description: >- @@ -5993,6 +6144,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/sessions/{sessionId}: get: description: >- @@ -6051,6 +6204,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' /api/public/traces/{traceId}: get: description: Get a specific trace @@ -6110,6 +6265,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' delete: description: Delete a specific trace operationId: trace_delete @@ -6290,7 +6447,7 @@ paths: [ { - "type": string, // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null" + "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: ">", "<", ">=", "<=" @@ -6301,10 +6458,11 @@ paths: // - number: "=", ">", "<", ">=", "<=" // - stringObject: "=", "contains", "does not contain", "starts with", "ends with" // - 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, and categoryOptions types when filtering on nested fields like metadata + "key": string // Required only for stringObject, numberObject, booleanObject, and categoryOptions types when filtering on nested fields like metadata or score names } ] @@ -6389,6 +6547,12 @@ paths: - `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 @@ -6475,6 +6639,8 @@ paths: application/json: schema: {} security: *ref_0 + deprecated: true + summary: '[DEPRECATED] Legacy API action' delete: description: Delete multiple traces operationId: trace_deleteMultiple @@ -6529,20 +6695,101 @@ paths: required: - traceIds /api/public/unstable/dashboard-widgets: + get: + description: |- + List dashboard widgets in the project, ordered by most recently + updated first. + + Responses may include legacy `traces` widgets created before this + API existed. New widgets cannot be created with `view: traces`. + operationId: unstable_dashboardWidgets_list + tags: + - UnstableDashboardWidgets + parameters: + - name: page + in: query + description: 1-based page number. Defaults to `1`. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: Maximum number of items per page. Defaults to `50`. + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboardWidgetList' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 post: description: >- - Create a reusable dashboard widget. + 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`. - This endpoint creates the widget. It does not place the widget on a - dashboard grid, this has to be done in the UI. + Supported views are `observations`, `scores-numeric`, `scores-boolean`, + and `scores-categorical`. - Supported views are `observations`, `scores-numeric`, and - `scores-categorical`. + The legacy `traces` view is not supported by this unstable API. - The legacy `traces` view is not supported by this unstable API, - `minVersion` defaults to `2`; values below `2` are rejected. + 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: @@ -6604,108 +6851,28 @@ paths: application/json: schema: $ref: '#/components/schemas/unstableCreateDashboardWidgetRequest' - /api/public/unstable/evaluation-rules: - post: - description: >- - Create an evaluation rule. - - - An evaluation rule defines **what** incoming data should be evaluated - and **how prompt variables should be populated** from that data. - + /api/public/unstable/dashboard-widgets/{widgetId}: + get: + description: |- + Get a dashboard widget by id. - Use this resource after choosing an evaluator from the evaluator - endpoints. - - - Key rules: - - - `name` must be unique within the project for public evaluation rules - - - `target` must be `observation` or `experiment` - - - `evaluator.name` + `evaluator.scope` must identify an existing - evaluator family returned by the evaluator endpoints - - - Langfuse resolves that family to its latest version before saving the - evaluation rule - - - for `target=experiment`, use dataset `id` values from `GET - /api/public/v2/datasets` when filtering by `datasetId` - - - for `llm_as_judge` evaluators, every evaluator prompt variable must be - mapped exactly once - - - for `code` evaluators, Langfuse uses the fixed code runtime mapping; - omit `mapping` in create and update requests - - - for user-provided `llm_as_judge` mappings, `expected_output` and - `experiment_item_metadata` are only valid for `target=experiment` - - - if `enabled=true`, Langfuse validates that the referenced evaluator - can currently run - - - at most 50 evaluation rules can be effectively active in one project - at the same time - - - If an evaluation rule with the same `name` already exists in the - project, the API returns `409`. - - In that case, update the existing resource with `PATCH - /api/public/unstable/evaluation-rules/{evaluationRuleId}` instead of - creating a second one. - - - If enabling this resource would exceed the 50-active limit, the API also - returns `409`. - - In that case, disable or pause another active evaluation rule before - enabling a new one. - - - Current scope: - - - evaluation rules are live-ingestion rules only - - - they do not trigger historical backfills - - - Recovery guidance: - - - `400 invalid_filter_value`: fix the filter `column` or `value` using - `details.column`, `details.invalidValues`, and `details.allowedValues` - - - `400 invalid_filter_value` with `details.column=datasetId`: call `GET - /api/public/v2/datasets`, then retry with dataset `id` values from that - response - - - `400 missing_variable_mapping`: for `llm_as_judge` evaluators, fetch - the evaluator again and make sure every variable in `variables` appears - exactly once in `mapping` - - - `400 duplicate_variable_mapping`: remove repeated mappings for the - same variable - - - `400 invalid_variable_mapping`: for `llm_as_judge`, switch to a valid - `source` for the selected `target`, or fix the variable name - - - `400 invalid_json_path`: remove or correct the `jsonPath` - - - `422 evaluator_preflight_failed`: the selected evaluator cannot run - with the resolved model configuration. Fix the evaluator/default model - setup, then retry the create request. - operationId: unstable_evaluationRules_create + The response may use `view: traces` for legacy widgets. + operationId: unstable_dashboardWidgets_get tags: - - UnstableEvaluationRules - parameters: [] + - UnstableDashboardWidgets + parameters: + - name: widgetId + in: path + required: true + schema: + type: string responses: '200': description: '' content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluationRule' + $ref: '#/components/schemas/unstableDashboardWidget' '400': description: '' content: @@ -6731,18 +6898,6 @@ paths: content: application/json: schema: {} - '409': - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/unstablePublicApiError' - '422': - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/unstablePublicApiError' '429': description: '' content: @@ -6756,44 +6911,33 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/unstableCreateEvaluationRuleRequest' - get: - description: >- - List evaluation rules in the authenticated project. + 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`. - Each item describes one live evaluation rule and its effective runtime - status. - operationId: unstable_evaluationRules_list + `view` cannot be changed to the legacy `traces` value. Existing + `traces` widgets may be updated on other fields. + operationId: unstable_dashboardWidgets_update tags: - - UnstableEvaluationRules + - UnstableDashboardWidgets parameters: - - name: page - in: query - description: 1-based page number. Defaults to `1`. - required: false - schema: - type: integer - nullable: true - - name: limit - in: query - description: Maximum number of items per page. Defaults to `50`. - required: false + - name: widgetId + in: path + required: true schema: - type: integer - nullable: true + type: string responses: '200': description: '' content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluationRules' + $ref: '#/components/schemas/unstableDashboardWidget' '400': description: '' content: @@ -6832,22 +6976,24 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - /api/public/unstable/evaluation-rules/{evaluationRuleId}: - get: - description: >- - Get one evaluation rule by its identifier. - + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateDashboardWidgetRequest' + delete: + description: |- + Delete a dashboard widget. - Use this endpoint to inspect the current evaluator, target, mapping, - filters, and effective runtime status. - operationId: unstable_evaluationRules_get + The API returns `409` while the widget is still placed on a dashboard. + Remove those placements first. + operationId: unstable_dashboardWidgets_delete tags: - - UnstableEvaluationRules + - UnstableDashboardWidgets parameters: - - name: evaluationRuleId + - name: widgetId in: path - description: >- - Evaluation rule identifier returned by the evaluation rule endpoints. required: true schema: type: string @@ -6857,7 +7003,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluationRule' + $ref: '#/components/schemas/unstableDeleteDashboardWidgetResponse' '400': description: '' content: @@ -6883,6 +7029,12 @@ paths: content: application/json: schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' '429': description: '' content: @@ -6896,74 +7048,36 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - patch: - description: >- - Update an evaluation rule. - - - Typical uses: - - - enable or disable live execution - - - switch to another evaluator - - - adjust sampling - - - change filters - - - update LLM-as-judge variable mappings - - - Important behavior: - - - provide only the fields you want to change - - - if you provide `evaluator`, Langfuse resolves that evaluator family to - its latest version before saving - - - changing `target`, `filter`, or an LLM-as-judge `mapping` must still - produce a valid target-specific configuration - - - if you change `target` for an LLM-as-judge rule, also send a - compatible `filter` and `mapping` in the same request unless the - existing ones are still valid for the new target - - - for `code` evaluator rules, omit `mapping`; Langfuse stores the fixed - code runtime mapping automatically - - - if the resulting config is enabled, Langfuse re-validates that the - selected evaluator can run - - - if the update would move a non-active evaluation rule into the active - state and the project already has 50 active evaluation rules, the API - returns `409` - - - Recovery guidance: - - - if an LLM-as-judge update fails with `missing_variable_mapping` or - `invalid_variable_mapping` after changing `evaluator` or `target`, - resend the request with a complete new `mapping` - - - if the update fails with `invalid_filter_value` after changing - `target`, resend the request with a target-compatible `filter` - operationId: unstable_evaluationRules_update + /api/public/unstable/dashboards: + get: + description: |- + List dashboards in the project, ordered by most recently updated + first. + operationId: unstable_dashboards_list tags: - - UnstableEvaluationRules + - UnstableDashboards parameters: - - name: evaluationRuleId - in: path - description: Evaluation rule identifier. - required: true + - name: page + in: query + 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': description: '' content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluationRule' + $ref: '#/components/schemas/unstableDashboardList' '400': description: '' content: @@ -6989,12 +7103,6 @@ paths: content: application/json: schema: {} - '422': - description: '' - content: - application/json: - schema: - $ref: '#/components/schemas/unstablePublicApiError' '429': description: '' content: @@ -7008,36 +7116,19 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/unstableUpdateEvaluationRuleRequest' - delete: - description: >- - Delete an evaluation rule. - - - This removes the live-ingestion rule only. It does not delete the - referenced evaluator. - operationId: unstable_evaluationRules_delete + post: + description: Create a dashboard. + operationId: unstable_dashboards_create tags: - - UnstableEvaluationRules - parameters: - - name: evaluationRuleId - in: path - description: Evaluation rule identifier. - required: true - schema: - type: string + - UnstableDashboards + parameters: [] responses: '200': description: '' content: application/json: schema: - $ref: '#/components/schemas/unstableDeleteEvaluationRuleResponse' + $ref: '#/components/schemas/unstableDashboard' '400': description: '' content: @@ -7076,92 +7167,31 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - /api/public/unstable/evaluators: - post: - description: >- - Create an evaluator in the authenticated project. - - - Use evaluators to define **how** Langfuse should score data. - - LLM-as-a-judge evaluators define a prompt, expected structured output, - and optional model configuration. - - Code evaluators define source code and a runtime language. - - - Naming behavior: - - - If this is a new evaluator name in your project, Langfuse creates - version `1`. - - - If the name already exists in your project, Langfuse creates the next - version and returns it. - - - When a new project version is created, existing evaluation rules in - that project automatically move to the newest version for that evaluator - name. - - - Recommended workflow: - - 1. Create the evaluator. - - 2. Read the returned `variables` array. - - 3. Read the returned `outputDefinition.dataType` so the client knows - whether future scores will be numeric, boolean, or categorical. - - 4. Create one or more evaluation rules that reference the returned - evaluator family using `name` and `scope`. - - - Code evaluator validation: - - - At creation, Langfuse only validates the request shape - - - The `sourceCode` itself is not executed here. It is first run - (preflight-tested against a sample observation) when you link the - evaluator to an evaluation rule, so runtime errors in the code surface - at evaluation-rule creation, not at evaluator creation. - - - Recovery guidance: - - - `422` with `code=evaluator_preflight_failed`: the evaluator cannot run - with the resolved model configuration. Add a valid explicit - `modelConfig`, or configure the project's default evaluation model, then - retry the same request. - - - `400` with `code=invalid_body`: the request shape is malformed. Use - the structured `details.issues` array to fix the specific fields and - retry. - - - `400` with `code=invalid_body` on `outputDefinition`: for - `type=llm_as_judge`, send `dataType`, `reasoning.description`, and - `score.description`. Do not send `version`; it is not part of the public - request shape. - - - If `type` is omitted, Langfuse treats the request as - `type=llm_as_judge` for backwards compatibility. New clients should send - `type` explicitly. - - - Unstable API note: - - - This surface may evolve while the underlying evaluation data model is - being redesigned. - operationId: unstable_evaluators_create + 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: - - UnstableEvaluators - parameters: [] + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string responses: '200': description: '' content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluator' + $ref: '#/components/schemas/unstableDashboard' '400': description: '' content: @@ -7187,18 +7217,62 @@ paths: content: application/json: schema: {} - '409': + '429': description: '' content: application/json: schema: $ref: '#/components/schemas/unstablePublicApiError' - '422': + '500': description: '' content: application/json: schema: $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + patch: + description: Update a dashboard's name, description, definition, or filters. + operationId: unstable_dashboards_update + tags: + - UnstableDashboards + parameters: + - name: dashboardId + in: path + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDashboard' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} '429': description: '' content: @@ -7217,46 +7291,25 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/unstableCreateEvaluatorRequest' - get: - description: >- - List the evaluators available to the authenticated project. - - - Important behavior: - - - This endpoint returns the latest version of each available evaluator. - - - Results can include evaluators from your project and Langfuse-managed - evaluators. - - - If the same evaluator name exists in both places, both are returned as - separate items with different `scope` values. - operationId: unstable_evaluators_list + $ref: '#/components/schemas/unstableUpdateDashboardRequest' + delete: + description: Delete a dashboard. + operationId: unstable_dashboards_delete tags: - - UnstableEvaluators + - 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/unstableEvaluators' + $ref: '#/components/schemas/unstableDeleteDashboardResponse' '400': description: '' content: @@ -7295,22 +7348,25 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - /api/public/unstable/evaluators/{evaluatorId}: - get: - description: >- - Get one evaluator by `id`. + /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. - Use this endpoint when you want the prompt, output definition, model - configuration, and derived variables for the evaluator you plan to use - in an evaluation rule. - operationId: unstable_evaluators_get + 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: - - UnstableEvaluators + - UnstableDashboards parameters: - - name: evaluatorId + - name: dashboardId in: path - description: Evaluator identifier returned by the evaluator endpoints. required: true schema: type: string @@ -7320,7 +7376,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/unstableEvaluator' + $ref: '#/components/schemas/unstableDashboardPlacement' '400': description: '' content: @@ -7346,6 +7402,12 @@ paths: content: application/json: schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' '429': description: '' content: @@ -7359,30 +7421,30 @@ paths: schema: $ref: '#/components/schemas/unstablePublicApiError' security: *ref_0 - delete: - description: >- - Delete an evaluator. - - - Important behavior: - - - This deletes the evaluator including all of its stored versions; - `evaluatorId` may reference any version. - - - The API returns `409` while evaluation rules still reference the - evaluator. Delete those evaluation rules first. - - - Langfuse-managed evaluators (`scope=managed`) cannot be deleted; the - API returns `403`. - - - Scores already produced by the evaluator are not deleted. - operationId: unstable_evaluators_delete + 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: - - UnstableEvaluators + - UnstableDashboards parameters: - - name: evaluatorId + - name: dashboardId + in: path + required: true + schema: + type: string + - name: placementId in: path - description: Evaluator identifier returned by the evaluator endpoints. required: true schema: type: string @@ -7392,7 +7454,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/unstableDeleteEvaluatorResponse' + $ref: '#/components/schemas/unstableDashboardPlacement' '400': description: '' content: @@ -7418,19 +7480,919 @@ paths: content: application/json: schema: {} - '409': + '429': description: '' content: application/json: schema: $ref: '#/components/schemas/unstablePublicApiError' - '429': + '500': description: '' content: application/json: schema: $ref: '#/components/schemas/unstablePublicApiError' - '500': + 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/evaluation-rules: + post: + description: >- + Create an evaluation rule. + + + An evaluation rule defines **what** incoming data should be evaluated + and **how prompt variables should be populated** from that data. + + + Use this resource after choosing an evaluator from the evaluator + endpoints. + + + Key rules: + + - `name` must be unique within the project for public evaluation rules + + - `target` must be `observation` or `experiment` + + - `evaluator.name` + `evaluator.scope` must identify an existing + evaluator family returned by the evaluator endpoints + + - Langfuse resolves that family to its latest version before saving the + evaluation rule + + - for `target=experiment`, use dataset `id` values from `GET + /api/public/v2/datasets` when filtering by `datasetId` + + - for `llm_as_judge` evaluators, every evaluator prompt variable must be + mapped exactly once + + - for `code` evaluators, Langfuse uses the fixed code runtime mapping; + omit `mapping` in create and update requests + + - for user-provided `llm_as_judge` mappings, `expected_output` and + `experiment_item_metadata` are only valid for `target=experiment` + + - if `enabled=true`, Langfuse validates that the referenced evaluator + can currently run + + - at most 50 evaluation rules can be effectively active in one project + at the same time + + + If an evaluation rule with the same `name` already exists in the + project, the API returns `409`. + + In that case, update the existing resource with `PATCH + /api/public/unstable/evaluation-rules/{evaluationRuleId}` instead of + creating a second one. + + + If enabling this resource would exceed the 50-active limit, the API also + returns `409`. + + In that case, disable or pause another active evaluation rule before + enabling a new one. + + + Current scope: + + - evaluation rules are live-ingestion rules only + + - they do not trigger historical backfills + + + Recovery guidance: + + - `400 invalid_filter_value`: fix the filter `column` or `value` using + `details.column`, `details.invalidValues`, and `details.allowedValues` + + - `400 invalid_filter_value` with `details.column=datasetId`: call `GET + /api/public/v2/datasets`, then retry with dataset `id` values from that + response + + - `400 missing_variable_mapping`: for `llm_as_judge` evaluators, fetch + the evaluator again and make sure every variable in `variables` appears + exactly once in `mapping` + + - `400 duplicate_variable_mapping`: remove repeated mappings for the + same variable + + - `400 invalid_variable_mapping`: for `llm_as_judge`, switch to a valid + `source` for the selected `target`, or fix the variable name + + - `400 invalid_json_path`: remove or correct the `jsonPath` + + - `422 evaluator_preflight_failed`: the selected evaluator cannot run + with the resolved model configuration. Fix the evaluator/default model + setup, then retry the create request. + operationId: unstable_evaluationRules_create + tags: + - UnstableEvaluationRules + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '422': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateEvaluationRuleRequest' + get: + description: >- + List evaluation rules in the authenticated project. + + + This includes legacy `trace` and `dataset` rules so they can be + inspected and migrated to v4 rules. Legacy rules are read-only through + this API; create, update, and delete continue to support only + `observation` and `experiment` rules. + operationId: unstable_evaluationRules_list + tags: + - UnstableEvaluationRules + parameters: + - name: page + in: query + description: 1-based page number. Defaults to `1`. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: Maximum number of items per page. Defaults to `50`. + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluationRules' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/evaluation-rules/{evaluationRuleId}: + get: + description: >- + Get one evaluation rule by its identifier. + + + Use this endpoint to inspect the current evaluator, target, mapping, + filters, execution timing, and effective runtime status. Legacy `trace` + and `dataset` rules are returned for migration and are read-only through + this API. + operationId: unstable_evaluationRules_get + tags: + - UnstableEvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: >- + Evaluation rule identifier returned by the evaluation rule endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableReadableEvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + patch: + description: >- + Update an evaluation rule. + + + Typical uses: + + - enable or disable live execution + + - switch to another evaluator + + - adjust sampling + + - change filters + + - update LLM-as-judge variable mappings + + + Important behavior: + + - provide only the fields you want to change + + - if you provide `evaluator`, Langfuse resolves that evaluator family to + its latest version before saving + + - changing `target`, `filter`, or an LLM-as-judge `mapping` must still + produce a valid target-specific configuration + + - if you change `target` for an LLM-as-judge rule, also send a + compatible `filter` and `mapping` in the same request unless the + existing ones are still valid for the new target + + - for `code` evaluator rules, omit `mapping`; Langfuse stores the fixed + code runtime mapping automatically + + - if the resulting config is enabled, Langfuse re-validates that the + selected evaluator can run + + - if the update would move a non-active evaluation rule into the active + state and the project already has 50 active evaluation rules, the API + returns `409` + + + Recovery guidance: + + - if an LLM-as-judge update fails with `missing_variable_mapping` or + `invalid_variable_mapping` after changing `evaluator` or `target`, + resend the request with a complete new `mapping` + + - if the update fails with `invalid_filter_value` after changing + `target`, resend the request with a target-compatible `filter` + operationId: unstable_evaluationRules_update + tags: + - UnstableEvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: Evaluation rule identifier. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluationRule' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '422': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableUpdateEvaluationRuleRequest' + delete: + description: >- + Delete an evaluation rule. + + + This removes the live-ingestion rule only. It does not delete the + referenced evaluator. + operationId: unstable_evaluationRules_delete + tags: + - UnstableEvaluationRules + parameters: + - name: evaluationRuleId + in: path + description: Evaluation rule identifier. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteEvaluationRuleResponse' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/evaluators: + post: + description: >- + Create an evaluator in the authenticated project. + + + Use evaluators to define **how** Langfuse should score data. + + LLM-as-a-judge evaluators define a prompt, expected structured output, + and optional model configuration. + + Code evaluators define source code and a runtime language. + + + Naming behavior: + + - If this is a new evaluator name in your project, Langfuse creates + version `1`. + + - If the name already exists in your project, Langfuse creates the next + version and returns it. + + - When a new project version is created, existing evaluation rules in + that project automatically move to the newest version for that evaluator + name. + + + Recommended workflow: + + 1. Create the evaluator. + + 2. Read the returned `variables` array. + + 3. Read the returned `outputDefinition.dataType` so the client knows + whether future scores will be numeric, boolean, or categorical. + + 4. Create one or more evaluation rules that reference the returned + evaluator family using `name` and `scope`. + + + Code evaluator validation: + + - At creation, Langfuse only validates the request shape + + - The `sourceCode` itself is not executed here. It is first run + (preflight-tested against a sample observation) when you link the + evaluator to an evaluation rule, so runtime errors in the code surface + at evaluation-rule creation, not at evaluator creation. + + + Recovery guidance: + + - `422` with `code=evaluator_preflight_failed`: the evaluator cannot run + with the resolved model configuration. Add a valid explicit + `modelConfig`, or configure the project's default evaluation model, then + retry the same request. + + - `400` with `code=invalid_body`: the request shape is malformed. Use + the structured `details.issues` array to fix the specific fields and + retry. + + - `400` with `code=invalid_body` on `outputDefinition`: for + `type=llm_as_judge`, send `dataType`, `reasoning.description`, and + `score.description`. Do not send `version`; it is not part of the public + request shape. + + - If `type` is omitted, Langfuse treats the request as + `type=llm_as_judge` for backwards compatibility. New clients should send + `type` explicitly. + + + Unstable API note: + + - This surface may evolve while the underlying evaluation data model is + being redesigned. + operationId: unstable_evaluators_create + tags: + - UnstableEvaluators + parameters: [] + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '409': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '422': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/unstableCreateEvaluatorRequest' + get: + description: >- + List the evaluators available to the authenticated project. + + + Important behavior: + + - This endpoint returns the latest version of each available evaluator. + + - Results can include evaluators from your project and Langfuse-managed + evaluators. + + - If the same evaluator name exists in both places, both are returned as + separate items with different `scope` values. + operationId: unstable_evaluators_list + tags: + - UnstableEvaluators + parameters: + - name: page + in: query + description: 1-based page number. Defaults to `1`. + required: false + schema: + type: integer + nullable: true + - name: limit + in: query + description: Maximum number of items per page. Defaults to `50`. + required: false + schema: + type: integer + nullable: true + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluators' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + /api/public/unstable/evaluators/{evaluatorId}: + get: + description: >- + Get one evaluator by `id`. + + + Use this endpoint when you want the prompt, output definition, model + configuration, and derived variables for the evaluator you plan to use + in an evaluation rule. + operationId: unstable_evaluators_get + tags: + - UnstableEvaluators + parameters: + - name: evaluatorId + in: path + description: Evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableEvaluator' + '400': + description: '' + content: + application/json: + schema: {} + '401': + description: '' + content: + application/json: + schema: {} + '403': + description: '' + content: + application/json: + schema: {} + '404': + description: '' + content: + application/json: + schema: {} + '405': + description: '' + content: + application/json: + schema: {} + '429': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + '500': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstablePublicApiError' + security: *ref_0 + delete: + description: >- + Delete an evaluator. + + + Important behavior: + + - This deletes the evaluator including all of its stored versions; + `evaluatorId` may reference any version. + + - The API returns `409` while evaluation rules still reference the + evaluator. Delete those evaluation rules first. + + - Langfuse-managed evaluators (`scope=managed`) cannot be deleted; the + API returns `403`. + + - Scores already produced by the evaluator are not deleted. + operationId: unstable_evaluators_delete + tags: + - UnstableEvaluators + parameters: + - name: evaluatorId + in: path + description: Evaluator identifier returned by the evaluator endpoints. + required: true + schema: + type: string + responses: + '200': + description: '' + content: + application/json: + schema: + $ref: '#/components/schemas/unstableDeleteEvaluatorResponse' + '400': + description: '' + content: + application/json: + schema: {} + '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: @@ -7631,6 +8593,13 @@ components: - 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 @@ -7639,10 +8608,7 @@ components: - CSV - JSONL - PARQUET - description: >- - File type reported for an existing integration. Includes `PARQUET`, - which a project may enable through the Langfuse UI but cannot yet be set - via this API (the request `fileType` omits it). + description: File type reported for an existing integration. BlobStorageExportMode: title: BlobStorageExportMode type: string @@ -8063,6 +9029,37 @@ components: required: - data - meta + Deprecation: + title: Deprecation + type: object + description: >- + Migration signal returned by deprecated endpoints. Optional fields are + omitted when they have no value. + properties: + message: + type: string + description: >- + Human- and agent-readable summary of the deprecation and its + replacement. + replacement: + type: string + nullable: true + description: >- + The replacement endpoint, e.g. "GET /api/public/v2/observations". + Omitted when the endpoint is being removed without a direct + replacement. + docsUrl: + type: string + nullable: true + description: Link to the migration documentation (markdown), when available. + sunsetAt: + type: string + nullable: true + description: >- + ISO date after which the endpoint may stop working, when a removal + date is committed. + required: + - message Trace: title: Trace type: object @@ -8188,6 +9185,9 @@ components: items: $ref: '#/components/schemas/ScoreV1' description: List of scores + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true required: - htmlPath - observations @@ -8221,6 +9221,9 @@ components: type: array items: $ref: '#/components/schemas/Trace' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true required: - traces allOf: @@ -8414,6 +9417,15 @@ components: - timeToFirstToken allOf: - $ref: '#/components/schemas/Observation' + ObservationsViewSingle: + title: ObservationsViewSingle + type: object + properties: + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true + allOf: + - $ref: '#/components/schemas/ObservationsView' ObservationV2: title: ObservationV2 type: object @@ -8445,10 +9457,22 @@ components: parentObservationId: type: string nullable: true - description: The parent observation ID + description: >- + The physical parent observation ID, if present. + + Observations marked as app roots by the SDK may retain a non-null + parent ID. type: type: string description: The type of the observation (e.g. GENERATION, SPAN, EVENT) + isRootObservation: + type: boolean + nullable: true + description: >- + Whether this observation is a logical root. + + This is true for observations without a physical parent and + observations marked as app roots by the SDK. name: type: string nullable: true @@ -8727,24 +9751,184 @@ components: label: type: string required: - - value - - label - BaseScoreV1: - title: BaseScoreV1 + - value + - label + BaseScoreV1: + title: BaseScoreV1 + type: object + properties: + id: + type: string + traceId: + type: string + name: + type: string + source: + $ref: '#/components/schemas/ScoreSource' + observationId: + type: string + nullable: true + description: The observation ID associated with the score + timestamp: + type: string + format: date-time + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + authorUserId: + type: string + nullable: true + description: The user ID of the author + comment: + type: string + nullable: true + description: Comment on the score + metadata: + description: Metadata associated with the score + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. When set, config and score name + must be equal and value must comply to optionally defined numerical + range + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + environment: + type: string + description: >- + The environment from which this score originated. Can be any + lowercase alphanumeric string with hyphens and underscores that does + not start with 'langfuse'. + required: + - id + - traceId + - name + - source + - timestamp + - createdAt + - updatedAt + - authorUserId + - comment + - metadata + - configId + - queueId + - environment + NumericScoreV1: + title: NumericScoreV1 + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + BooleanScoreV1: + title: BooleanScoreV1 + type: object + properties: + value: + type: number + format: double + description: >- + The numeric value of the score. Equals 1 for "True" and 0 for "False" + stringValue: + type: string + description: >- + The string representation of the score value. Is inferred from the + numeric value and equals "True" or "False" + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + CategoricalScoreV1: + title: CategoricalScoreV1 + type: object + properties: + value: + type: number + format: double + description: >- + Represents the numeric category mapping of the stringValue. If no + config is linked, defaults to 0. + stringValue: + type: string + description: >- + The string representation of the score value. If no config is + linked, can be any string. Otherwise, must map to a config category + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + TextScoreV1: + title: TextScoreV1 + type: object + properties: + stringValue: + type: string + description: The text content of the score (1-500 characters) + required: + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScoreV1' + ScoreV1: + title: ScoreV1 + type: object + properties: + dataType: + type: string + enum: + - NUMERIC + - CATEGORICAL + - BOOLEAN + - TEXT + value: + type: string + description: The numeric value of the score + 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: + - dataType + BaseScore: + title: BaseScore type: object properties: id: type: string traceId: type: string - name: + nullable: true + description: The trace ID associated with the score + sessionId: type: string - source: - $ref: '#/components/schemas/ScoreSource' + nullable: true + description: The session ID associated with the score observationId: type: string nullable: true description: The observation ID associated with the score + datasetRunId: + type: string + nullable: true + description: The dataset run ID associated with the score + name: + type: string + source: + $ref: '#/components/schemas/ScoreSource' timestamp: type: string format: date-time @@ -8785,7 +9969,6 @@ components: not start with 'langfuse'. required: - id - - traceId - name - source - timestamp @@ -8797,8 +9980,8 @@ components: - configId - queueId - environment - NumericScoreV1: - title: NumericScoreV1 + NumericScore: + title: NumericScore type: object properties: value: @@ -8808,9 +9991,9 @@ components: required: - value allOf: - - $ref: '#/components/schemas/BaseScoreV1' - BooleanScoreV1: - title: BooleanScoreV1 + - $ref: '#/components/schemas/BaseScore' + BooleanScore: + title: BooleanScore type: object properties: value: @@ -8827,9 +10010,9 @@ components: - value - stringValue allOf: - - $ref: '#/components/schemas/BaseScoreV1' - CategoricalScoreV1: - title: CategoricalScoreV1 + - $ref: '#/components/schemas/BaseScore' + CategoricalScore: + title: CategoricalScore type: object properties: value: @@ -8847,9 +10030,25 @@ components: - value - stringValue allOf: - - $ref: '#/components/schemas/BaseScoreV1' - TextScoreV1: - title: TextScoreV1 + - $ref: '#/components/schemas/BaseScore' + CorrectionScore: + title: CorrectionScore + type: object + properties: + value: + type: number + format: double + description: The numeric value of the score. Always 0 for correction scores. + stringValue: + type: string + description: The string representation of the correction content + required: + - value + - stringValue + allOf: + - $ref: '#/components/schemas/BaseScore' + TextScore: + title: TextScore type: object properties: stringValue: @@ -8858,9 +10057,9 @@ components: required: - stringValue allOf: - - $ref: '#/components/schemas/BaseScoreV1' - ScoreV1: - title: ScoreV1 + - $ref: '#/components/schemas/BaseScore' + Score: + title: Score type: object properties: dataType: @@ -8869,6 +10068,7 @@ components: - NUMERIC - CATEGORICAL - BOOLEAN + - CORRECTION - TEXT value: type: string @@ -8879,2133 +10079,2596 @@ components: linked, can be any string. Otherwise, must map to a config category required: - dataType - BaseScore: - title: BaseScore + CreateScoreValue: + title: CreateScoreValue + oneOf: + - type: number + format: double + - type: string + description: >- + The value of the score. Must be passed as string for categorical and + text scores, and numeric for boolean and numeric scores + Comment: + title: Comment + type: object + properties: + id: + type: string + projectId: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + objectType: + $ref: '#/components/schemas/CommentObjectType' + objectId: + type: string + content: + type: string + authorUserId: + type: string + nullable: true + description: The user ID of the comment author + required: + - id + - projectId + - createdAt + - updatedAt + - objectType + - objectId + - content + Dataset: + title: Dataset + type: object + properties: + id: + type: string + name: + type: string + description: + type: string + nullable: true + description: Description of the dataset + metadata: + description: Metadata associated with the dataset + inputSchema: + nullable: true + description: JSON Schema for validating dataset item inputs + expectedOutputSchema: + nullable: true + description: JSON Schema for validating dataset item expected outputs + projectId: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + required: + - id + - name + - description + - metadata + - inputSchema + - expectedOutputSchema + - projectId + - createdAt + - updatedAt + DatasetItem: + title: DatasetItem + type: object + properties: + id: + type: string + status: + $ref: '#/components/schemas/DatasetStatus' + input: + description: Input data for the dataset item + expectedOutput: + description: Expected output for the dataset item + metadata: + description: Metadata associated with the dataset item + sourceTraceId: + type: string + nullable: true + description: The trace ID that sourced this dataset item + sourceObservationId: + type: string + nullable: true + description: The observation ID that sourced this dataset item + datasetId: + type: string + datasetName: + type: string + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + mediaReferences: + type: array + items: + $ref: '#/components/schemas/DatasetItemMediaReference' + description: >- + Resolved Langfuse media references found in input, expectedOutput, + and metadata. + required: + - id + - status + - input + - expectedOutput + - metadata + - sourceTraceId + - sourceObservationId + - datasetId + - datasetName + - createdAt + - updatedAt + - mediaReferences + DatasetItemMediaReference: + title: DatasetItemMediaReference + type: object + properties: + field: + $ref: '#/components/schemas/DatasetItemMediaReferenceField' + description: The dataset item field containing the reference + referenceString: + type: string + description: >- + The Langfuse media reference string, e.g. + `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@` + jsonPath: + type: string + description: >- + JSONPath of the string holding the reference within the field, e.g. + `$['image']` + media: + $ref: '#/components/schemas/DatasetItemMediaReferenceMedia' + description: The resolved media record. + required: + - field + - referenceString + - jsonPath + - media + DatasetItemMediaReferenceField: + title: DatasetItemMediaReferenceField + type: string + enum: + - input + - expectedOutput + - metadata + DatasetItemMediaReferenceMedia: + title: DatasetItemMediaReferenceMedia + type: object + properties: + mediaId: + type: string + description: The unique langfuse identifier of the media record + contentType: + type: string + description: The MIME type of the media record + contentLength: + type: integer + description: The size of the media record in bytes + url: + type: string + description: The signed download URL of the media record + urlExpiry: + type: string + description: The expiry date and time of the download URL + required: + - mediaId + - contentType + - contentLength + - url + - urlExpiry + DatasetRunItem: + title: DatasetRunItem type: object properties: id: type: string - traceId: - type: string - nullable: true - description: The trace ID associated with the score - sessionId: + datasetRunId: type: string - nullable: true - description: The session ID associated with the score - observationId: + datasetRunName: type: string - nullable: true - description: The observation ID associated with the score - datasetRunId: + datasetItemId: type: string - nullable: true - description: The dataset run ID associated with the score - name: + traceId: type: string - source: - $ref: '#/components/schemas/ScoreSource' - timestamp: + observationId: type: string - format: date-time + nullable: true + description: The observation ID associated with this run item createdAt: type: string format: date-time updatedAt: type: string format: date-time - authorUserId: + required: + - id + - datasetRunId + - datasetRunName + - datasetItemId + - traceId + - observationId + - createdAt + - updatedAt + DatasetRun: + title: DatasetRun + type: object + properties: + id: type: string - nullable: true - description: The user ID of the author - comment: + description: Unique identifier of the dataset run + name: + type: string + description: Name of the dataset run + description: type: string nullable: true - description: Comment on the score + description: Description of the run metadata: - description: Metadata associated with the score - configId: + description: Metadata of the dataset run + datasetId: 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: Id of the associated dataset + datasetName: type: string - nullable: true - description: >- - The annotation queue referenced by the score. Indicates if score was - initially created while processing annotation queue. - environment: + description: Name of the associated dataset + createdAt: 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'. + 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 - - source - - timestamp + - description + - metadata + - datasetId + - datasetName - createdAt - updatedAt - - authorUserId - - comment - - metadata - - configId - - queueId - - environment - NumericScore: - title: NumericScore + DatasetRunWithItems: + title: DatasetRunWithItems type: object properties: - value: - type: number - format: double - description: The numeric value of the score + datasetRunItems: + type: array + items: + $ref: '#/components/schemas/DatasetRunItem' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true required: - - value + - datasetRunItems allOf: - - $ref: '#/components/schemas/BaseScore' - BooleanScore: - title: BooleanScore + - $ref: '#/components/schemas/DatasetRun' + Model: + title: Model type: object + description: >- + Model definition used for transforming usage into USD cost and/or + tokenization. + + + Models can have either simple flat pricing or tiered pricing: + + - Flat pricing: Single price per usage type (legacy, but still + supported) + + - Tiered pricing: Multiple pricing tiers with conditional matching based + on usage patterns + + + The pricing tiers approach is recommended for models with usage-based + pricing variations. + + When using tiered pricing, the flat price fields (inputPrice, + outputPrice, prices) are populated + + from the default tier for backward compatibility. properties: - value: + id: + type: string + modelName: + type: string + description: >- + Name of the model definition. If multiple with the same name exist, + they are applied in the following order: (1) custom over built-in, + (2) newest according to startTime where + model.startTime- + Regex pattern which matches this model definition to + generation.model. Useful in case of fine-tuned models. If you want + to exact match, use `(?i)^modelname$` + startDate: + type: string + format: date-time + nullable: true + description: Apply only to generations which are newer than this ISO date. + unit: + $ref: '#/components/schemas/ModelUsageUnit' + nullable: true + description: Unit used by this model. + inputPrice: + type: number + format: double + nullable: true + description: Deprecated. See 'prices' instead. Price (USD) per input unit + outputPrice: + type: number + format: double + nullable: true + description: Deprecated. See 'prices' instead. Price (USD) per output unit + totalPrice: type: number format: double + nullable: true description: >- - The numeric value of the score. Equals 1 for "True" and 0 for "False" - stringValue: + 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: >- - The string representation of the score value. Is inferred from the - numeric value and equals "True" or "False" + Optional. Tokenizer to be applied to observations which match to + this model. See docs for more details. + tokenizerConfig: + description: >- + Optional. Configuration for the selected tokenizer. Needs to be + JSON. See docs for more details. + isLangfuseManaged: + type: boolean + createdAt: + type: string + format: date-time + description: Timestamp when the model was created + prices: + type: object + additionalProperties: + $ref: '#/components/schemas/ModelPrice' + description: >- + Deprecated. Use 'pricingTiers' instead for models with usage-based + pricing variations. + + + This field shows prices by usage type from the default pricing tier. + Maintained for backward compatibility. + + If the model uses tiered pricing, this field will be populated from + the default tier's prices. + pricingTiers: + type: array + items: + $ref: '#/components/schemas/PricingTier' + description: >- + Array of pricing tiers with conditional pricing based on usage + thresholds. + + + Pricing tiers enable accurate cost tracking for models that charge + different rates based on usage patterns + + (e.g., different rates for high-volume usage, large context windows, + or cached tokens). + + + Each model must have exactly one default tier (isDefault=true, + priority=0) that serves as a fallback. + + Additional conditional tiers can be defined with specific matching + criteria. + + + If this array is empty, the model uses legacy flat pricing from the + inputPrice/outputPrice/totalPrice fields. required: - - value - - stringValue - allOf: - - $ref: '#/components/schemas/BaseScore' - CategoricalScore: - title: CategoricalScore + - id + - modelName + - matchPattern + - startDate + - inputPrice + - outputPrice + - totalPrice + - tokenizerId + - tokenizerConfig + - isLangfuseManaged + - createdAt + - prices + - pricingTiers + ModelPrice: + title: ModelPrice type: object properties: - value: + price: 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 + - price + PricingTierCondition: + title: PricingTierCondition type: object + description: >- + Condition for matching a pricing tier based on usage details. Used to + implement tiered pricing models where costs vary based on usage + thresholds. + + + How it works: + + 1. The regex pattern matches against usage detail keys (e.g., + "input_tokens", "input_cached") + + 2. Values of all matching keys are summed together + + 3. The sum is compared against the threshold value using the specified + operator + + 4. All conditions in a tier must be met (AND logic) for the tier to + match + + + Common use cases: + + - Threshold-based pricing: Match when accumulated usage exceeds a + certain amount + + - Usage-type-specific pricing: Different rates for cached vs non-cached + tokens, or input vs output + + - Volume-based pricing: Different rates based on total request or token + count properties: + usageDetailPattern: + type: string + description: >- + Regex pattern to match against usage detail keys. All matching keys' + values are summed for threshold comparison. + + + Examples: + + - "^input" matches "input", "input_tokens", "input_cached", etc. + + - "^(input|prompt)" matches both "input_tokens" and "prompt_tokens" + + - "_cache$" matches "input_cache", "output_cache", etc. + + + The pattern is case-insensitive by default. If no keys match, the + sum is treated as zero. + operator: + $ref: '#/components/schemas/PricingTierOperator' + description: >- + Comparison operator to apply between the summed value and the + threshold. + + + - gt: greater than (sum > threshold) + + - gte: greater than or equal (sum >= threshold) + + - lt: less than (sum < threshold) + + - lte: less than or equal (sum <= threshold) + + - eq: equal (sum == threshold) + + - neq: not equal (sum != threshold) value: type: number format: double - description: The numeric value of the score. Always 0 for correction scores. - stringValue: - type: string - description: The string representation of the correction content + description: >- + Threshold value for comparison. For token-based pricing, this is + typically the token count threshold (e.g., 200000 for a 200K token + threshold). + caseSensitive: + type: boolean + description: >- + Whether the regex pattern matching is case-sensitive. Default is + false (case-insensitive matching). required: + - usageDetailPattern + - operator - value - - 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 + - caseSensitive + PricingTier: + title: PricingTier type: object - properties: - dataType: - type: string - enum: - - NUMERIC - - CATEGORICAL - - BOOLEAN - - CORRECTION - - TEXT - value: - type: string - description: The numeric value of the score - 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: - - dataType - CreateScoreValue: - title: CreateScoreValue - oneOf: - - type: number - format: double - - type: string description: >- - The value of the score. Must be passed as string for categorical and - text scores, and numeric for boolean and numeric scores - Comment: - title: Comment - type: object + Pricing tier definition with conditional pricing based on usage + thresholds. + + + Pricing tiers enable accurate cost tracking for LLM providers that + charge different rates based on usage patterns. + + For example, some providers charge higher rates when context size + exceeds certain thresholds. + + + How tier matching works: + + 1. Tiers are evaluated in ascending priority order (priority 1 before + priority 2, etc.) + + 2. The first tier where ALL conditions match is selected + + 3. If no conditional tiers match, the default tier is used as a fallback + + 4. The default tier has priority 0 and no conditions + + + Why priorities matter: + + - Lower priority numbers are evaluated first, allowing you to define + specific cases before general ones + + - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for + "medium usage" (>100K tokens), Priority 0 for default + + - Without proper ordering, a less specific condition might match before + a more specific one + + + Every model must have exactly one default tier to ensure cost + calculation always succeeds. properties: id: type: string - projectId: - type: string - createdAt: - type: string - format: date-time - updatedAt: - type: string - format: date-time - objectType: - $ref: '#/components/schemas/CommentObjectType' - objectId: - type: string - content: - type: string - authorUserId: + description: Unique identifier for the pricing tier + name: type: string - nullable: true - description: The user ID of the comment author + description: >- + Name of the pricing tier for display and identification purposes. + + + Examples: "Standard", "High Volume Tier", "Large Context", "Extended + Context Tier" + isDefault: + type: boolean + description: >- + Whether this is the default tier. Every model must have exactly one + default tier with priority 0 and no conditions. + + + The default tier serves as a fallback when no conditional tiers + match, ensuring cost calculation always succeeds. + + It typically represents the base pricing for standard usage + patterns. + priority: + type: integer + description: >- + Priority for tier matching evaluation. Lower numbers = higher + priority (evaluated first). + + + The default tier must always have priority 0. Conditional tiers + should have priority 1, 2, 3, etc. + + + Example ordering: + + - Priority 0: Default tier (no conditions, always matches as + fallback) + + - Priority 1: High usage tier (e.g., >200K tokens) + + - Priority 2: Medium usage tier (e.g., >100K tokens) + + + This ensures more specific conditions are checked before general + ones. + conditions: + type: array + items: + $ref: '#/components/schemas/PricingTierCondition' + description: >- + Array of conditions that must ALL be met for this tier to match (AND + logic). + + + The default tier must have an empty conditions array. Conditional + tiers should have one or more conditions + + that define when this tier's pricing applies. + + + Multiple conditions enable complex matching scenarios (e.g., "high + input tokens AND low output tokens"). + prices: + type: object + additionalProperties: + type: number + format: double + description: >- + Prices (USD) by usage type for this tier. + + + Common usage types: "input", "output", "total", "request", "image" + + Prices are specified in USD per unit (e.g., per token, per request, + per second). + + + Example: {"input": 0.000003, "output": 0.000015} means $3 per + million input tokens and $15 per million output tokens. required: - id - - projectId - - createdAt - - updatedAt - - objectType - - objectId - - content - Dataset: - title: Dataset + - name + - isDefault + - priority + - conditions + - prices + PricingTierInput: + title: PricingTierInput type: object + description: >- + Input schema for creating a pricing tier. The tier ID will be + automatically generated server-side. + + + When creating a model with pricing tiers: + + - Exactly one tier must have isDefault=true (the fallback tier) + + - The default tier must have priority=0 and conditions=[] + + - All tier names and priorities must be unique within the model + + - Each tier must define at least one price + + + See PricingTier for detailed information about how tiers work and why + they're useful. properties: - id: - type: string name: type: string - description: - type: string + description: >- + Name of the pricing tier for display and identification purposes. + + + Must be unique within the model. Common patterns: "Standard", "High + Volume Tier", "Extended Context" + isDefault: + type: boolean + description: >- + Whether this is the default tier. Exactly one tier per model must be + marked as default. + + + Requirements for default tier: + + - Must have isDefault=true + + - Must have priority=0 + + - Must have empty conditions array (conditions=[]) + + + The default tier acts as a fallback when no conditional tiers match. + priority: + type: integer + description: >- + Priority for tier matching evaluation. Lower numbers = higher + priority (evaluated first). + + + Must be unique within the model. The default tier must have + priority=0. + + Conditional tiers should use priority 1, 2, 3, etc. based on their + specificity. + conditions: + type: array + items: + $ref: '#/components/schemas/PricingTierCondition' + description: >- + Array of conditions that must ALL be met for this tier to match (AND + logic). + + + The default tier must have an empty array (conditions=[]). + + Conditional tiers should define one or more conditions that specify + when this tier's pricing applies. + + + Each condition specifies a regex pattern, operator, and threshold + value for matching against usage details. + prices: + type: object + additionalProperties: + type: number + format: double + description: >- + Prices (USD) by usage type for this tier. At least one price must be + defined. + + + Common usage types: "input", "output", "total", "request", "image" + + Prices are in USD per unit (e.g., per token). + + + Example: {"input": 0.000003, "output": 0.000015} represents $3 per + million input tokens and $15 per million output tokens. + required: + - name + - isDefault + - priority + - conditions + - prices + PricingTierOperator: + title: PricingTierOperator + type: string + enum: + - gt + - gte + - lt + - lte + - eq + - neq + description: Comparison operators for pricing tier conditions + ModelUsageUnit: + title: ModelUsageUnit + type: string + enum: + - CHARACTERS + - TOKENS + - MILLISECONDS + - SECONDS + - IMAGES + - REQUESTS + description: Unit of usage in Langfuse + ObservationLevel: + title: ObservationLevel + type: string + enum: + - DEBUG + - DEFAULT + - WARNING + - ERROR + MapValue: + title: MapValue + oneOf: + - type: string nullable: true - description: Description of the dataset - metadata: - description: Metadata associated with the dataset - inputSchema: + - type: integer nullable: true - description: JSON Schema for validating dataset item inputs - expectedOutputSchema: + - type: number + format: float nullable: true - description: JSON Schema for validating dataset item expected outputs - projectId: - type: string - createdAt: - type: string - format: date-time - updatedAt: + - type: boolean + nullable: true + - type: array + items: + type: string + nullable: true + CommentObjectType: + title: CommentObjectType + type: string + enum: + - TRACE + - OBSERVATION + - SESSION + - PROMPT + DatasetStatus: + title: DatasetStatus + type: string + enum: + - ACTIVE + - ARCHIVED + ScoreSource: + title: ScoreSource + type: string + enum: + - ANNOTATION + - API + - EVAL + ScoreConfigDataType: + title: ScoreConfigDataType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + - TEXT + ScoreDataType: + title: ScoreDataType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + - CORRECTION + - TEXT + DeleteDatasetItemResponse: + title: DeleteDatasetItemResponse + type: object + properties: + message: type: string - format: date-time + description: Success message after deletion required: - - id - - name - - description - - metadata - - inputSchema - - expectedOutputSchema - - projectId - - createdAt - - updatedAt - DatasetItem: - title: DatasetItem + - message + CreateDatasetItemRequest: + title: CreateDatasetItemRequest type: object properties: - id: + datasetName: type: string - status: - $ref: '#/components/schemas/DatasetStatus' input: - description: Input data for the dataset item + nullable: true expectedOutput: - description: Expected output for the dataset item + nullable: true metadata: - description: Metadata associated with the dataset item + nullable: true sourceTraceId: type: string nullable: true - description: The trace ID that sourced this dataset item sourceObservationId: type: string nullable: true - description: The observation ID that sourced this dataset item - datasetId: - type: string - datasetName: - type: string - createdAt: - type: string - format: date-time - updatedAt: + id: type: string - format: date-time - mediaReferences: - type: array - items: - $ref: '#/components/schemas/DatasetItemMediaReference' + nullable: true description: >- - Resolved Langfuse media references found in input, expectedOutput, - and metadata. + 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: - - id - - status - - input - - expectedOutput - - metadata - - sourceTraceId - - sourceObservationId - - datasetId - datasetName - - createdAt - - updatedAt - - mediaReferences - DatasetItemMediaReference: - title: DatasetItemMediaReference - type: object - properties: - field: - $ref: '#/components/schemas/DatasetItemMediaReferenceField' - description: The dataset item field containing the reference - referenceString: - type: string - description: >- - The Langfuse media reference string, e.g. - `@@@langfuseMedia:type=image/png|id=...|source=bytes@@@` - jsonPath: - type: string - description: >- - JSONPath of the string holding the reference within the field, e.g. - `$['image']` - media: - $ref: '#/components/schemas/DatasetItemMediaReferenceMedia' - description: The resolved media record. - required: - - field - - referenceString - - jsonPath - - media - DatasetItemMediaReferenceField: - title: DatasetItemMediaReferenceField - type: string - enum: - - input - - expectedOutput - - metadata - DatasetItemMediaReferenceMedia: - title: DatasetItemMediaReferenceMedia + PaginatedDatasetItems: + title: PaginatedDatasetItems 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 + data: + type: array + items: + $ref: '#/components/schemas/DatasetItem' + meta: + $ref: '#/components/schemas/utilsMetaResponse' required: - - mediaId - - contentType - - contentLength - - url - - urlExpiry - DatasetRunItem: - title: DatasetRunItem + - data + - meta + CreateDatasetRunItemRequest: + title: CreateDatasetRunItemRequest type: object properties: - id: - type: string - datasetRunId: + runName: type: string - datasetRunName: + 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 - traceId: - type: string observationId: type: string nullable: true - description: The observation ID associated with this run item - createdAt: + traceId: + type: string + nullable: true + description: >- + traceId should always be provided. For compatibility with older SDK + versions it can also be inferred from the provided observationId. + datasetVersion: type: string format: date-time - updatedAt: + nullable: true + description: >- + ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g., + "2026-01-21T14:35:42Z"). + + Specifies the dataset version to use for this experiment run. + + If provided, the experiment will use dataset items as they existed + at or before this timestamp. + + If not provided, uses the latest version of dataset items. + createdAt: type: string format: date-time + nullable: true + description: >- + Optional timestamp to set the createdAt field of the dataset run + item. If not provided or null, defaults to current timestamp. required: - - id - - datasetRunId - - datasetRunName + - runName - datasetItemId - - traceId - - observationId - - createdAt - - updatedAt - DatasetRun: - title: DatasetRun + PaginatedDatasetRunItems: + title: PaginatedDatasetRunItems type: object properties: - id: - type: string - description: Unique identifier of the dataset run - name: - type: string - description: Name of the dataset run - description: - type: string + data: + type: array + items: + $ref: '#/components/schemas/DatasetRunItem' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' nullable: true - description: Description of the run - metadata: - description: Metadata of the dataset run - datasetId: - type: string - description: Id of the associated dataset - datasetName: - type: string - description: Name of the associated dataset - createdAt: - type: string - format: date-time - description: The date and time when the dataset run was created - updatedAt: - type: string - format: date-time - description: The date and time when the dataset run was last updated required: - - id - - name - - description - - metadata - - datasetId - - datasetName - - createdAt - - updatedAt - DatasetRunWithItems: - title: DatasetRunWithItems + - data + - meta + PaginatedDatasets: + title: PaginatedDatasets type: object properties: - datasetRunItems: + data: type: array items: - $ref: '#/components/schemas/DatasetRunItem' + $ref: '#/components/schemas/Dataset' + meta: + $ref: '#/components/schemas/utilsMetaResponse' required: - - datasetRunItems - allOf: - - $ref: '#/components/schemas/DatasetRun' - Model: - title: Model + - data + - meta + CreateDatasetRequest: + title: CreateDatasetRequest type: object - description: >- - Model definition used for transforming usage into USD cost and/or - tokenization. - - - Models can have either simple flat pricing or tiered pricing: - - - Flat pricing: Single price per usage type (legacy, but still - supported) - - - Tiered pricing: Multiple pricing tiers with conditional matching based - on usage patterns - - - The pricing tiers approach is recommended for models with usage-based - pricing variations. - - When using tiered pricing, the flat price fields (inputPrice, - outputPrice, prices) are populated - - from the default tier for backward compatibility. properties: - id: - type: string - modelName: - type: string - description: >- - Name of the model definition. If multiple with the same name exist, - they are applied in the following order: (1) custom over built-in, - (2) newest according to startTime where - model.startTime- - Regex pattern which matches this model definition to - generation.model. Useful in case of fine-tuned models. If you want - to exact match, use `(?i)^modelname$` - startDate: + description: 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 + metadata: nullable: true - description: Deprecated. See 'prices' instead. Price (USD) per output unit - totalPrice: - type: number - format: double + inputSchema: nullable: true description: >- - Deprecated. See 'prices' instead. Price (USD) per total unit. Cannot - be set if input or output price is set. - tokenizerId: - type: string + 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: >- - Optional. Tokenizer to be applied to observations which match to - this model. See docs for more details. - tokenizerConfig: - description: >- - Optional. Configuration for the selected tokenizer. Needs to be - JSON. See docs for more details. - isLangfuseManaged: - type: boolean - createdAt: - type: string - format: date-time - description: Timestamp when the model was created - prices: - type: object - additionalProperties: - $ref: '#/components/schemas/ModelPrice' - description: >- - Deprecated. Use 'pricingTiers' instead for models with usage-based - pricing variations. - - - This field shows prices by usage type from the default pricing tier. - Maintained for backward compatibility. - - If the model uses tiered pricing, this field will be populated from - the default tier's prices. - pricingTiers: + JSON Schema for validating dataset item expected outputs. When set, + all new and existing dataset items will be validated against this + schema. + required: + - name + PaginatedDatasetRuns: + title: PaginatedDatasetRuns + type: object + properties: + data: type: array items: - $ref: '#/components/schemas/PricingTier' - description: >- - Array of pricing tiers with conditional pricing based on usage - thresholds. - - - Pricing tiers enable accurate cost tracking for models that charge - different rates based on usage patterns - - (e.g., different rates for high-volume usage, large context windows, - or cached tokens). - - - Each model must have exactly one default tier (isDefault=true, - priority=0) that serves as a fallback. - - Additional conditional tiers can be defined with specific matching - criteria. - - - If this array is empty, the model uses legacy flat pricing from the - inputPrice/outputPrice/totalPrice fields. + $ref: '#/components/schemas/DatasetRun' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true required: - - id - - modelName - - matchPattern - - startDate - - inputPrice - - outputPrice - - totalPrice - - tokenizerId - - tokenizerConfig - - isLangfuseManaged - - createdAt - - prices - - pricingTiers - ModelPrice: - title: ModelPrice + - data + - meta + DeleteDatasetRunResponse: + title: DeleteDatasetRunResponse type: object properties: - price: - type: number - format: double + message: + type: string required: - - price - PricingTierCondition: - title: PricingTierCondition + - message + ExperimentsResponse: + title: ExperimentsResponse type: object - description: >- - Condition for matching a pricing tier based on usage details. Used to - implement tiered pricing models where costs vary based on usage - thresholds. - - - How it works: - - 1. The regex pattern matches against usage detail keys (e.g., - "input_tokens", "input_cached") - - 2. Values of all matching keys are summed together - - 3. The sum is compared against the threshold value using the specified - operator - - 4. All conditions in a tier must be met (AND logic) for the tier to - match - - - Common use cases: - - - Threshold-based pricing: Match when accumulated usage exceeds a - certain amount - - - Usage-type-specific pricing: Different rates for cached vs non-cached - tokens, or input vs output - - - Volume-based pricing: Different rates based on total request or token - count properties: - usageDetailPattern: - type: string - description: >- - Regex pattern to match against usage detail keys. All matching keys' - values are summed for threshold comparison. - - - Examples: - - - "^input" matches "input", "input_tokens", "input_cached", etc. - - - "^(input|prompt)" matches both "input_tokens" and "prompt_tokens" - - - "_cache$" matches "input_cache", "output_cache", etc. - - - The pattern is case-insensitive by default. If no keys match, the - sum is treated as zero. - operator: - $ref: '#/components/schemas/PricingTierOperator' - description: >- - Comparison operator to apply between the summed value and the - threshold. - - - - gt: greater than (sum > threshold) - - - gte: greater than or equal (sum >= threshold) - - - lt: less than (sum < threshold) - - - lte: less than or equal (sum <= threshold) - - - eq: equal (sum == threshold) - - - neq: not equal (sum != threshold) - value: - type: number - format: double - description: >- - Threshold value for comparison. For token-based pricing, this is - typically the token count threshold (e.g., 200000 for a 200K token - threshold). - caseSensitive: - type: boolean - description: >- - Whether the regex pattern matching is case-sensitive. Default is - false (case-insensitive matching). + data: + type: array + items: + $ref: '#/components/schemas/Experiment' + meta: + $ref: '#/components/schemas/ExperimentsResponseMeta' required: - - usageDetailPattern - - operator - - value - - caseSensitive - PricingTier: - title: PricingTier + - data + - meta + ExperimentsResponseMeta: + title: ExperimentsResponseMeta + type: object + properties: + cursor: + type: string + nullable: true + description: >- + Versioned base64url cursor for retrieving the next page. Absent when + there are no more results. + Experiment: + title: Experiment type: object - description: >- - Pricing tier definition with conditional pricing based on usage - thresholds. - - - Pricing tiers enable accurate cost tracking for LLM providers that - charge different rates based on usage patterns. - - For example, some providers charge higher rates when context size - exceeds certain thresholds. - - - How tier matching works: - - 1. Tiers are evaluated in ascending priority order (priority 1 before - priority 2, etc.) - - 2. The first tier where ALL conditions match is selected - - 3. If no conditional tiers match, the default tier is used as a fallback - - 4. The default tier has priority 0 and no conditions - - - Why priorities matter: - - - Lower priority numbers are evaluated first, allowing you to define - specific cases before general ones - - - Example: Priority 1 for "high usage" (>200K tokens), Priority 2 for - "medium usage" (>100K tokens), Priority 0 for default - - - Without proper ordering, a less specific condition might match before - a more specific one - - - Every model must have exactly one default tier to ensure cost - calculation always succeeds. properties: id: type: string - description: Unique identifier for the pricing tier name: type: string - description: >- - Name of the pricing tier for display and identification purposes. - - - Examples: "Standard", "High Volume Tier", "Large Context", "Extended - Context Tier" - isDefault: - type: boolean - description: >- - Whether this is the default tier. Every model must have exactly one - default tier with priority 0 and no conditions. - - - The default tier serves as a fallback when no conditional tiers - match, ensuring cost calculation always succeeds. - - It typically represents the base pricing for standard usage - patterns. - priority: + 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: >- - 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: + 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/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/ScoreV3' + nullable: true 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. + Included only when `fields=scores` is requested. Contains scores + directly attached to the experiment. required: - id - name - - isDefault - - priority - - conditions - - prices - PricingTierInput: - title: PricingTierInput + - description + - startTime + - endTime + - itemCount + - datasetId + ExperimentItemsResponse: + title: ExperimentItemsResponse type: object - description: >- - Input schema for creating a pricing tier. The tier ID will be - automatically generated server-side. - - - When creating a model with pricing tiers: - - - Exactly one tier must have isDefault=true (the fallback tier) - - - The default tier must have priority=0 and conditions=[] - - - All tier names and priorities must be unique within the model - - - Each tier must define at least one price - - - See PricingTier for detailed information about how tiers work and why - they're useful. properties: - name: - type: string - description: >- - Name of the pricing tier for display and identification purposes. - - - Must be unique within the model. Common patterns: "Standard", "High - Volume Tier", "Extended Context" - isDefault: - type: boolean - description: >- - Whether this is the default tier. Exactly one tier per model must be - marked as default. - - - Requirements for default tier: - - - Must have isDefault=true - - - Must have priority=0 - - - Must have empty conditions array (conditions=[]) - - - The default tier acts as a fallback when no conditional tiers match. - priority: - type: integer - description: >- - Priority for tier matching evaluation. Lower numbers = higher - priority (evaluated first). - - - Must be unique within the model. The default tier must have - priority=0. - - Conditional tiers should use priority 1, 2, 3, etc. based on their - specificity. - conditions: + data: type: array items: - $ref: '#/components/schemas/PricingTierCondition' - description: >- - Array of conditions that must ALL be met for this tier to match (AND - logic). - - - The default tier must have an empty array (conditions=[]). - - Conditional tiers should define one or more conditions that specify - when this tier's pricing applies. - - - Each condition specifies a regex pattern, operator, and threshold - value for matching against usage details. - prices: + $ref: '#/components/schemas/ExperimentItem' + meta: + $ref: '#/components/schemas/ExperimentsResponseMeta' + required: + - data + - meta + ExperimentItem: + title: ExperimentItem + type: object + properties: + id: + type: string + traceId: + type: string + startTime: + type: string + format: date-time + endTime: + type: string + format: date-time + nullable: true + level: + $ref: '#/components/schemas/ObservationLevel' + environment: + type: string + experimentId: + type: string + experimentName: + type: string + experimentItemId: + type: string + experimentDatasetId: + type: string + nullable: true + description: Included when `fields=dataset` is requested. + experimentItemVersion: + type: string + format: date-time + nullable: true + description: Included when `fields=dataset` is requested. + input: + nullable: true + description: Included when `fields=io` is requested. + output: + nullable: true + description: Included when `fields=io` is requested. + expectedOutput: + nullable: true + description: Included when `fields=io` is requested. + metadata: + type: object + additionalProperties: true + nullable: true + description: Included when `fields=metadata` is requested. + experimentItemMetadata: + type: object + additionalProperties: true + nullable: true + description: Included when `fields=itemMetadata` is requested. + experimentMetadata: type: object - additionalProperties: - type: number - format: double + 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: >- - Prices (USD) by usage type for this tier. At least one price must be - defined. - - - Common usage types: "input", "output", "total", "request", "image" - - Prices are in USD per unit (e.g., per token). - - - Example: {"input": 0.000003, "output": 0.000015} represents $3 per - million input tokens and $15 per million output tokens. + Included only when `fields=scores` is requested. Contains item and + trace scores only; experiment-level scores are returned by the + experiments endpoint. required: - - name - - isDefault - - priority - - conditions - - prices - PricingTierOperator: - title: PricingTierOperator - type: string - enum: - - gt - - gte - - lt - - lte - - eq - - neq - description: Comparison operators for pricing tier conditions - ModelUsageUnit: - title: ModelUsageUnit + - id + - traceId + - startTime + - endTime + - level + - environment + - experimentId + - experimentName + - experimentItemId + FeedbackTargetType: + title: FeedbackTargetType type: string enum: - - CHARACTERS - - TOKENS - - MILLISECONDS - - SECONDS - - IMAGES - - REQUESTS - description: Unit of usage in Langfuse - ObservationLevel: - title: ObservationLevel + - skill + - mcp-tool + - cli + - docs + - public-api + - other + SubmitFeedbackRequest: + title: SubmitFeedbackRequest + type: object + properties: + targetType: + $ref: '#/components/schemas/FeedbackTargetType' + description: Category of the thing the feedback is about. + target: + type: string + description: >- + The specific instance within targetType: the skill name, MCP tool + name, CLI command, API endpoint path, or docs page path (e.g. + 'queryMetrics', '/docs/mcp'). An identifier, not a sentence. Must be + between 1 and 200 characters. + feedback: + type: string + description: >- + Concise feedback text approved by the user. Must be between 1 and + 3000 characters. + goal: + type: string + nullable: true + description: >- + Optional user-approved goal or use case they were trying to achieve. + Must be between 1 and 1500 characters when provided. Do not include + secrets, customer data, trace payloads, or broad unrelated context. + referenceUrl: + type: string + nullable: true + description: >- + Optional HTTP(S) reference URL. Langfuse stores it as text for + triage and does not fetch it. + required: + - targetType + - target + - feedback + SubmitFeedbackResponse: + title: SubmitFeedbackResponse + type: object + properties: + id: + type: string + description: Correlation ID for the submitted feedback. + required: + - id + HealthResponse: + title: HealthResponse + type: object + properties: + version: + type: string + description: Langfuse server version + status: + type: string + required: + - version + - status + IngestionEvent: + title: IngestionEvent + type: object + properties: + type: + type: string + enum: + - trace-create + - score-create + - span-create + - span-update + - generation-create + - generation-update + - event-create + - sdk-log + - observation-create + - observation-update + body: + type: string + required: + - type + - body + ObservationType: + title: ObservationType type: string enum: - - DEBUG - - DEFAULT - - WARNING - - ERROR - MapValue: - title: MapValue + - SPAN + - GENERATION + - EVENT + - AGENT + - TOOL + - CHAIN + - RETRIEVER + - EVALUATOR + - EMBEDDING + - GUARDRAIL + IngestionUsage: + title: IngestionUsage oneOf: - - type: string + - $ref: '#/components/schemas/Usage' + - $ref: '#/components/schemas/OpenAIUsage' + OpenAIUsage: + title: OpenAIUsage + type: object + description: Usage interface of OpenAI for improved compatibility. + properties: + promptTokens: + type: integer nullable: true - - type: integer + completionTokens: + type: integer nullable: true - - type: number - format: float + totalTokens: + type: integer nullable: true - - type: boolean + OptionalObservationBody: + title: OptionalObservationBody + type: object + properties: + traceId: + type: string nullable: true - - type: array - items: - type: string + name: + type: string nullable: true - CommentObjectType: - title: CommentObjectType - type: string - enum: - - TRACE - - OBSERVATION - - SESSION - - PROMPT - DatasetStatus: - title: DatasetStatus - type: string - enum: - - ACTIVE - - ARCHIVED - ScoreSource: - title: ScoreSource - type: string - enum: - - ANNOTATION - - API - - EVAL - ScoreConfigDataType: - title: ScoreConfigDataType - type: string - enum: - - NUMERIC - - BOOLEAN - - CATEGORICAL - - TEXT - ScoreDataType: - title: ScoreDataType - type: string - enum: - - NUMERIC - - BOOLEAN - - CATEGORICAL - - CORRECTION - - TEXT - DeleteDatasetItemResponse: - title: DeleteDatasetItemResponse + startTime: + type: string + format: date-time + nullable: true + metadata: + nullable: true + input: + nullable: true + output: + nullable: true + level: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + statusMessage: + type: string + nullable: true + parentObservationId: + type: string + nullable: true + version: + type: string + nullable: true + environment: + type: string + nullable: true + CreateEventBody: + title: CreateEventBody + type: object + properties: + id: + type: string + nullable: true + allOf: + - $ref: '#/components/schemas/OptionalObservationBody' + UpdateEventBody: + title: UpdateEventBody + type: object + properties: + id: + type: string + required: + - id + allOf: + - $ref: '#/components/schemas/OptionalObservationBody' + CreateSpanBody: + title: CreateSpanBody + type: object + properties: + endTime: + type: string + format: date-time + nullable: true + allOf: + - $ref: '#/components/schemas/CreateEventBody' + UpdateSpanBody: + title: UpdateSpanBody type: object properties: - message: + endTime: type: string - description: Success message after deletion - required: - - message - CreateDatasetItemRequest: - title: CreateDatasetItemRequest + format: date-time + nullable: true + allOf: + - $ref: '#/components/schemas/UpdateEventBody' + CreateGenerationBody: + title: CreateGenerationBody type: object properties: - datasetName: + completionStartTime: type: string - input: + format: date-time nullable: true - expectedOutput: + model: + type: string nullable: true - metadata: + modelParameters: + type: object + additionalProperties: + $ref: '#/components/schemas/MapValue' nullable: true - sourceTraceId: - type: string + usage: + $ref: '#/components/schemas/IngestionUsage' nullable: true - sourceObservationId: - type: string + usageDetails: + $ref: '#/components/schemas/UsageDetails' nullable: true - id: + costDetails: + type: object + additionalProperties: + type: number + format: double + nullable: true + promptName: 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' + promptVersion: + type: integer nullable: true - description: Defaults to ACTIVE for newly created items - required: - - datasetName - PaginatedDatasetItems: - title: PaginatedDatasetItems - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/DatasetItem' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - CreateDatasetRunItemRequest: - title: CreateDatasetRunItemRequest + allOf: + - $ref: '#/components/schemas/CreateSpanBody' + UpdateGenerationBody: + title: UpdateGenerationBody type: object properties: - runName: + completionStartTime: type: string - runDescription: + format: date-time + nullable: true + model: type: string nullable: true - description: Description of the run. If run exists, description will be updated. - metadata: + modelParameters: + type: object + additionalProperties: + $ref: '#/components/schemas/MapValue' nullable: true - description: Metadata of the dataset run, updates run if run already exists - datasetItemId: + usage: + $ref: '#/components/schemas/IngestionUsage' + nullable: true + promptName: type: string - observationId: + nullable: true + usageDetails: + $ref: '#/components/schemas/UsageDetails' + nullable: true + costDetails: + type: object + additionalProperties: + type: number + format: double + nullable: true + promptVersion: + type: integer + nullable: true + allOf: + - $ref: '#/components/schemas/UpdateSpanBody' + ObservationBody: + title: ObservationBody + type: object + properties: + id: type: string nullable: true traceId: type: string nullable: true - description: >- - traceId should always be provided. For compatibility with older SDK - versions it can also be inferred from the provided observationId. - datasetVersion: + type: + $ref: '#/components/schemas/ObservationType' + name: + type: string + nullable: true + startTime: type: string format: date-time nullable: true - description: >- - ISO 8601 timestamp (RFC 3339, Section 5.6) in UTC (e.g., - "2026-01-21T14:35:42Z"). - - Specifies the dataset version to use for this experiment run. - - If provided, the experiment will use dataset items as they existed - at or before this timestamp. - - If not provided, uses the latest version of dataset items. - createdAt: + endTime: type: string format: date-time nullable: true - description: >- - Optional timestamp to set the createdAt field of the dataset run - item. If not provided or null, defaults to current timestamp. - required: - - runName - - datasetItemId - PaginatedDatasetRunItems: - title: PaginatedDatasetRunItems - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/DatasetRunItem' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - PaginatedDatasets: - title: PaginatedDatasets - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/Dataset' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - CreateDatasetRequest: - title: CreateDatasetRequest - type: object - properties: - name: + completionStartTime: type: string - description: + 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 - inputSchema: + output: nullable: true - description: >- - JSON Schema for validating dataset item inputs. When set, all new - and existing dataset items will be validated against this schema. - expectedOutputSchema: + usage: + $ref: '#/components/schemas/Usage' nullable: true - description: >- - JSON Schema for validating dataset item expected outputs. When set, - all new and existing dataset items will be validated against this - schema. - required: - - name - PaginatedDatasetRuns: - title: PaginatedDatasetRuns - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/DatasetRun' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - DeleteDatasetRunResponse: - title: DeleteDatasetRunResponse - type: object - properties: - message: + level: + $ref: '#/components/schemas/ObservationLevel' + nullable: true + statusMessage: type: string - required: - - message - 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 - properties: - cursor: + nullable: true + parentObservationId: type: string nullable: true - description: >- - Versioned base64url cursor for retrieving the next page. Absent when - there are no more results. - Experiment: - title: Experiment + environment: + type: string + nullable: true + required: + - type + TraceBody: + title: TraceBody type: object properties: id: type: string + nullable: true + timestamp: + type: string + format: date-time + nullable: true name: type: string - description: + nullable: true + userId: type: string nullable: true - startTime: + input: + nullable: true + output: + nullable: true + sessionId: 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: + nullable: true + release: 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: + nullable: true + version: 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: + tags: type: array items: - $ref: '#/components/schemas/ScoreV3' + type: string nullable: true - description: >- - Included only when `fields=scores` is requested. Contains scores - directly attached to the experiment. - required: - - id - - name - - description - - startTime - - endTime - - itemCount - - datasetId - ExperimentItemsResponse: - title: ExperimentItemsResponse + environment: + type: string + nullable: true + public: + type: boolean + nullable: true + description: Make trace publicly accessible via url + SDKLogBody: + title: SDKLogBody type: object properties: - data: - type: array - items: - $ref: '#/components/schemas/ExperimentItem' - meta: - $ref: '#/components/schemas/ExperimentsResponseMeta' + log: {} required: - - data - - meta - ExperimentItem: - title: ExperimentItem + - log + ScoreBody: + title: ScoreBody type: object properties: id: type: string + nullable: true traceId: type: string - startTime: - type: string - format: date-time - endTime: - type: string - format: date-time nullable: true - level: - $ref: '#/components/schemas/ObservationLevel' - environment: + sessionId: type: string - experimentId: + nullable: true + observationId: type: string - experimentName: + nullable: true + datasetRunId: type: string - experimentItemId: + nullable: true + name: type: string - experimentDatasetId: + description: >- + The name of the score. Always overrides "output" for correction + scores. + environment: type: string nullable: true - description: Included when `fields=dataset` is requested. - experimentItemVersion: + queueId: 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: + 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 - 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 + dataType: + $ref: '#/components/schemas/ScoreDataType' nullable: true - description: Included when `fields=experimentMetadata` is requested. - experimentDescription: + description: >- + When set, must match the score value's type. If not set, will be + inferred from the score value or config + configId: type: string nullable: true - description: 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. + 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: - - id - - traceId - - startTime - - endTime - - level - - environment - - experimentId - - experimentName - - experimentItemId - HealthResponse: - title: HealthResponse + - name + - value + BaseEvent: + title: BaseEvent type: object properties: - version: + id: type: string - description: Langfuse server version - status: + description: UUID v4 that identifies the event + timestamp: type: string + description: >- + Datetime (ISO 8601) of event creation in client. Should be as close + to actual event creation in client as possible, this timestamp will + be used for ordering of events in future release. Resolution: + milliseconds (required), microseconds (optimal). + metadata: + nullable: true + description: Optional. Metadata field used by the Langfuse SDKs for debugging. required: - - version - - status - IngestionEvent: - title: IngestionEvent + - id + - timestamp + TraceEvent: + title: TraceEvent + type: object + properties: + body: + $ref: '#/components/schemas/TraceBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateObservationEvent: + title: CreateObservationEvent + type: object + properties: + body: + $ref: '#/components/schemas/ObservationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateObservationEvent: + title: UpdateObservationEvent + type: object + properties: + body: + $ref: '#/components/schemas/ObservationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + ScoreEvent: + title: ScoreEvent + type: object + properties: + body: + $ref: '#/components/schemas/ScoreBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + SDKLogEvent: + title: SDKLogEvent + type: object + properties: + body: + $ref: '#/components/schemas/SDKLogBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateGenerationEvent: + title: CreateGenerationEvent + type: object + properties: + body: + $ref: '#/components/schemas/CreateGenerationBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateGenerationEvent: + title: UpdateGenerationEvent type: object properties: - type: - type: string - enum: - - trace-create - - score-create - - span-create - - span-update - - generation-create - - generation-update - - event-create - - sdk-log - - observation-create - - observation-update body: - type: string + $ref: '#/components/schemas/UpdateGenerationBody' required: - - type - body - 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 + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateSpanEvent: + title: CreateSpanEvent type: object - description: Usage interface of OpenAI for improved compatibility. properties: - promptTokens: - type: integer - nullable: true - completionTokens: - type: integer - nullable: true - totalTokens: - type: integer - nullable: true - OptionalObservationBody: - title: OptionalObservationBody + body: + $ref: '#/components/schemas/CreateSpanBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + UpdateSpanEvent: + title: UpdateSpanEvent type: object properties: - traceId: - type: string - nullable: true - name: - type: string - nullable: true - startTime: - type: string - format: date-time - nullable: true - metadata: - nullable: true - input: - nullable: true - output: - nullable: true - level: - $ref: '#/components/schemas/ObservationLevel' - nullable: true - statusMessage: - type: string - nullable: true - parentObservationId: - type: string - nullable: true - version: - type: string - nullable: true - environment: - type: string - nullable: true - CreateEventBody: - title: CreateEventBody + body: + $ref: '#/components/schemas/UpdateSpanBody' + required: + - body + allOf: + - $ref: '#/components/schemas/BaseEvent' + CreateEventEvent: + title: CreateEventEvent type: object properties: - id: - type: string - nullable: true + body: + $ref: '#/components/schemas/CreateEventBody' + required: + - body allOf: - - $ref: '#/components/schemas/OptionalObservationBody' - UpdateEventBody: - title: UpdateEventBody + - $ref: '#/components/schemas/BaseEvent' + IngestionSuccess: + title: IngestionSuccess type: object properties: id: type: string + status: + type: integer required: - id - allOf: - - $ref: '#/components/schemas/OptionalObservationBody' - CreateSpanBody: - title: CreateSpanBody + - status + IngestionError: + title: IngestionError type: object properties: - endTime: + id: + type: string + status: + type: integer + message: type: string - format: date-time nullable: true - allOf: - - $ref: '#/components/schemas/CreateEventBody' - UpdateSpanBody: - title: UpdateSpanBody + error: + nullable: true + required: + - id + - status + IngestionResponse: + title: IngestionResponse type: object properties: - endTime: - type: string - format: date-time - nullable: true - allOf: - - $ref: '#/components/schemas/UpdateEventBody' - CreateGenerationBody: - title: CreateGenerationBody + successes: + type: array + items: + $ref: '#/components/schemas/IngestionSuccess' + errors: + type: array + items: + $ref: '#/components/schemas/IngestionError' + required: + - successes + - errors + OpenAICompletionUsageSchema: + title: OpenAICompletionUsageSchema type: object + description: OpenAI Usage schema from (Chat-)Completion APIs properties: - completionStartTime: - type: string - format: date-time - nullable: true - model: - type: string - nullable: true - modelParameters: + prompt_tokens: + type: integer + completion_tokens: + type: integer + total_tokens: + type: integer + prompt_tokens_details: type: object additionalProperties: - $ref: '#/components/schemas/MapValue' - nullable: true - usage: - $ref: '#/components/schemas/IngestionUsage' - nullable: true - usageDetails: - $ref: '#/components/schemas/UsageDetails' + type: integer + nullable: true nullable: true - costDetails: + completion_tokens_details: type: object additionalProperties: - type: number - format: double - nullable: true - promptName: - type: string - nullable: true - promptVersion: - type: integer + type: integer + nullable: true nullable: true - allOf: - - $ref: '#/components/schemas/CreateSpanBody' - UpdateGenerationBody: - title: UpdateGenerationBody + required: + - prompt_tokens + - completion_tokens + - total_tokens + OpenAIResponseUsageSchema: + title: OpenAIResponseUsageSchema type: object + description: OpenAI Usage schema from Response API properties: - completionStartTime: - type: string - format: date-time - nullable: true - model: - type: string - nullable: true - modelParameters: + input_tokens: + type: integer + output_tokens: + type: integer + total_tokens: + type: integer + input_tokens_details: type: object additionalProperties: - $ref: '#/components/schemas/MapValue' - nullable: true - usage: - $ref: '#/components/schemas/IngestionUsage' - nullable: true - promptName: - type: string - nullable: true - usageDetails: - $ref: '#/components/schemas/UsageDetails' + type: integer + nullable: true nullable: true - costDetails: + output_tokens_details: type: object additionalProperties: - type: number - format: double + type: integer + nullable: true + nullable: true + required: + - input_tokens + - output_tokens + - total_tokens + UsageDetails: + title: UsageDetails + oneOf: + - type: object + additionalProperties: + type: integer + - $ref: '#/components/schemas/OpenAICompletionUsageSchema' + - $ref: '#/components/schemas/OpenAIResponseUsageSchema' + legacyMetricsResponse: + title: legacyMetricsResponse + type: object + properties: + data: + type: array + items: + type: object + additionalProperties: true + description: >- + The metrics data. Each item in the list contains the metric values + and dimensions requested in the query. + + Format varies based on the query parameters. + + Histograms will return an array with [lower, upper, height] tuples. + _deprecation: + $ref: '#/components/schemas/Deprecation' nullable: true - promptVersion: - type: integer + required: + - data + legacyObservations: + title: legacyObservations + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Observation' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + legacyObservationsViews: + title: legacyObservationsViews + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/ObservationsView' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' nullable: true - allOf: - - $ref: '#/components/schemas/UpdateSpanBody' - ObservationBody: - title: ObservationBody + required: + - data + - meta + LlmConnection: + title: LlmConnection type: object + description: LLM API connection configuration (secrets excluded) properties: id: type: string - nullable: true - traceId: + provider: type: string - nullable: true - type: - $ref: '#/components/schemas/ObservationType' - name: + description: >- + Provider name (e.g., 'openai', 'my-gateway'). Must be unique in + project, used for upserting. + adapter: type: string - nullable: true - startTime: + description: The adapter used to interface with the LLM + displaySecretKey: + type: string + description: Masked version of the secret key for display purposes + baseURL: type: string - format: date-time nullable: true - endTime: + description: Custom base URL for the LLM API + customModels: + type: array + items: + type: string + description: List of custom model names available for this connection + withDefaultModels: + type: boolean + description: Whether to include default models for this adapter + extraHeaderKeys: + type: array + items: + type: string + description: >- + Keys of extra headers sent with requests (values excluded for + security) + config: + type: object + additionalProperties: true + nullable: true + description: >- + Adapter-specific configuration. Required for Bedrock + (`{"region":"us-east-1"}`), optional for OpenAI + (`{"useResponsesApi":true}`), optional for VertexAI + (`{"location":"us-central1"}`), not used by other adapters. + createdAt: type: string format: date-time - nullable: true - completionStartTime: + updatedAt: type: string format: date-time - nullable: true - model: + required: + - id + - provider + - adapter + - displaySecretKey + - customModels + - withDefaultModels + - extraHeaderKeys + - createdAt + - updatedAt + PaginatedLlmConnections: + title: PaginatedLlmConnections + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/LlmConnection' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + UpsertLlmConnectionRequest: + title: UpsertLlmConnectionRequest + type: object + description: Request to create or update an LLM connection (upsert) + properties: + provider: type: string - nullable: true - modelParameters: - type: object - additionalProperties: - $ref: '#/components/schemas/MapValue' - nullable: true - input: - nullable: true - version: + description: >- + Provider name (e.g., 'openai', 'my-gateway'). Must be unique in + project, used for upserting. + adapter: + $ref: '#/components/schemas/LlmAdapter' + description: The adapter used to interface with the LLM + secretKey: + type: string + description: Secret key for the LLM API. + baseURL: type: string nullable: true - metadata: - nullable: true - output: - nullable: true - usage: - $ref: '#/components/schemas/Usage' - nullable: true - level: - $ref: '#/components/schemas/ObservationLevel' + description: Custom base URL for the LLM API + customModels: + type: array + items: + type: string nullable: true - statusMessage: - type: string + description: List of custom model names + withDefaultModels: + type: boolean nullable: true - parentObservationId: - type: string + description: Whether to include default models. Default is true. + extraHeaders: + type: object + additionalProperties: + type: string nullable: true - environment: - type: string + description: Extra headers to send with requests + config: + type: object + additionalProperties: true nullable: true + description: >- + Adapter-specific configuration. Validation rules: - **Bedrock**: + Required. Must be `{"region": ""}` (e.g., + `{"region":"us-east-1"}`) - **OpenAI**: Optional. If provided, must + be `{"useResponsesApi": }` to control whether Langfuse + routes calls through OpenAI's Responses API. - **VertexAI**: + Optional. If provided, must be `{"location": ""}` + (e.g., `{"location":"us-central1"}`) - **Other adapters**: Not + supported. Omit this field or set to null. required: - - type - TraceBody: - title: TraceBody + - provider + - adapter + - secretKey + DeleteLlmConnectionResponse: + title: DeleteLlmConnectionResponse type: object properties: - id: - type: string - nullable: true - timestamp: + message: type: string - format: date-time - nullable: true - name: + required: + - message + LlmAdapter: + title: LlmAdapter + type: string + enum: + - anthropic + - openai + - azure + - bedrock + - google-vertex-ai + - google-ai-studio + GetMediaResponse: + title: GetMediaResponse + type: object + properties: + mediaId: type: string - nullable: true - userId: + description: The unique langfuse identifier of a media record + contentType: type: string - nullable: true - input: - nullable: true - output: - nullable: true - sessionId: + description: The MIME type of the media record + contentLength: + type: integer + description: The size of the media record in bytes + uploadedAt: type: string - nullable: true - release: + format: date-time + description: The date and time when the media record was uploaded + url: type: string - nullable: true - version: + description: The download URL of the media record + urlExpiry: type: string - nullable: true - metadata: - nullable: true - tags: - type: array - items: - type: string - nullable: true - environment: + description: The expiry date and time of the media record download URL + required: + - mediaId + - contentType + - contentLength + - uploadedAt + - url + - urlExpiry + PatchMediaBody: + title: PatchMediaBody + type: object + properties: + uploadedAt: + type: string + format: date-time + description: The date and time when the media record was uploaded + uploadHttpStatus: + type: integer + description: The HTTP status code of the upload + uploadHttpError: type: string nullable: true - public: - type: boolean + description: The HTTP error message of the upload + uploadTimeMs: + type: integer nullable: true - description: Make trace publicly accessible via url - SDKLogBody: - title: SDKLogBody - type: object - properties: - log: {} + description: The time in milliseconds it took to upload the media record required: - - log - ScoreBody: - title: ScoreBody + - uploadedAt + - uploadHttpStatus + GetMediaUploadUrlRequest: + title: GetMediaUploadUrlRequest type: object + description: >- + Request a presigned media upload URL. Provide exactly one context: a + trace (traceId, optionally observationId) or a dataset item (datasetId + + datasetItemId). field is required and must match the chosen context. properties: - id: - type: string - nullable: true traceId: type: string nullable: true - sessionId: - type: string - nullable: true + description: >- + The trace the media is associated with. Null for dataset item media + uploads. observationId: type: string nullable: true - datasetRunId: - type: string - nullable: true - name: - type: string description: >- - The name of the score. Always overrides "output" for correction - scores. - environment: - type: string - nullable: true - queueId: + The observation ID associated with the media record. If the media + record is associated directly with a trace, this will be null. + datasetId: type: string nullable: true description: >- - The 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: + The dataset the media belongs to. Null for trace/observation media + uploads. + datasetItemId: type: string nullable: true - metadata: - nullable: true - dataType: - $ref: '#/components/schemas/ScoreDataType' - nullable: true description: >- - When set, must match the score value's type. If not set, will be - inferred from the score value or config - configId: + The dataset item the media is associated with (need not exist yet). + Null for trace/observation media uploads. + contentType: + $ref: '#/components/schemas/MediaContentType' + contentLength: + type: integer + description: The size of the media record in bytes + sha256Hash: + type: string + description: The SHA-256 hash of the media record + field: type: string - nullable: true description: >- - Reference a score config on a score. When set, the score name must - equal the config name and scores must comply with the config's range - and data type. For categorical scores, the value must map to a - config category. Numeric scores might be constrained by the score - config's max and min values + The item field the media is in: `input`/`output`/`metadata` (trace) + or `input`/`expectedOutput`/`metadata` (dataset item). required: - - name - - value - BaseEvent: - title: BaseEvent + - contentType + - contentLength + - sha256Hash + - field + GetMediaUploadUrlResponse: + title: GetMediaUploadUrlResponse type: object properties: - id: - type: string - description: UUID v4 that identifies the event - timestamp: + uploadUrl: type: string - description: >- - Datetime (ISO 8601) of event creation in client. Should be as close - to actual event creation in client as possible, this timestamp will - be used for ordering of events in future release. Resolution: - milliseconds (required), microseconds (optimal). - metadata: nullable: true - description: Optional. Metadata field used by the Langfuse SDKs for debugging. - required: - - id - - timestamp - TraceEvent: - title: TraceEvent - type: object - properties: - body: - $ref: '#/components/schemas/TraceBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - CreateObservationEvent: - title: CreateObservationEvent - type: object - properties: - body: - $ref: '#/components/schemas/ObservationBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - UpdateObservationEvent: - title: UpdateObservationEvent - type: object - properties: - body: - $ref: '#/components/schemas/ObservationBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - ScoreEvent: - title: ScoreEvent - type: object - properties: - body: - $ref: '#/components/schemas/ScoreBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - SDKLogEvent: - title: SDKLogEvent - type: object - properties: - body: - $ref: '#/components/schemas/SDKLogBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - CreateGenerationEvent: - title: CreateGenerationEvent - type: object - properties: - body: - $ref: '#/components/schemas/CreateGenerationBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - UpdateGenerationEvent: - title: UpdateGenerationEvent - type: object - properties: - body: - $ref: '#/components/schemas/UpdateGenerationBody' - required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - CreateSpanEvent: - title: CreateSpanEvent - type: object - properties: - body: - $ref: '#/components/schemas/CreateSpanBody' + description: >- + The presigned upload URL. If the asset is already uploaded, this + will be null + mediaId: + type: string + description: The unique langfuse identifier of a media record required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - UpdateSpanEvent: - title: UpdateSpanEvent + - mediaId + MediaContentType: + title: MediaContentType + type: string + enum: + - image/png + - image/jpeg + - image/jpg + - image/webp + - image/gif + - image/svg+xml + - image/tiff + - image/bmp + - image/avif + - image/heic + - audio/mpeg + - audio/mp3 + - audio/wav + - audio/ogg + - audio/oga + - audio/aac + - audio/mp4 + - audio/flac + - audio/opus + - audio/webm + - video/mp4 + - video/webm + - video/ogg + - video/mpeg + - video/quicktime + - video/x-msvideo + - video/x-matroska + - text/plain + - text/html + - text/css + - text/csv + - text/markdown + - text/x-python + - application/javascript + - text/x-typescript + - application/x-yaml + - application/pdf + - application/msword + - application/vnd.ms-excel + - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet + - application/zip + - application/json + - application/xml + - application/octet-stream + - >- + application/vnd.openxmlformats-officedocument.wordprocessingml.document + - >- + application/vnd.openxmlformats-officedocument.presentationml.presentation + - application/rtf + - application/x-ndjson + - application/vnd.apache.parquet + - application/gzip + - application/x-tar + - application/x-7z-compressed + description: The MIME type of the media record + MetricsV2Response: + title: MetricsV2Response type: object properties: - body: - $ref: '#/components/schemas/UpdateSpanBody' + data: + type: array + items: + type: object + additionalProperties: true + description: >- + The metrics data. Each item in the list contains the metric values + and dimensions requested in the query. + + Format varies based on the query parameters. + + Histograms will return an array with [lower, upper, height] tuples. required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - CreateEventEvent: - title: CreateEventEvent + - data + PaginatedModels: + title: PaginatedModels type: object properties: - body: - $ref: '#/components/schemas/CreateEventBody' + data: + type: array + items: + $ref: '#/components/schemas/Model' + meta: + $ref: '#/components/schemas/utilsMetaResponse' required: - - body - allOf: - - $ref: '#/components/schemas/BaseEvent' - IngestionSuccess: - title: IngestionSuccess + - data + - meta + CreateModelRequest: + title: CreateModelRequest type: object properties: - id: + modelName: type: string - status: - type: integer - required: - - id - - status - IngestionError: - title: IngestionError - type: object - properties: - id: + description: >- + Name of the model definition. If multiple with the same name exist, + they are applied in the following order: (1) custom over built-in, + (2) newest according to startTime where + model.startTime- + Regex pattern which matches this model definition to + generation.model. Useful in case of fine-tuned models. If you want + to exact match, use `(?i)^modelname$` + startDate: type: string + format: date-time nullable: true - error: + description: Apply only to generations which are newer than this ISO date. + unit: + $ref: '#/components/schemas/ModelUsageUnit' nullable: true - required: - - id - - status - IngestionResponse: - title: IngestionResponse - type: object - properties: - successes: - type: array - items: - $ref: '#/components/schemas/IngestionSuccess' - errors: + description: Unit used by this model. + inputPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit. + Creates a default tier if pricingTiers not provided. + outputPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit. + Creates a default tier if pricingTiers not provided. + totalPrice: + type: number + format: double + nullable: true + description: >- + Deprecated. Use 'pricingTiers' instead. Price (USD) per total units. + Cannot be set if input or output price is set. Creates a default + tier if pricingTiers not provided. + pricingTiers: type: array items: - $ref: '#/components/schemas/IngestionError' - required: - - successes - - errors - OpenAICompletionUsageSchema: - title: OpenAICompletionUsageSchema - type: object - description: OpenAI Usage schema from (Chat-)Completion APIs - properties: - prompt_tokens: - type: integer - completion_tokens: - type: integer - total_tokens: - type: integer - prompt_tokens_details: - type: object - additionalProperties: - type: integer - nullable: true - nullable: true - completion_tokens_details: - type: object - additionalProperties: - type: integer - nullable: true + $ref: '#/components/schemas/PricingTierInput' nullable: true - required: - - prompt_tokens - - completion_tokens - - total_tokens - OpenAIResponseUsageSchema: - title: OpenAIResponseUsageSchema - type: object - description: OpenAI Usage schema from Response API - properties: - input_tokens: - type: integer - output_tokens: - type: integer - total_tokens: - type: integer - input_tokens_details: - type: object - additionalProperties: - type: integer - nullable: true + description: >- + Optional. Array of pricing tiers for this model. + + + Use pricing tiers for all models - both those with threshold-based + pricing variations and those with simple flat pricing: + + + - For models with standard flat pricing: Create a single default + tier with your prices + (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices) + + - For models with threshold-based pricing: Create a default tier + plus additional conditional tiers + (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds) + + Requirements: + + - Cannot be provided with flat prices + (inputPrice/outputPrice/totalPrice) - use one approach or the other + + - Must include exactly one default tier with isDefault=true, + priority=0, and conditions=[] + + - All tier names and priorities must be unique within the model + + - Each tier must define at least one price + + + If omitted, you must provide flat prices instead + (inputPrice/outputPrice/totalPrice), + + which will automatically create a single default tier named + "Standard". + tokenizerId: + type: string nullable: true - output_tokens_details: - type: object - additionalProperties: - type: integer - nullable: true + description: >- + Optional. Tokenizer to be applied to observations which match to + this model. See docs for more details. + tokenizerConfig: nullable: true + description: >- + Optional. Configuration for the selected tokenizer. Needs to be + JSON. See docs for more details. required: - - input_tokens - - output_tokens - - total_tokens - UsageDetails: - title: UsageDetails - oneOf: - - type: object - additionalProperties: - type: integer - - $ref: '#/components/schemas/OpenAICompletionUsageSchema' - - $ref: '#/components/schemas/OpenAIResponseUsageSchema' - legacyMetricsResponse: - title: legacyMetricsResponse + - modelName + - matchPattern + ObservationsV2Response: + title: ObservationsV2Response type: object + description: >- + Response containing observations with field-group-based filtering and + cursor-based pagination. + + + The `data` array contains observation objects with only the requested + field groups included. + + Use the `cursor` in `meta` to retrieve the next page of results. properties: data: type: array items: - type: object - additionalProperties: true + $ref: '#/components/schemas/ObservationV2' 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. + Array of observation objects. Fields included depend on the `fields` + parameter in the request. + meta: + $ref: '#/components/schemas/ObservationsV2Meta' required: - data - legacyObservations: - title: legacyObservations + - meta + ObservationsV2Meta: + title: ObservationsV2Meta type: object + description: Metadata for cursor-based pagination properties: - data: + cursor: + type: string + nullable: true + description: >- + Base64-encoded cursor to use for retrieving the next page. If not + present, there are no more results. + OtelResourceSpan: + title: OtelResourceSpan + type: object + description: >- + Represents a collection of spans from a single resource as per OTLP + specification + properties: + resource: + $ref: '#/components/schemas/OtelResource' + nullable: true + description: Resource information + scopeSpans: type: array items: - $ref: '#/components/schemas/Observation' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - legacyObservationsViews: - title: legacyObservationsViews + $ref: '#/components/schemas/OtelScopeSpan' + nullable: true + description: Array of scope spans + OtelResource: + title: OtelResource type: object + description: Resource attributes identifying the source of telemetry properties: - data: + attributes: type: array items: - $ref: '#/components/schemas/ObservationsView' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - legacyCreateScoreRequest: - title: legacyCreateScoreRequest + $ref: '#/components/schemas/OtelAttribute' + nullable: true + description: Resource attributes like service.name, service.version, etc. + OtelScopeSpan: + title: OtelScopeSpan type: object + description: Collection of spans from a single instrumentation scope properties: - id: - type: string + scope: + $ref: '#/components/schemas/OtelScope' nullable: true - traceId: - type: string + description: Instrumentation scope information + spans: + type: array + items: + $ref: '#/components/schemas/OtelSpan' nullable: true - sessionId: + description: Array of spans + OtelScope: + title: OtelScope + type: object + description: Instrumentation scope information + properties: + name: type: string nullable: true - observationId: + description: Instrumentation scope name + version: type: string nullable: true - datasetRunId: - type: string + description: Instrumentation scope version + attributes: + type: array + items: + $ref: '#/components/schemas/OtelAttribute' + nullable: true + description: Additional scope attributes + OtelSpan: + title: OtelSpan + type: object + description: Individual span representing a unit of work or operation + properties: + traceId: + nullable: true + description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary) + spanId: + nullable: true + description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary) + parentSpanId: nullable: true + description: Parent span ID if this is a child span name: type: string - 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 + description: Span name describing the operation + kind: + type: integer nullable: true - environment: - type: string + description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER) + startTimeUnixNano: + nullable: true + description: Start time in nanoseconds since Unix epoch + endTimeUnixNano: + nullable: true + description: End time in nanoseconds since Unix epoch + attributes: + type: array + items: + $ref: '#/components/schemas/OtelAttribute' nullable: true description: >- - The environment of the score. Can be any lowercase alphanumeric - string with hyphens and underscores that does not start with - 'langfuse'. - queueId: + Span attributes including Langfuse-specific attributes + (langfuse.observation.*) + status: + nullable: true + description: Span status object + OtelAttribute: + title: OtelAttribute + type: object + description: Key-value attribute pair for resources, scopes, or spans + properties: + key: type: string nullable: true - description: >- - The annotation queue referenced by the score. Indicates if score was - initially created while processing annotation queue. - dataType: - $ref: '#/components/schemas/ScoreDataType' + description: Attribute key (e.g., "service.name", "langfuse.observation.type") + value: + $ref: '#/components/schemas/OtelAttributeValue' 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: + description: Attribute value + OtelAttributeValue: + title: OtelAttributeValue + type: object + description: Attribute value wrapper supporting different value types + properties: + stringValue: type: string nullable: true - description: >- - Reference a score config on a score. The unique langfuse identifier - of a score config. When passing this field, the dataType and - stringValue fields are automatically populated. - source: - $ref: '#/components/schemas/legacyCreateScoreSource' + description: String value + intValue: + type: integer nullable: true - description: >- - The source of the score. Defaults to API. Set to ANNOTATION to - prefill scores (e.g. from an LLM) for a human reviewer to verify in - an annotation queue. When source is ANNOTATION, a configId is - required unless dataType is CORRECTION. EVAL is reserved for - internal evaluator outputs and is not accepted on this endpoint. - required: - - name - - value - legacyCreateScoreSource: - title: legacyCreateScoreSource + description: Integer value + doubleValue: + type: number + format: double + nullable: true + description: Double value + boolValue: + type: boolean + nullable: true + description: Boolean value + OtelTraceResponse: + title: OtelTraceResponse + type: object + description: Response from trace export request. Empty object indicates success. + properties: {} + MembershipRole: + title: MembershipRole type: string enum: - - API - - ANNOTATION - description: |- - Source values accepted when creating a score via the public REST API. - EVAL is reserved for internal evaluator outputs and is intentionally not - exposed here — use commons.ScoreSource when reading scores. - legacyCreateScoreResponse: - title: legacyCreateScoreResponse + - OWNER + - ADMIN + - MEMBER + - VIEWER + MembershipRequest: + title: MembershipRequest + type: object + properties: + userId: + type: string + role: + $ref: '#/components/schemas/MembershipRole' + required: + - userId + - role + DeleteMembershipRequest: + title: DeleteMembershipRequest + type: object + properties: + userId: + type: string + required: + - userId + MembershipResponse: + title: MembershipResponse + type: object + properties: + userId: + type: string + role: + $ref: '#/components/schemas/MembershipRole' + email: + type: string + name: + type: string + required: + - userId + - role + - email + - name + MembershipDeletionResponse: + title: MembershipDeletionResponse type: object properties: - id: + message: + type: string + userId: type: string - description: The id of the created object in Langfuse required: - - id - LlmConnection: - title: LlmConnection + - message + - userId + MembershipsResponse: + title: MembershipsResponse + type: object + properties: + memberships: + type: array + items: + $ref: '#/components/schemas/MembershipResponse' + required: + - memberships + OrganizationProject: + title: OrganizationProject type: object - description: LLM API connection configuration (secrets excluded) properties: id: type: string - provider: - type: string - description: >- - Provider name (e.g., 'openai', 'my-gateway'). Must be unique in - project, used for upserting. - adapter: - type: string - description: The adapter used to interface with the LLM - displaySecretKey: - type: string - description: Masked version of the secret key for display purposes - baseURL: + name: type: string - nullable: true - description: Custom base URL for the LLM API - customModels: - type: array - items: - type: string - description: List of custom model names available for this connection - withDefaultModels: - type: boolean - description: Whether to include default models for this adapter - extraHeaderKeys: - type: array - items: - type: string - description: >- - Keys of extra headers sent with requests (values excluded for - security) - config: + metadata: type: object additionalProperties: true nullable: true - description: >- - Adapter-specific configuration. Required for Bedrock - (`{"region":"us-east-1"}`), optional for OpenAI - (`{"useResponsesApi":true}`), optional for VertexAI - (`{"location":"us-central1"}`), not used by other adapters. createdAt: type: string format: date-time @@ -11014,1691 +12677,1579 @@ components: format: date-time required: - id - - provider - - adapter - - displaySecretKey - - customModels - - withDefaultModels - - extraHeaderKeys + - name - createdAt - updatedAt - PaginatedLlmConnections: - title: PaginatedLlmConnections - type: object - properties: - data: - type: array - items: - $ref: '#/components/schemas/LlmConnection' - meta: - $ref: '#/components/schemas/utilsMetaResponse' - required: - - data - - meta - UpsertLlmConnectionRequest: - title: UpsertLlmConnectionRequest + OrganizationProjectsResponse: + title: OrganizationProjectsResponse type: object - description: Request to create or update an LLM connection (upsert) properties: - provider: - type: string - description: >- - Provider name (e.g., 'openai', 'my-gateway'). Must be unique in - project, used for upserting. - adapter: - $ref: '#/components/schemas/LlmAdapter' - description: The adapter used to interface with the LLM - secretKey: - type: string - description: Secret key for the LLM API. - baseURL: - type: string - nullable: true - description: Custom base URL for the LLM API - customModels: + projects: type: array items: - type: string - nullable: true - description: List of custom model names - withDefaultModels: - type: boolean - nullable: true - description: Whether to include default models. Default is true. - extraHeaders: - type: object - additionalProperties: - type: string - nullable: true - description: Extra headers to send with requests - config: - type: object - additionalProperties: true - nullable: true - description: >- - Adapter-specific configuration. Validation rules: - **Bedrock**: - Required. Must be `{"region": ""}` (e.g., - `{"region":"us-east-1"}`) - **OpenAI**: Optional. If provided, must - be `{"useResponsesApi": }` to control whether Langfuse - routes calls through OpenAI's Responses API. - **VertexAI**: - Optional. If provided, must be `{"location": ""}` - (e.g., `{"location":"us-central1"}`) - **Other adapters**: Not - supported. Omit this field or set to null. - required: - - provider - - adapter - - secretKey - DeleteLlmConnectionResponse: - title: DeleteLlmConnectionResponse - type: object - properties: - message: - type: string + $ref: '#/components/schemas/OrganizationProject' required: - - message - LlmAdapter: - title: LlmAdapter - type: string - enum: - - anthropic - - openai - - azure - - bedrock - - google-vertex-ai - - google-ai-studio - GetMediaResponse: - title: GetMediaResponse + - projects + OrganizationApiKey: + title: OrganizationApiKey type: object properties: - mediaId: - type: string - description: The unique langfuse identifier of a media record - contentType: + id: type: string - description: The MIME type of the media record - contentLength: - type: integer - description: The size of the media record in bytes - uploadedAt: + createdAt: type: string format: date-time - description: The date and time when the media record was uploaded - url: - type: string - description: The download URL of the media record - urlExpiry: - type: string - description: The expiry date and time of the media record download URL - required: - - mediaId - - contentType - - contentLength - - uploadedAt - - url - - urlExpiry - PatchMediaBody: - title: PatchMediaBody - type: object - properties: - uploadedAt: + expiresAt: type: string format: date-time - description: The date and time when the media record was uploaded - uploadHttpStatus: - type: integer - description: The HTTP status code of the upload - uploadHttpError: - type: string - nullable: true - description: The HTTP error message of the upload - uploadTimeMs: - type: integer nullable: true - description: The time in milliseconds it took to upload the media record - required: - - uploadedAt - - uploadHttpStatus - GetMediaUploadUrlRequest: - title: GetMediaUploadUrlRequest - type: object - description: >- - Request a presigned media upload URL. Provide exactly one context: a - trace (traceId, optionally observationId) or a dataset item (datasetId + - datasetItemId). field is required and must match the chosen context. - properties: - traceId: + lastUsedAt: type: string + format: date-time nullable: true - description: >- - The trace the media is associated with. Null for dataset item media - uploads. - observationId: + note: type: string nullable: true - description: >- - The observation ID associated with the media record. If the media - record is associated directly with a trace, this will be null. - datasetId: + publicKey: type: string - nullable: true - description: >- - The dataset the media belongs to. Null for trace/observation media - uploads. - datasetItemId: + displaySecretKey: type: string - nullable: true - description: >- - The dataset item the media is associated with (need not exist yet). - Null for trace/observation media uploads. - contentType: - $ref: '#/components/schemas/MediaContentType' - contentLength: - type: integer - description: The size of the media record in bytes - sha256Hash: + required: + - id + - createdAt + - publicKey + - displaySecretKey + OrganizationApiKeysResponse: + title: OrganizationApiKeysResponse + type: object + properties: + apiKeys: + type: array + items: + $ref: '#/components/schemas/OrganizationApiKey' + required: + - apiKeys + Projects: + title: Projects + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/Project' + required: + - data + Organization: + title: Organization + type: object + properties: + id: type: string - description: The SHA-256 hash of the media record - field: + description: The unique identifier of the organization + name: type: string - description: >- - The item field the media is in: `input`/`output`/`metadata` (trace) - or `input`/`expectedOutput`/`metadata` (dataset item). + description: The name of the organization required: - - contentType - - contentLength - - sha256Hash - - field - GetMediaUploadUrlResponse: - title: GetMediaUploadUrlResponse + - id + - name + Project: + title: Project type: object properties: - uploadUrl: + id: + type: string + name: type: string + organization: + $ref: '#/components/schemas/Organization' + description: The organization this project belongs to + metadata: + type: object + additionalProperties: true + description: Metadata for the project + retentionDays: + type: integer nullable: true description: >- - The presigned upload URL. If the asset is already uploaded, this - will be null - mediaId: - type: string - description: The unique langfuse identifier of a media record + Number of days to retain data. Null or 0 means no retention. Omitted + if no retention is configured. required: - - mediaId - MediaContentType: - title: MediaContentType - type: string - enum: - - image/png - - image/jpeg - - image/jpg - - image/webp - - image/gif - - image/svg+xml - - image/tiff - - image/bmp - - image/avif - - image/heic - - audio/mpeg - - audio/mp3 - - audio/wav - - audio/ogg - - audio/oga - - audio/aac - - audio/mp4 - - audio/flac - - audio/opus - - audio/webm - - video/mp4 - - video/webm - - video/ogg - - video/mpeg - - video/quicktime - - video/x-msvideo - - video/x-matroska - - text/plain - - text/html - - text/css - - text/csv - - text/markdown - - text/x-python - - application/javascript - - text/x-typescript - - application/x-yaml - - application/pdf - - application/msword - - application/vnd.ms-excel - - application/vnd.openxmlformats-officedocument.spreadsheetml.sheet - - application/zip - - application/json - - application/xml - - application/octet-stream - - >- - application/vnd.openxmlformats-officedocument.wordprocessingml.document - - >- - application/vnd.openxmlformats-officedocument.presentationml.presentation - - application/rtf - - application/x-ndjson - - application/vnd.apache.parquet - - application/gzip - - application/x-tar - - application/x-7z-compressed - description: The MIME type of the media record - MetricsV2Response: - title: MetricsV2Response + - id + - name + - organization + - metadata + ProjectDeletionResponse: + title: ProjectDeletionResponse type: object properties: - data: - type: array - items: - type: object - additionalProperties: true - description: >- - The metrics data. Each item in the list contains the metric values - and dimensions requested in the query. - - Format varies based on the query parameters. - - Histograms will return an array with [lower, upper, height] tuples. + success: + type: boolean + message: + type: string required: - - data - PaginatedModels: - title: PaginatedModels + - success + - message + ApiKeyList: + title: ApiKeyList type: object + description: List of API keys for a project properties: - data: + apiKeys: type: array items: - $ref: '#/components/schemas/Model' - meta: - $ref: '#/components/schemas/utilsMetaResponse' + $ref: '#/components/schemas/ApiKeySummary' required: - - data - - meta - CreateModelRequest: - title: CreateModelRequest + - apiKeys + ApiKeySummary: + title: ApiKeySummary type: object + description: Summary of an API key properties: - modelName: + id: type: string - description: >- - Name of the model definition. If multiple with the same name exist, - they are applied in the following order: (1) custom over built-in, - (2) newest according to startTime where - model.startTime- - Regex pattern which matches this model definition to - generation.model. Useful in case of fine-tuned models. If you want - to exact match, use `(?i)^modelname$` - startDate: + format: date-time + expiresAt: type: string format: date-time nullable: true - description: Apply only to generations which are newer than this ISO date. - unit: - $ref: '#/components/schemas/ModelUsageUnit' - nullable: true - description: Unit used by this model. - inputPrice: - type: number - format: double - nullable: true - description: >- - Deprecated. Use 'pricingTiers' instead. Price (USD) per input unit. - Creates a default tier if pricingTiers not provided. - outputPrice: - type: number - format: double - nullable: true - description: >- - Deprecated. Use 'pricingTiers' instead. Price (USD) per output unit. - Creates a default tier if pricingTiers not provided. - totalPrice: - type: number - format: double + lastUsedAt: + type: string + format: date-time nullable: true - description: >- - Deprecated. Use 'pricingTiers' instead. Price (USD) per total units. - Cannot be set if input or output price is set. Creates a default - tier if pricingTiers not provided. - pricingTiers: - type: array - items: - $ref: '#/components/schemas/PricingTierInput' + note: + type: string nullable: true - description: >- - Optional. Array of pricing tiers for this model. - - - Use pricing tiers for all models - both those with threshold-based - pricing variations and those with simple flat pricing: - - - - For models with standard flat pricing: Create a single default - tier with your prices - (e.g., one tier with isDefault=true, priority=0, conditions=[], and your standard prices) - - - For models with threshold-based pricing: Create a default tier - plus additional conditional tiers - (e.g., default tier for standard usage + high-volume tier for usage above certain thresholds) - - Requirements: - - - Cannot be provided with flat prices - (inputPrice/outputPrice/totalPrice) - use one approach or the other - - - Must include exactly one default tier with isDefault=true, - priority=0, and conditions=[] - - - All tier names and priorities must be unique within the model - - - Each tier must define at least one price - - - If omitted, you must provide flat prices instead - (inputPrice/outputPrice/totalPrice), - - which will automatically create a single default tier named - "Standard". - tokenizerId: + publicKey: + type: string + displaySecretKey: + type: string + required: + - id + - createdAt + - publicKey + - displaySecretKey + ApiKeyResponse: + title: ApiKeyResponse + type: object + description: Response for API key creation + properties: + id: + type: string + createdAt: + type: string + format: date-time + publicKey: + type: string + secretKey: + type: string + displaySecretKey: + type: string + note: type: string nullable: true - description: >- - Optional. Tokenizer to be applied to observations which match to - this model. See docs for more details. - tokenizerConfig: - nullable: true - description: >- - Optional. Configuration for the selected tokenizer. Needs to be - JSON. See docs for more details. required: - - modelName - - matchPattern - ObservationsV2Response: - title: ObservationsV2Response + - id + - createdAt + - publicKey + - secretKey + - displaySecretKey + ApiKeyDeletionResponse: + title: ApiKeyDeletionResponse + type: object + description: Response for API key deletion + properties: + success: + type: boolean + required: + - success + PromptMetaListResponse: + title: PromptMetaListResponse type: object - description: >- - Response containing observations with field-group-based filtering and - cursor-based pagination. - - - The `data` array contains observation objects with only the requested - field groups included. - - Use the `cursor` in `meta` to retrieve the next page of results. properties: data: type: array items: - $ref: '#/components/schemas/ObservationV2' - description: >- - Array of observation objects. Fields included depend on the `fields` - parameter in the request. + $ref: '#/components/schemas/PromptMeta' meta: - $ref: '#/components/schemas/ObservationsV2Meta' + $ref: '#/components/schemas/utilsMetaResponse' required: - data - meta - ObservationsV2Meta: - title: ObservationsV2Meta + PromptMeta: + title: PromptMeta type: object - description: Metadata for cursor-based pagination properties: - cursor: + name: type: string - nullable: true - description: >- - Base64-encoded cursor to use for retrieving the next page. If not - present, there are no more results. - OtelResourceSpan: - title: OtelResourceSpan - type: object - description: >- - Represents a collection of spans from a single resource as per OTLP - specification - properties: - resource: - $ref: '#/components/schemas/OtelResource' - nullable: true - description: Resource information - scopeSpans: + type: + $ref: '#/components/schemas/PromptType' + description: Indicates whether the prompt is a text or chat prompt. + versions: type: array items: - $ref: '#/components/schemas/OtelScopeSpan' - nullable: true - description: Array of scope spans - OtelResource: - title: OtelResource - type: object - description: Resource attributes identifying the source of telemetry - properties: - attributes: + type: integer + labels: type: array items: - $ref: '#/components/schemas/OtelAttribute' - nullable: true - description: Resource attributes like service.name, service.version, etc. - OtelScopeSpan: - title: OtelScopeSpan - type: object - description: Collection of spans from a single instrumentation scope - properties: - scope: - $ref: '#/components/schemas/OtelScope' - nullable: true - description: Instrumentation scope information - spans: + type: string + tags: type: array items: - $ref: '#/components/schemas/OtelSpan' - nullable: true - description: Array of spans - OtelScope: - title: OtelScope + type: string + lastUpdatedAt: + type: string + format: date-time + lastConfig: + description: >- + Config object of the most recent prompt version that matches the + filters (if any are provided) + required: + - name + - type + - versions + - labels + - tags + - lastUpdatedAt + - lastConfig + CreatePromptRequest: + title: CreatePromptRequest + oneOf: + - $ref: '#/components/schemas/CreateChatPromptRequest' + - $ref: '#/components/schemas/CreateTextPromptRequest' + CreateChatPromptRequest: + title: CreateChatPromptRequest type: object - description: Instrumentation scope information properties: name: type: string + prompt: + type: array + items: + $ref: '#/components/schemas/ChatMessageWithPlaceholders' + config: nullable: true - description: Instrumentation scope name - version: - type: string + type: + $ref: '#/components/schemas/CreateChatPromptType' + labels: + type: array + items: + type: string nullable: true - description: Instrumentation scope version - attributes: + description: List of deployment labels of this prompt version. + tags: type: array items: - $ref: '#/components/schemas/OtelAttribute' + type: string nullable: true - description: Additional scope attributes - OtelSpan: - title: OtelSpan + description: List of tags to apply to all versions of this prompt. + commitMessage: + type: string + nullable: true + description: Commit message for this prompt version. + required: + - name + - prompt + - type + CreateTextPromptRequest: + title: CreateTextPromptRequest type: object - description: Individual span representing a unit of work or operation properties: - traceId: - nullable: true - description: Trace ID (16 bytes, hex-encoded string in JSON or Buffer in binary) - spanId: - nullable: true - description: Span ID (8 bytes, hex-encoded string in JSON or Buffer in binary) - parentSpanId: - nullable: true - description: Parent span ID if this is a child span name: type: string + prompt: + type: string + config: nullable: true - description: Span name describing the operation - kind: - type: integer - nullable: true - description: Span kind (1=INTERNAL, 2=SERVER, 3=CLIENT, 4=PRODUCER, 5=CONSUMER) - startTimeUnixNano: - nullable: true - description: Start time in nanoseconds since Unix epoch - endTimeUnixNano: + type: + $ref: '#/components/schemas/CreateTextPromptType' nullable: true - description: End time in nanoseconds since Unix epoch - attributes: + labels: type: array items: - $ref: '#/components/schemas/OtelAttribute' - nullable: true - description: >- - Span attributes including Langfuse-specific attributes - (langfuse.observation.*) - status: - nullable: true - description: Span status object - OtelAttribute: - title: OtelAttribute - type: object - description: Key-value attribute pair for resources, scopes, or spans - properties: - key: - type: string + type: string nullable: true - description: Attribute key (e.g., "service.name", "langfuse.observation.type") - value: - $ref: '#/components/schemas/OtelAttributeValue' + description: List of deployment labels of this prompt version. + tags: + type: array + items: + type: string nullable: true - description: Attribute value - OtelAttributeValue: - title: OtelAttributeValue - type: object - description: Attribute value wrapper supporting different value types - properties: - stringValue: + description: List of tags to apply to all versions of this prompt. + commitMessage: type: string nullable: true - description: String value - intValue: - type: integer - nullable: true - description: Integer value - doubleValue: - type: number - format: double - nullable: true - description: Double value - boolValue: - type: boolean - nullable: true - description: Boolean value - OtelTraceResponse: - title: OtelTraceResponse + description: Commit message for this prompt version. + required: + - name + - prompt + Prompt: + title: Prompt type: object - description: Response from trace export request. Empty object indicates success. - properties: {} - MembershipRole: - title: MembershipRole + properties: + type: + type: string + enum: + - chat + - text + prompt: + type: string + required: + - type + - prompt + PromptType: + title: PromptType type: string enum: - - OWNER - - ADMIN - - MEMBER - - VIEWER - MembershipRequest: - title: MembershipRequest + - chat + - text + BasePrompt: + title: BasePrompt type: object properties: - userId: + name: type: string - role: - $ref: '#/components/schemas/MembershipRole' + version: + type: integer + config: {} + labels: + type: array + items: + type: string + description: List of deployment labels of this prompt version. + tags: + type: array + items: + type: string + description: >- + List of tags. Used to filter via UI and API. The same across + versions of a prompt. + commitMessage: + type: string + nullable: true + description: Commit message for this prompt version. + resolutionGraph: + type: object + additionalProperties: true + nullable: true + description: >- + The dependency resolution graph for the current prompt. Null if the + prompt has no dependencies or if `resolve=false` was used. required: - - userId - - role - DeleteMembershipRequest: - title: DeleteMembershipRequest + - name + - version + - config + - labels + - tags + ChatMessageWithPlaceholders: + title: ChatMessageWithPlaceholders + oneOf: + - $ref: '#/components/schemas/ChatMessage' + - $ref: '#/components/schemas/PlaceholderMessage' + ChatMessage: + title: ChatMessage type: object properties: - userId: + role: + type: string + content: type: string + type: + $ref: '#/components/schemas/ChatMessageType' + nullable: true required: - - userId - MembershipResponse: - title: MembershipResponse + - role + - content + ChatMessageType: + title: ChatMessageType + type: string + enum: + - chatmessage + PlaceholderMessage: + title: PlaceholderMessage type: object properties: - userId: - type: string - role: - $ref: '#/components/schemas/MembershipRole' - email: - type: string name: type: string + type: + $ref: '#/components/schemas/PlaceholderMessageType' + nullable: true required: - - userId - - role - - email - name - MembershipDeletionResponse: - title: MembershipDeletionResponse + PlaceholderMessageType: + title: PlaceholderMessageType + type: string + enum: + - placeholder + TextPrompt: + title: TextPrompt type: object properties: - message: - type: string - userId: + prompt: type: string required: - - message - - userId - MembershipsResponse: - title: MembershipsResponse + - prompt + allOf: + - $ref: '#/components/schemas/BasePrompt' + ChatPrompt: + title: ChatPrompt type: object properties: - memberships: + prompt: type: array items: - $ref: '#/components/schemas/MembershipResponse' + $ref: '#/components/schemas/ChatMessageWithPlaceholders' required: - - memberships - OrganizationProject: - title: OrganizationProject + - prompt + allOf: + - $ref: '#/components/schemas/BasePrompt' + CreateChatPromptType: + title: CreateChatPromptType + type: string + enum: + - chat + CreateTextPromptType: + title: CreateTextPromptType + type: string + enum: + - text + ServiceProviderConfig: + title: ServiceProviderConfig type: object properties: - id: - type: string - name: - type: string - metadata: - type: object - additionalProperties: true - nullable: true - createdAt: - type: string - format: date-time - updatedAt: + schemas: + type: array + items: + type: string + documentationUri: type: string - format: date-time - required: - - id - - name - - createdAt - - updatedAt - OrganizationProjectsResponse: - title: OrganizationProjectsResponse - type: object - properties: - projects: + patch: + $ref: '#/components/schemas/ScimFeatureSupport' + bulk: + $ref: '#/components/schemas/BulkConfig' + filter: + $ref: '#/components/schemas/FilterConfig' + changePassword: + $ref: '#/components/schemas/ScimFeatureSupport' + sort: + $ref: '#/components/schemas/ScimFeatureSupport' + etag: + $ref: '#/components/schemas/ScimFeatureSupport' + authenticationSchemes: type: array items: - $ref: '#/components/schemas/OrganizationProject' + $ref: '#/components/schemas/AuthenticationScheme' + meta: + $ref: '#/components/schemas/ResourceMeta' required: - - projects - OrganizationApiKey: - title: OrganizationApiKey + - schemas + - documentationUri + - patch + - bulk + - filter + - changePassword + - sort + - etag + - authenticationSchemes + - meta + ScimFeatureSupport: + title: ScimFeatureSupport type: object properties: - id: - type: string - createdAt: - type: string - format: date-time - expiresAt: - type: string - format: date-time - nullable: true - lastUsedAt: - type: string - format: date-time - nullable: true - note: - type: string - nullable: true - publicKey: - type: string - displaySecretKey: - type: string + supported: + type: boolean required: - - id - - createdAt - - publicKey - - displaySecretKey - OrganizationApiKeysResponse: - title: OrganizationApiKeysResponse + - supported + BulkConfig: + title: BulkConfig type: object properties: - apiKeys: - type: array - items: - $ref: '#/components/schemas/OrganizationApiKey' + supported: + type: boolean + maxOperations: + type: integer + maxPayloadSize: + type: integer required: - - apiKeys - Projects: - title: Projects + - supported + - maxOperations + - maxPayloadSize + FilterConfig: + title: FilterConfig type: object properties: - data: - type: array - items: - $ref: '#/components/schemas/Project' + supported: + type: boolean + maxResults: + type: integer required: - - data - Organization: - title: Organization + - supported + - maxResults + ResourceMeta: + title: ResourceMeta type: object properties: - id: + resourceType: type: string - description: The unique identifier of the organization - name: + location: type: string - description: The name of the organization required: - - id - - name - Project: - title: Project + - resourceType + - location + AuthenticationScheme: + title: AuthenticationScheme type: object properties: - id: - type: string name: type: string - organization: - $ref: '#/components/schemas/Organization' - description: The organization this project belongs to - metadata: - type: object - additionalProperties: true - description: Metadata for the project - retentionDays: - type: integer - nullable: true - description: >- - Number of days to retain data. Null or 0 means no retention. Omitted - if no retention is configured. - required: - - id - - name - - organization - - metadata - ProjectDeletionResponse: - title: ProjectDeletionResponse - type: object - properties: - success: - type: boolean - message: + description: + type: string + specUri: type: string + type: + type: string + primary: + type: boolean required: - - success - - message - ApiKeyList: - title: ApiKeyList + - name + - description + - specUri + - type + - primary + ResourceTypesResponse: + title: ResourceTypesResponse type: object - description: List of API keys for a project properties: - apiKeys: + schemas: type: array items: - $ref: '#/components/schemas/ApiKeySummary' + type: string + totalResults: + type: integer + Resources: + type: array + items: + $ref: '#/components/schemas/ResourceType' required: - - apiKeys - ApiKeySummary: - title: ApiKeySummary + - schemas + - totalResults + - Resources + ResourceType: + title: ResourceType type: object - description: Summary of an API key properties: - id: - type: string - createdAt: - type: string - format: date-time - expiresAt: - type: string - format: date-time - nullable: true - lastUsedAt: - type: string - format: date-time - nullable: true - note: - type: string + schemas: + type: array + items: + type: string nullable: true - publicKey: - type: string - displaySecretKey: - type: string - required: - - id - - createdAt - - publicKey - - displaySecretKey - ApiKeyResponse: - title: ApiKeyResponse - type: object - description: Response for API key creation - properties: id: type: string - createdAt: - type: string - format: date-time - publicKey: + name: type: string - secretKey: + endpoint: type: string - displaySecretKey: + description: type: string - note: + schema: type: string - nullable: true + schemaExtensions: + type: array + items: + $ref: '#/components/schemas/SchemaExtension' + meta: + $ref: '#/components/schemas/ResourceMeta' required: - id - - createdAt - - publicKey - - secretKey - - displaySecretKey - ApiKeyDeletionResponse: - title: ApiKeyDeletionResponse + - name + - endpoint + - description + - schema + - schemaExtensions + - meta + SchemaExtension: + title: SchemaExtension type: object - description: Response for API key deletion properties: - success: + schema: + type: string + required: type: boolean required: - - success - PromptMetaListResponse: - title: PromptMetaListResponse + - schema + - required + SchemasResponse: + title: SchemasResponse type: object properties: - data: + schemas: type: array items: - $ref: '#/components/schemas/PromptMeta' - meta: - $ref: '#/components/schemas/utilsMetaResponse' + type: string + totalResults: + type: integer + Resources: + type: array + items: + $ref: '#/components/schemas/SchemaResource' required: - - data - - meta - PromptMeta: - title: PromptMeta + - schemas + - totalResults + - Resources + SchemaResource: + title: SchemaResource type: object properties: + id: + type: string name: type: string - type: - $ref: '#/components/schemas/PromptType' - description: Indicates whether the prompt is a text or chat prompt. - versions: + description: + type: string + attributes: type: array - items: - type: integer - labels: + items: {} + meta: + $ref: '#/components/schemas/ResourceMeta' + required: + - id + - name + - description + - attributes + - meta + ScimUsersListResponse: + title: ScimUsersListResponse + type: object + properties: + schemas: type: array items: type: string - tags: + totalResults: + type: integer + startIndex: + type: integer + itemsPerPage: + type: integer + Resources: type: array items: - type: string - lastUpdatedAt: - type: string - format: date-time - lastConfig: - description: >- - Config object of the most recent prompt version that matches the - filters (if any are provided) + $ref: '#/components/schemas/ScimUser' required: - - name - - type - - versions - - labels - - tags - - lastUpdatedAt - - lastConfig - CreatePromptRequest: - title: CreatePromptRequest - oneOf: - - $ref: '#/components/schemas/CreateChatPromptRequest' - - $ref: '#/components/schemas/CreateTextPromptRequest' - CreateChatPromptRequest: - title: CreateChatPromptRequest + - schemas + - totalResults + - startIndex + - itemsPerPage + - Resources + ScimUser: + title: ScimUser type: object properties: - name: - type: string - prompt: - type: array - items: - $ref: '#/components/schemas/ChatMessageWithPlaceholders' - config: - nullable: true - type: - $ref: '#/components/schemas/CreateChatPromptType' - labels: + schemas: type: array items: type: string - nullable: true - description: List of deployment labels of this prompt version. - tags: + id: + type: string + userName: + type: string + name: + $ref: '#/components/schemas/ScimName' + emails: type: array items: - type: string - nullable: true - description: List of tags to apply to all versions of this prompt. - commitMessage: - type: string - nullable: true - description: Commit message for this prompt version. + $ref: '#/components/schemas/ScimEmail' + meta: + $ref: '#/components/schemas/UserMeta' required: + - schemas + - id + - userName - name - - prompt - - type - CreateTextPromptRequest: - title: CreateTextPromptRequest + - emails + - meta + UserMeta: + title: UserMeta type: object properties: - name: + resourceType: type: string - prompt: + created: type: string - config: - nullable: true - type: - $ref: '#/components/schemas/CreateTextPromptType' - nullable: true - labels: - type: array - items: - type: string - nullable: true - description: List of deployment labels of this prompt version. - tags: - type: array - items: - type: string nullable: true - description: List of tags to apply to all versions of this prompt. - commitMessage: + lastModified: type: string nullable: true - description: Commit message for this prompt version. required: - - name - - prompt - Prompt: - title: Prompt + - resourceType + ScimName: + title: ScimName type: object properties: - type: + formatted: type: string - enum: - - chat - - text - prompt: + nullable: true + ScimEmail: + title: ScimEmail + type: object + properties: + primary: + type: boolean + value: + type: string + type: type: string required: + - primary + - value - type - - prompt - PromptType: - title: PromptType - type: string - enum: - - chat - - text - BasePrompt: - title: BasePrompt + EmptyResponse: + title: EmptyResponse + type: object + description: Empty response for 204 No Content responses + properties: {} + ScoreConfigs: + title: ScoreConfigs type: object properties: - name: - type: string - version: - type: integer - config: {} - labels: + data: type: array items: - type: string - description: List of deployment labels of this prompt version. - tags: + $ref: '#/components/schemas/ScoreConfig' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + CreateScoreConfigRequest: + title: CreateScoreConfigRequest + type: object + properties: + name: + type: string + description: >- + Name of the score config. Max 35 characters. Only letters, numbers, + underscores, spaces, periods, parentheses, and hyphens are allowed. + dataType: + $ref: '#/components/schemas/ScoreConfigDataType' + categories: type: array items: - type: string + $ref: '#/components/schemas/ConfigCategory' + nullable: true description: >- - List of tags. Used to filter via UI and API. The same across - versions of a prompt. - commitMessage: - type: string + Configure custom categories for categorical scores. Pass a list of + objects with `label` and `value` properties. Categories are + autogenerated for boolean configs and cannot be passed + minValue: + type: number + format: double nullable: true - description: Commit message for this prompt version. - resolutionGraph: - type: object - additionalProperties: true + description: >- + Configure a minimum value for numerical scores. If not set, the + minimum value defaults to -∞ + maxValue: + type: number + format: double nullable: true description: >- - The dependency resolution graph for the current prompt. Null if the - prompt has no dependencies or if `resolve=false` was used. - required: - - name - - version - - config - - labels - - tags - ChatMessageWithPlaceholders: - title: ChatMessageWithPlaceholders - oneOf: - - $ref: '#/components/schemas/ChatMessage' - - $ref: '#/components/schemas/PlaceholderMessage' - ChatMessage: - title: ChatMessage - type: object - properties: - role: - type: string - content: + Configure a maximum value for numerical scores. If not set, the + maximum value defaults to +∞ + description: type: string - type: - $ref: '#/components/schemas/ChatMessageType' nullable: true + description: >- + Description is shown across the Langfuse UI and can be used to e.g. + explain the config categories in detail, why a numeric range was + set, or provide additional context on config name or usage required: - - role - - content - ChatMessageType: - title: ChatMessageType - type: string - enum: - - chatmessage - PlaceholderMessage: - title: PlaceholderMessage + - name + - dataType + UpdateScoreConfigRequest: + title: UpdateScoreConfigRequest type: object properties: + isArchived: + type: boolean + nullable: true + description: The status of the score config showing if it is archived or not name: type: string - type: - $ref: '#/components/schemas/PlaceholderMessageType' nullable: true - required: - - name - PlaceholderMessageType: - title: PlaceholderMessageType - type: string - enum: - - placeholder - TextPrompt: - title: TextPrompt - type: object - properties: - prompt: - type: string - required: - - prompt - allOf: - - $ref: '#/components/schemas/BasePrompt' - ChatPrompt: - title: ChatPrompt - type: object - properties: - prompt: + description: >- + Name of the score config. Max 35 characters. Only letters, numbers, + underscores, spaces, periods, parentheses, and hyphens are allowed. + categories: type: array items: - $ref: '#/components/schemas/ChatMessageWithPlaceholders' - required: - - prompt - allOf: - - $ref: '#/components/schemas/BasePrompt' - CreateChatPromptType: - title: CreateChatPromptType - type: string - enum: - - chat - CreateTextPromptType: - title: CreateTextPromptType - type: string - enum: - - text - ServiceProviderConfig: - title: ServiceProviderConfig + $ref: '#/components/schemas/ConfigCategory' + nullable: true + description: >- + Configure custom categories for categorical scores. Pass a list of + objects with `label` and `value` properties. Categories are + autogenerated for boolean configs and cannot be passed + minValue: + type: number + format: double + nullable: true + description: >- + Configure a minimum value for numerical scores. If not set, the + minimum value defaults to -∞ + maxValue: + type: number + format: double + nullable: true + description: >- + Configure a maximum value for numerical scores. If not set, the + maximum value defaults to +∞ + description: + type: string + nullable: true + description: >- + Description is shown across the Langfuse UI and can be used to e.g. + explain the config categories in detail, why a numeric range was + set, or provide additional context on config name or usage + ScoreSubjectTraceV3: + title: ScoreSubjectTraceV3 type: object properties: - schemas: - type: array - items: - type: string - documentationUri: + id: type: string - patch: - $ref: '#/components/schemas/ScimFeatureSupport' - bulk: - $ref: '#/components/schemas/BulkConfig' - filter: - $ref: '#/components/schemas/FilterConfig' - changePassword: - $ref: '#/components/schemas/ScimFeatureSupport' - sort: - $ref: '#/components/schemas/ScimFeatureSupport' - etag: - $ref: '#/components/schemas/ScimFeatureSupport' - authenticationSchemes: - type: array - items: - $ref: '#/components/schemas/AuthenticationScheme' - meta: - $ref: '#/components/schemas/ResourceMeta' + description: The trace ID. required: - - schemas - - documentationUri - - patch - - bulk - - filter - - changePassword - - sort - - etag - - authenticationSchemes - - meta - ScimFeatureSupport: - title: ScimFeatureSupport + - id + ScoreSubjectObservationV3: + title: ScoreSubjectObservationV3 type: object properties: - supported: - type: boolean + id: + type: string + description: The observation ID. + traceId: + type: string + nullable: true + description: The parent trace ID, if available. required: - - supported - BulkConfig: - title: BulkConfig + - id + ScoreSubjectSessionV3: + title: ScoreSubjectSessionV3 type: object properties: - supported: - type: boolean - maxOperations: - type: integer - maxPayloadSize: - type: integer + id: + type: string + description: The session ID. required: - - supported - - maxOperations - - maxPayloadSize - FilterConfig: - title: FilterConfig + - id + ScoreSubjectExperimentV3: + title: ScoreSubjectExperimentV3 type: object properties: - supported: - type: boolean - maxResults: - type: integer + id: + type: string + description: The dataset run ID (experiment ID). required: - - supported - - maxResults - ResourceMeta: - title: ResourceMeta + - id + ScoreSubjectV3: + title: ScoreSubjectV3 type: object properties: - resourceType: + kind: type: string - location: + enum: + - trace + - observation + - session + - experiment + id: + type: string + description: The trace ID. + traceId: type: string + nullable: true + description: The parent trace ID, if available. required: - - resourceType - - location - AuthenticationScheme: - title: AuthenticationScheme + - kind + - id + BaseScoreV3: + title: BaseScoreV3 type: object properties: + id: + type: string + projectId: + type: string name: type: string - description: + source: + $ref: '#/components/schemas/ScoreSource' + timestamp: type: string - specUri: + format: date-time + environment: type: string - type: + description: The environment from which this score originated. + createdAt: type: string - primary: - type: boolean + format: date-time + updatedAt: + type: string + format: date-time + comment: + type: string + nullable: true + description: >- + Optional comment attached to the score. Present when "details" is + included in the fields parameter. + configId: + type: string + nullable: true + description: >- + The score config ID, if this score was created from a config. + Present when "details" is included in the fields parameter. + metadata: + type: object + additionalProperties: true + nullable: true + description: >- + Arbitrary metadata attached to the score. Present when "details" is + included in the fields parameter. + authorUserId: + type: string + nullable: true + description: >- + The user who created this score, if available. Present when + "annotation" is included in the fields parameter. + queueId: + type: string + nullable: true + description: >- + The annotation queue this score belongs to, if any. Present when + "annotation" is included in the fields parameter. + subject: + $ref: '#/components/schemas/ScoreSubjectV3' + nullable: true + description: >- + The entity this score is attached to (trace, observation, session, + or experiment). Present when "subject" is included in the fields + parameter. required: + - id + - projectId - name - - description - - specUri - - type - - primary - ResourceTypesResponse: - title: ResourceTypesResponse + - source + - timestamp + - environment + - createdAt + - updatedAt + NumericScoreV3: + title: NumericScoreV3 type: object properties: - schemas: - type: array - items: - type: string - totalResults: - type: integer - Resources: - type: array - items: - $ref: '#/components/schemas/ResourceType' + value: + type: number + format: double + description: The numeric value of the score. required: - - schemas - - totalResults - - Resources - ResourceType: - title: ResourceType + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + BooleanScoreV3: + title: BooleanScoreV3 + type: object + properties: + value: + type: boolean + description: The boolean value of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + CategoricalScoreV3: + title: CategoricalScoreV3 + type: object + properties: + value: + type: string + description: The string category value of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + TextScoreV3: + title: TextScoreV3 + type: object + properties: + value: + type: string + description: The text content of the score. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + CorrectionScoreV3: + title: CorrectionScoreV3 type: object properties: - schemas: - type: array - items: - type: string - nullable: true - id: - type: string - name: - type: string - endpoint: + value: type: string - description: + description: The correction content of the score. Empty string if not set. + required: + - value + allOf: + - $ref: '#/components/schemas/BaseScoreV3' + ScoreV3: + title: ScoreV3 + type: object + properties: + dataType: type: string - schema: + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + - TEXT + - CORRECTION + value: type: string - schemaExtensions: - type: array - items: - $ref: '#/components/schemas/SchemaExtension' - meta: - $ref: '#/components/schemas/ResourceMeta' + description: The numeric value of the score. required: - - id - - name - - endpoint - - description - - schema - - schemaExtensions - - meta - SchemaExtension: - title: SchemaExtension + - dataType + - value + GetScoresV3Meta: + title: GetScoresV3Meta type: object properties: - schema: + limit: + type: integer + cursor: type: string - required: - type: boolean + nullable: true + description: >- + URL-safe base64 (base64url) cursor for the next page. Absent when + there are no more results. required: - - schema - - required - SchemasResponse: - title: SchemasResponse + - limit + GetScoresV3Response: + title: GetScoresV3Response type: object properties: - schemas: - type: array - items: - type: string - totalResults: - type: integer - Resources: + data: type: array items: - $ref: '#/components/schemas/SchemaResource' + $ref: '#/components/schemas/ScoreV3' + meta: + $ref: '#/components/schemas/GetScoresV3Meta' required: - - schemas - - totalResults - - Resources - SchemaResource: - title: SchemaResource + - data + - meta + CreateScoreRequest: + title: CreateScoreRequest type: object properties: id: type: string + nullable: true + traceId: + type: string + nullable: true + sessionId: + type: string + nullable: true + observationId: + type: string + nullable: true + datasetRunId: + type: string + nullable: true name: type: string - description: + 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 - attributes: - type: array - items: {} - meta: - $ref: '#/components/schemas/ResourceMeta' + nullable: true + metadata: + type: object + additionalProperties: true + nullable: true + environment: + type: string + nullable: true + description: >- + The environment of the score. Can be any lowercase alphanumeric + string with hyphens and underscores that does not start with + 'langfuse'. + queueId: + type: string + nullable: true + description: >- + The annotation queue referenced by the score. Indicates if score was + initially created while processing annotation queue. + dataType: + $ref: '#/components/schemas/ScoreDataType' + nullable: true + description: >- + The data type of the score. When passing a configId this field is + inferred. Otherwise, this field must be passed or will default to + numeric. + configId: + type: string + nullable: true + description: >- + Reference a score config on a score. The unique langfuse identifier + of a score config. When passing this field, the dataType and + stringValue fields are automatically populated. + source: + $ref: '#/components/schemas/CreateScoreSource' + nullable: true + description: >- + The source of the score. Defaults to API. Set to ANNOTATION to + prefill scores (e.g. from an LLM) for a human reviewer to verify in + an annotation queue. When source is ANNOTATION, a configId is + required unless dataType is CORRECTION. EVAL is reserved for + internal evaluator outputs and is not accepted on this endpoint. required: - - id - name - - description - - attributes - - meta - ScimUsersListResponse: - title: ScimUsersListResponse + - value + CreateScoreSource: + title: CreateScoreSource + type: string + enum: + - API + - ANNOTATION + description: |- + Source values accepted when creating a score via the public REST API. + EVAL is reserved for internal evaluator outputs and is intentionally not + exposed here — use commons.ScoreSource when reading scores. + CreateScoreResponse: + title: CreateScoreResponse type: object properties: - schemas: - type: array - items: - type: string - totalResults: - type: integer - startIndex: - type: integer - itemsPerPage: - type: integer - Resources: - type: array - items: - $ref: '#/components/schemas/ScimUser' + id: + type: string + description: The id of the created object in Langfuse required: - - schemas - - totalResults - - startIndex - - itemsPerPage - - Resources - ScimUser: - title: ScimUser + - id + GetScoresResponseTraceData: + title: GetScoresResponseTraceData type: object properties: - schemas: + userId: + type: string + nullable: true + description: The user ID associated with the trace referenced by score + tags: type: array items: type: string - id: + nullable: true + description: A list of tags associated with the trace referenced by score + environment: type: string - userName: + nullable: true + description: The environment of the trace referenced by score + sessionId: type: string - name: - $ref: '#/components/schemas/ScimName' - emails: - type: array - items: - $ref: '#/components/schemas/ScimEmail' - meta: - $ref: '#/components/schemas/UserMeta' - required: - - schemas - - id - - userName - - name - - emails - - meta - UserMeta: - title: UserMeta + 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: - resourceType: - type: string - created: - type: string - nullable: true - lastModified: - type: string + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' nullable: true - required: - - resourceType - ScimName: - title: ScimName + allOf: + - $ref: '#/components/schemas/CorrectionScore' + GetScoresResponseDataText: + title: GetScoresResponseDataText type: object properties: - formatted: - type: string + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' nullable: true - ScimEmail: - title: ScimEmail + allOf: + - $ref: '#/components/schemas/TextScore' + GetScoresResponseData: + title: GetScoresResponseData type: object properties: - primary: - type: boolean - value: - type: string - type: + dataType: type: string + enum: + - NUMERIC + - CATEGORICAL + - BOOLEAN + - CORRECTION + - TEXT + trace: + $ref: '#/components/schemas/GetScoresResponseTraceData' required: - - primary - - value - - type - EmptyResponse: - title: EmptyResponse - type: object - description: Empty response for 204 No Content responses - properties: {} - ScoreConfigs: - title: ScoreConfigs + - dataType + GetScoresResponse: + title: GetScoresResponse type: object properties: data: type: array items: - $ref: '#/components/schemas/ScoreConfig' + $ref: '#/components/schemas/GetScoresResponseData' meta: $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' + nullable: true required: - data - meta - CreateScoreConfigRequest: - title: CreateScoreConfigRequest + PaginatedSessions: + title: PaginatedSessions type: object properties: - name: - type: string - description: >- - Name of the score config. Max 35 characters. Only letters, numbers, - underscores, spaces, periods, parentheses, and hyphens are allowed. - dataType: - $ref: '#/components/schemas/ScoreConfigDataType' - categories: + data: type: array items: - $ref: '#/components/schemas/ConfigCategory' - nullable: true - description: >- - Configure custom categories for categorical scores. Pass a list of - objects with `label` and `value` properties. Categories are - autogenerated for boolean configs and cannot be passed - minValue: - type: number - format: double + $ref: '#/components/schemas/Session' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + _deprecation: + $ref: '#/components/schemas/Deprecation' nullable: true - description: >- - Configure a minimum value for numerical scores. If not set, the - minimum value defaults to -∞ - maxValue: - type: number - format: double + 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 - description: >- - Configure a maximum value for numerical scores. If not set, the - maximum value defaults to +∞ - description: + required: + - data + - meta + DeleteTraceResponse: + title: DeleteTraceResponse + type: object + properties: + message: type: string - nullable: true - description: >- - Description is shown across the Langfuse UI and can be used to e.g. - explain the config categories in detail, why a numeric range was - set, or provide additional context on config name or usage required: - - name - - dataType - UpdateScoreConfigRequest: - title: UpdateScoreConfigRequest + - message + Sort: + title: Sort + type: object + properties: + id: + type: string + required: + - id + unstableEvaluatorType: + title: unstableEvaluatorType + type: string + enum: + - llm_as_judge + - code + description: |- + The evaluator engine type. + + The unstable public API supports LLM-as-a-judge and code evaluators. + unstableCodeEvaluatorSourceCodeLanguage: + title: unstableCodeEvaluatorSourceCodeLanguage + type: string + enum: + - PYTHON + - TYPESCRIPT + description: Code evaluator runtime language. + unstableEvaluatorScope: + title: unstableEvaluatorScope + type: string + enum: + - project + - managed + description: |- + Where an evaluator comes from. + + - `project`: created in your project + - `managed`: provided by Langfuse + unstableEvaluationRuleTarget: + title: unstableEvaluationRuleTarget + type: string + enum: + - observation + - experiment + description: >- + The ingestion object type that should trigger evaluation runs. + + + Choose the target first, because it changes both the valid filter + columns and the valid variable-mapping sources: + + - `observation` evaluates live-ingested observations such as + generations, spans, and events. + It supports mapping from `input`, `output`, `metadata`, and `tool_calls`. + - `experiment` evaluates live experiment executions and can additionally + map `expected_output` and `experiment_item_metadata`. + It currently supports filtering by `datasetId`. + Discover valid dataset IDs with `GET /api/public/v2/datasets`, then use the returned dataset `id` values in your filter. + unstableEvaluationRuleStatus: + title: unstableEvaluationRuleStatus + type: string + enum: + - active + - inactive + - paused + description: >- + Effective runtime status of the evaluation rule. + + + - `active`: enabled and currently runnable. + + - `inactive`: disabled by configuration. + + - `paused`: enabled, but Langfuse has blocked execution until the + underlying issue is resolved. + unstableEvaluationRuleMappingSource: + title: unstableEvaluationRuleMappingSource + type: string + enum: + - input + - output + - metadata + - tool_calls + - expected_output + - experiment_item_metadata + description: >- + Source field used to populate a prompt variable. + + + Use these values when mapping evaluator prompt variables to live data. + + + Target-specific rules: + + - `target=observation` supports `input`, `output`, `metadata`, and + `tool_calls` + + - `target=experiment` supports `input`, `output`, `metadata`, + `tool_calls`, `expected_output`, and `experiment_item_metadata` + + + Source semantics: + + - `input`: the observation or experiment input payload + + - `output`: the observation or experiment output payload + + - `metadata`: the metadata object for the target. Combine with + `jsonPath` when you need one nested field instead of the whole object. + + - `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. Only valid + for `target=experiment`. + + - `experiment_item_metadata`: the experiment item's metadata object. + Only valid for `target=experiment`. + unstableEvaluatorModelConfig: + title: unstableEvaluatorModelConfig type: object + description: >- + Optional explicit model configuration for an evaluator. + + + If omitted, Langfuse uses the project's default evaluation model. + + If provided, the model must be available to the project when the + evaluator or evaluation rule is enabled. + + + To discover valid configured `provider` values for a project, call `GET + /api/public/llm-connections` and read the `provider` field from the + returned connections. + + Use a `provider` value that matches one of the connections already + configured in the same project. + + + Recovery guidance: + + - If evaluator creation returns `422` with + `code=evaluator_preflight_failed`, either provide a valid explicit + `modelConfig` here or configure the project's default evaluation model, + then retry the same request. properties: - isArchived: - type: boolean - nullable: true - description: The status of the score config showing if it is archived or not - name: + provider: type: string - nullable: true - description: >- - Name of the score config. Max 35 characters. Only letters, numbers, - underscores, spaces, periods, parentheses, and hyphens are allowed. - categories: - type: array - items: - $ref: '#/components/schemas/ConfigCategory' - nullable: true - description: >- - Configure custom categories for categorical scores. Pass a list of - objects with `label` and `value` properties. Categories are - autogenerated for boolean configs and cannot be passed - minValue: - type: number - format: double - nullable: true - description: >- - Configure a minimum value for numerical scores. If not set, the - minimum value defaults to -∞ - maxValue: - type: number - format: double - nullable: true description: >- - Configure a maximum value for numerical scores. If not set, the - maximum value defaults to +∞ - description: + Provider identifier to use for this evaluator, for example `openai` + or `anthropic`. + + + To discover valid values for the current project, call `GET + /api/public/llm-connections` and use one of the returned `provider` + values. + model: type: string - nullable: true description: >- - Description is shown across the Langfuse UI and can be used to e.g. - explain the config categories in detail, why a numeric range was - set, or provide additional context on config name or usage - ScoreSubjectTraceV3: - title: ScoreSubjectTraceV3 - type: object - properties: - id: - type: string - description: The trace ID. - required: - - id - ScoreSubjectObservationV3: - title: ScoreSubjectObservationV3 - type: object - properties: - id: - type: string - description: The observation ID. - traceId: - type: string - nullable: true - description: The parent trace ID, if available. - required: - - id - ScoreSubjectSessionV3: - title: ScoreSubjectSessionV3 - type: object - properties: - id: - type: string - description: The session ID. + Model identifier exposed by the provider, for example `gpt-4.1-mini`. required: - - id - ScoreSubjectExperimentV3: - title: ScoreSubjectExperimentV3 + - provider + - model + unstableEvaluatorOutputDataType: + title: unstableEvaluatorOutputDataType + type: string + enum: + - NUMERIC + - BOOLEAN + - CATEGORICAL + description: >- + Structured score type returned by an evaluator. + + + This controls the type of score value Langfuse stores for evaluation + results: + + - `NUMERIC`: a numeric score such as `0.82` + + - `BOOLEAN`: a boolean score such as `true` + + - `CATEGORICAL`: one or more category labels from a fixed list + unstableEvaluatorOutputFieldDefinition: + title: unstableEvaluatorOutputFieldDefinition type: object properties: - id: + description: type: string - description: The dataset run ID (experiment ID). + description: >- + Human-readable instructions for what the evaluator should return in + this field. required: - - id - ScoreSubjectV3: - title: ScoreSubjectV3 + - description + unstableEvaluatorOutputDefinition: + title: unstableEvaluatorOutputDefinition type: object properties: - kind: + dataType: type: string enum: - - trace - - observation - - session - - experiment - id: - type: string - description: The trace ID. - traceId: - type: string - nullable: true - description: The parent trace ID, if available. - required: - - kind - - id - BaseScoreV3: - title: BaseScoreV3 - type: object - properties: - id: - type: string - projectId: - type: string - name: - type: string - source: - $ref: '#/components/schemas/ScoreSource' - timestamp: - type: string - format: date-time - environment: - type: string - description: The environment from which this score originated. - createdAt: - type: string - format: date-time - updatedAt: - type: string - format: date-time - comment: - type: string - nullable: true - description: >- - Optional comment attached to the score. Present when "details" is - included in the fields parameter. - configId: - type: string - nullable: true - description: >- - The score config ID, if this score was created from a config. - Present when "details" is included in the fields parameter. - metadata: - type: object - additionalProperties: true - nullable: true - description: >- - Arbitrary metadata attached to the score. Present when "details" is - included in the fields parameter. - authorUserId: - type: string - nullable: true - description: >- - The user who created this score, if available. Present when - "annotation" is included in the fields parameter. - queueId: + - NUMERIC + - BOOLEAN + - CATEGORICAL + reasoning: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' + score: type: string - nullable: true - description: >- - The annotation queue this score belongs to, if any. Present when - "annotation" is included in the fields parameter. - subject: - $ref: '#/components/schemas/ScoreSubjectV3' - nullable: true - description: >- - The entity this score is attached to (trace, observation, session, - or experiment). Present when "subject" is included in the fields - parameter. - required: - - id - - projectId - - name - - source - - timestamp - - environment - - createdAt - - updatedAt - NumericScoreV3: - title: NumericScoreV3 - type: object - properties: - value: - type: number - format: double - description: The numeric value of the score. required: - - value - allOf: - - $ref: '#/components/schemas/BaseScoreV3' - BooleanScoreV3: - title: BooleanScoreV3 + - dataType + - reasoning + - score + unstablePublicNumericEvaluatorOutputDefinition: + title: unstablePublicNumericEvaluatorOutputDefinition type: object properties: - value: - type: boolean - description: The boolean value of the score. + dataType: + $ref: '#/components/schemas/unstableEvaluatorOutputDataType' + description: Always `NUMERIC`. + reasoning: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' + score: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' required: - - value - allOf: - - $ref: '#/components/schemas/BaseScoreV3' - CategoricalScoreV3: - title: CategoricalScoreV3 + - dataType + - reasoning + - score + unstablePublicBooleanEvaluatorOutputDefinition: + title: unstablePublicBooleanEvaluatorOutputDefinition type: object properties: - value: - type: string - description: The string category value of the score. + dataType: + $ref: '#/components/schemas/unstableEvaluatorOutputDataType' + description: Always `BOOLEAN`. + reasoning: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' + score: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' required: - - value - allOf: - - $ref: '#/components/schemas/BaseScoreV3' - TextScoreV3: - title: TextScoreV3 + - dataType + - reasoning + - score + unstablePublicCategoricalEvaluatorOutputScoreDefinition: + title: unstablePublicCategoricalEvaluatorOutputScoreDefinition type: object properties: - value: + description: type: string - description: The text content of the score. + categories: + type: array + items: + type: string + shouldAllowMultipleMatches: + type: boolean required: - - value - allOf: - - $ref: '#/components/schemas/BaseScoreV3' - CorrectionScoreV3: - title: CorrectionScoreV3 + - description + - categories + - shouldAllowMultipleMatches + unstablePublicCategoricalEvaluatorOutputDefinition: + title: unstablePublicCategoricalEvaluatorOutputDefinition type: object properties: - value: - type: string - description: The correction content of the score. Empty string if not set. + dataType: + $ref: '#/components/schemas/unstableEvaluatorOutputDataType' + description: Always `CATEGORICAL`. + reasoning: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' + score: + $ref: >- + #/components/schemas/unstablePublicCategoricalEvaluatorOutputScoreDefinition required: - - value - allOf: - - $ref: '#/components/schemas/BaseScoreV3' - ScoreV3: - title: ScoreV3 + - dataType + - reasoning + - score + unstablePublicEvaluatorOutputDefinition: + title: unstablePublicEvaluatorOutputDefinition type: object properties: dataType: @@ -12707,962 +14258,888 @@ components: - NUMERIC - BOOLEAN - CATEGORICAL - - TEXT - - CORRECTION - value: + reasoning: + $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' + score: type: string - description: The numeric value of the score. required: - dataType + - reasoning + - score + unstableEvaluationRuleStringFilterOperator: + title: unstableEvaluationRuleStringFilterOperator + type: string + enum: + - '=' + - contains + - does not contain + - starts with + - ends with + unstableEvaluationRuleNumberFilterOperator: + title: unstableEvaluationRuleNumberFilterOperator + type: string + enum: + - '=' + - '>' + - < + - '>=' + - <= + unstableEvaluationRuleOptionsFilterOperator: + title: unstableEvaluationRuleOptionsFilterOperator + type: string + enum: + - any of + - none of + unstableEvaluationRuleArrayOptionsFilterOperator: + title: unstableEvaluationRuleArrayOptionsFilterOperator + type: string + enum: + - any of + - none of + - all of + unstableEvaluationRuleBooleanFilterOperator: + title: unstableEvaluationRuleBooleanFilterOperator + type: string + enum: + - '=' + - <> + unstableEvaluationRuleNullFilterOperator: + title: unstableEvaluationRuleNullFilterOperator + type: string + enum: + - is null + - is not null + unstableDateTimeEvaluationRuleFilter: + title: unstableDateTimeEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' + description: Comparison operator for datetime values. + value: + type: string + format: date-time + description: Datetime value to compare against. + required: + - column + - operator - value - GetScoresV3Meta: - title: GetScoresV3Meta + unstableStringEvaluationRuleFilter: + title: unstableStringEvaluationRuleFilter type: object properties: - limit: - type: integer - cursor: + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator' + value: type: string - nullable: true - description: >- - URL-safe base64 (base64url) cursor for the next page. Absent when - there are no more results. required: - - limit - GetScoresV3Response: - title: GetScoresV3Response + - column + - operator + - value + unstableNumberEvaluationRuleFilter: + title: unstableNumberEvaluationRuleFilter type: object properties: - data: - type: array - items: - $ref: '#/components/schemas/ScoreV3' - meta: - $ref: '#/components/schemas/GetScoresV3Meta' + column: + type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' + value: + type: number + format: double required: - - data - - meta - GetScoresResponseTraceData: - title: GetScoresResponseTraceData + - column + - operator + - value + unstableStringOptionsEvaluationRuleFilter: + title: unstableStringOptionsEvaluationRuleFilter type: object properties: - userId: + column: type: string - nullable: true - description: The user ID associated with the trace referenced by score - tags: + description: Column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator' + value: 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 - type: object - properties: - dataType: - type: string - enum: - - NUMERIC - - CATEGORICAL - - BOOLEAN - - CORRECTION - - TEXT - trace: - $ref: '#/components/schemas/GetScoresResponseTraceData' + description: One or more allowed string values. required: - - dataType - GetScoresResponse: - title: GetScoresResponse + - column + - operator + - value + unstableArrayOptionsEvaluationRuleFilter: + title: unstableArrayOptionsEvaluationRuleFilter type: object properties: - data: + column: + type: string + description: Column to filter on. + operator: + $ref: >- + #/components/schemas/unstableEvaluationRuleArrayOptionsFilterOperator + value: type: array items: - $ref: '#/components/schemas/GetScoresResponseData' - meta: - $ref: '#/components/schemas/utilsMetaResponse' + type: string + description: One or more array elements to match. required: - - data - - meta - PaginatedSessions: - title: PaginatedSessions + - column + - operator + - value + unstableStringObjectEvaluationRuleFilter: + title: unstableStringObjectEvaluationRuleFilter type: object properties: - data: - type: array - items: - $ref: '#/components/schemas/Session' - meta: - $ref: '#/components/schemas/utilsMetaResponse' + column: + type: string + description: >- + Object-valued column to filter on. In the unstable public API this + is currently `metadata`. + key: + type: string + description: Top-level key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator' + value: + type: string required: - - data - - meta - Traces: - title: Traces + - column + - key + - operator + - value + unstableNumberObjectEvaluationRuleFilter: + title: unstableNumberObjectEvaluationRuleFilter type: object properties: - data: + column: + type: string + description: Object-valued column to filter on. + key: + type: string + description: Key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' + value: + type: number + format: double + required: + - column + - key + - operator + - value + unstableCategoryOptionsEvaluationRuleFilter: + title: unstableCategoryOptionsEvaluationRuleFilter + type: object + properties: + column: + type: string + description: Object-valued column to filter on. + key: + type: string + description: Key inside the object-valued column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator' + value: type: array items: - $ref: '#/components/schemas/TraceWithDetails' - meta: - $ref: '#/components/schemas/utilsMetaResponse' + type: string required: - - data - - meta - DeleteTraceResponse: - title: DeleteTraceResponse + - column + - key + - operator + - value + unstableBooleanEvaluationRuleFilter: + title: unstableBooleanEvaluationRuleFilter type: object properties: - message: + column: type: string + description: Column to filter on. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleBooleanFilterOperator' + value: + type: boolean required: - - message - Sort: - title: Sort + - column + - operator + - value + unstableNullEvaluationRuleFilter: + title: unstableNullEvaluationRuleFilter type: object properties: - id: + column: + type: string + description: >- + Column to filter on. In the unstable public API this is currently + `parentObservationId`. + operator: + $ref: '#/components/schemas/unstableEvaluationRuleNullFilterOperator' + value: type: string + nullable: true + description: >- + Ignored placeholder value. Clients may omit it or send an empty + string. required: - - id - unstableEvaluatorType: - title: unstableEvaluatorType - type: string - enum: - - llm_as_judge - - code - description: |- - The evaluator engine type. - - The unstable public API supports LLM-as-a-judge and code evaluators. - unstableCodeEvaluatorSourceCodeLanguage: - title: unstableCodeEvaluatorSourceCodeLanguage - type: string - enum: - - PYTHON - - TYPESCRIPT - description: Code evaluator runtime language. - unstableEvaluatorScope: - title: unstableEvaluatorScope - type: string - enum: - - project - - managed - description: |- - Where an evaluator comes from. - - - `project`: created in your project - - `managed`: provided by Langfuse - unstableEvaluationRuleTarget: - title: unstableEvaluationRuleTarget - type: string - enum: - - observation - - experiment - description: >- - The ingestion object type that should trigger evaluation runs. - - - Choose the target first, because it changes both the valid filter - columns and the valid variable-mapping sources: - - - `observation` evaluates live-ingested observations such as - generations, spans, and events. - It supports mapping from `input`, `output`, and `metadata`. - - `experiment` evaluates live experiment executions and can additionally - map `expected_output` and `experiment_item_metadata`. - It currently supports filtering by `datasetId`. - Discover valid dataset IDs with `GET /api/public/v2/datasets`, then use the returned dataset `id` values in your filter. - unstableEvaluationRuleStatus: - title: unstableEvaluationRuleStatus - type: string - enum: - - active - - inactive - - paused - description: >- - Effective runtime status of the evaluation rule. - - - - `active`: enabled and currently runnable. - - - `inactive`: disabled by configuration. - - - `paused`: enabled, but Langfuse has blocked execution until the - underlying issue is resolved. - unstableEvaluationRuleMappingSource: - title: unstableEvaluationRuleMappingSource - type: string - enum: - - input - - output - - metadata - - expected_output - - experiment_item_metadata + - column + - operator + unstableEvaluationRuleMapping: + title: unstableEvaluationRuleMapping + type: object description: >- - Source field used to populate a prompt variable. - - - Use these values when mapping evaluator prompt variables to live data. - - - Target-specific rules: - - - `target=observation` supports `input`, `output`, and `metadata` + Maps one evaluator variable to one source field from the target object. - - `target=experiment` supports `input`, `output`, `metadata`, - `expected_output`, and `experiment_item_metadata` + Manual mappings are used for `llm_as_judge` evaluators. `code` + evaluators use a fixed runtime mapping managed by Langfuse. - Source semantics: - - `input`: the observation or experiment input payload + How to build a valid mapping list: - - `output`: the observation or experiment output payload + 1. Create the evaluator or fetch it with `GET /evaluators/{id}`. - - `metadata`: the metadata object for the target. Combine with - `jsonPath` when you need one nested field instead of the whole object. + 2. Read the evaluator `variables` array. - - `expected_output`: the experiment item's expected output. Only valid - for `target=experiment`. + 3. Add exactly one mapping object for each variable in that array. - - `experiment_item_metadata`: the experiment item's metadata object. - Only valid for `target=experiment`. - unstableEvaluatorModelConfig: - title: unstableEvaluatorModelConfig - type: object - description: >- - Optional explicit model configuration for an evaluator. + 4. Use the variable name exactly as returned, without braces such as + `{{` or `}}`. + 5. Choose a `source` that is valid for the selected `target`. - If omitted, Langfuse uses the project's default evaluation model. - If provided, the model must be available to the project when the - evaluator or evaluation rule is enabled. + `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. - To discover valid configured `provider` values for a project, call `GET - /api/public/llm-connections` and read the `provider` field from the - returned connections. + Recovery guidance: - Use a `provider` value that matches one of the connections already - configured in the same project. + - `invalid_variable_mapping`: the variable name is unknown for this + evaluator, or the selected `source` is not valid for the chosen `target` + - `missing_variable_mapping`: one or more LLM-as-judge evaluator + variables are not mapped yet - Recovery guidance: + - `duplicate_variable_mapping`: the same evaluator variable appears more + than once - - If evaluator creation returns `422` with - `code=evaluator_preflight_failed`, either provide a valid explicit - `modelConfig` here or configure the project's default evaluation model, - then retry the same request. + - `invalid_json_path`: the JSONPath expression is malformed. Remove it + or correct it. properties: - provider: + variable: type: string description: >- - Provider identifier to use for this evaluator, 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/unstableEvaluationRuleMappingSource' description: >- - Model identifier exposed by the provider, for example `gpt-4.1-mini`. - required: - - provider - - model - unstableEvaluatorOutputDataType: - title: unstableEvaluatorOutputDataType - type: string - enum: - - NUMERIC - - BOOLEAN - - CATEGORICAL - description: >- - Structured score type returned by an evaluator. - + Source field that should populate the prompt variable. - This controls the type of score value Langfuse stores for evaluation - results: - - `NUMERIC`: a numeric score such as `0.82` + Quick reference: - - `BOOLEAN`: a boolean score such as `true` + - `target=observation`: `input`, `output`, `metadata`, `tool_calls` - - `CATEGORICAL`: one or more category labels from a fixed list - unstableEvaluatorOutputFieldDefinition: - title: unstableEvaluatorOutputFieldDefinition - type: object - properties: - description: + - `target=experiment`: `input`, `output`, `metadata`, `tool_calls`, + `expected_output`, `experiment_item_metadata` + jsonPath: type: string + nullable: true description: >- - Human-readable instructions for what the evaluator should return in - this field. + 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: - - description - unstableEvaluatorOutputDefinition: - title: unstableEvaluatorOutputDefinition + - variable + - source + unstableEvaluationRuleFilter: + title: unstableEvaluationRuleFilter type: object properties: - dataType: + type: type: string enum: - - NUMERIC - - BOOLEAN - - CATEGORICAL - reasoning: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - score: + - datetime + - string + - number + - stringOptions + - categoryOptions + - arrayOptions + - stringObject + - numberObject + - boolean + - 'null' + column: type: string - required: - - dataType - - reasoning - - score - unstablePublicNumericEvaluatorOutputDefinition: - title: unstablePublicNumericEvaluatorOutputDefinition - type: object - properties: - dataType: - $ref: '#/components/schemas/unstableEvaluatorOutputDataType' - description: Always `NUMERIC`. - reasoning: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - score: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - required: - - dataType - - reasoning - - score - unstablePublicBooleanEvaluatorOutputDefinition: - title: unstablePublicBooleanEvaluatorOutputDefinition - type: object - properties: - dataType: - $ref: '#/components/schemas/unstableEvaluatorOutputDataType' - description: Always `BOOLEAN`. - reasoning: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - score: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - required: - - dataType - - reasoning - - score - unstablePublicCategoricalEvaluatorOutputScoreDefinition: - title: unstablePublicCategoricalEvaluatorOutputScoreDefinition - type: object - properties: - description: + description: Column to filter on. + operator: type: string - categories: - type: array - items: - type: string - shouldAllowMultipleMatches: - type: boolean - required: - - description - - categories - - shouldAllowMultipleMatches - unstablePublicCategoricalEvaluatorOutputDefinition: - title: unstablePublicCategoricalEvaluatorOutputDefinition - type: object - properties: - dataType: - $ref: '#/components/schemas/unstableEvaluatorOutputDataType' - description: Always `CATEGORICAL`. - reasoning: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - score: - $ref: >- - #/components/schemas/unstablePublicCategoricalEvaluatorOutputScoreDefinition - required: - - dataType - - reasoning - - score - unstablePublicEvaluatorOutputDefinition: - title: unstablePublicEvaluatorOutputDefinition - type: object - properties: - dataType: + description: Comparison operator for datetime values. + value: type: string - enum: - - NUMERIC - - BOOLEAN - - CATEGORICAL - reasoning: - $ref: '#/components/schemas/unstableEvaluatorOutputFieldDefinition' - score: + description: Datetime value to compare against. + key: type: string + description: Key inside the object-valued column to filter on. required: - - dataType - - reasoning - - score - unstableEvaluationRuleStringFilterOperator: - title: unstableEvaluationRuleStringFilterOperator - type: string - enum: - - '=' - - contains - - does not contain - - starts with - - ends with - unstableEvaluationRuleNumberFilterOperator: - title: unstableEvaluationRuleNumberFilterOperator - type: string - enum: - - '=' - - '>' - - < - - '>=' - - <= - unstableEvaluationRuleOptionsFilterOperator: - title: unstableEvaluationRuleOptionsFilterOperator + - type + - column + - operator + unstableDashboardWidgetView: + title: unstableDashboardWidgetView type: string enum: - - any of - - none of - unstableEvaluationRuleArrayOptionsFilterOperator: - title: unstableEvaluationRuleArrayOptionsFilterOperator + - observations + - scores-numeric + - scores-boolean + - scores-categorical + unstableDashboardWidgetViewWithLegacy: + title: unstableDashboardWidgetViewWithLegacy type: string enum: - - any of - - none of - - all of - unstableEvaluationRuleBooleanFilterOperator: - title: unstableEvaluationRuleBooleanFilterOperator + - observations + - scores-numeric + - scores-boolean + - scores-categorical + - traces + description: |- + Widget data view. Responses may include the legacy `traces` value for + widgets created before this API existed. + unstableDashboardWidgetChartType: + title: unstableDashboardWidgetChartType type: string enum: - - '=' - - <> - unstableEvaluationRuleNullFilterOperator: - title: unstableEvaluationRuleNullFilterOperator + - LINE_TIME_SERIES + - AREA_TIME_SERIES + - BAR_TIME_SERIES + - HORIZONTAL_BAR + - VERTICAL_BAR + - PIE + - NUMBER + - HISTOGRAM + - PIVOT_TABLE + unstableDashboardWidgetMetricAggregation: + title: unstableDashboardWidgetMetricAggregation type: string enum: - - is null - - is not null - unstableDateTimeEvaluationRuleFilter: - title: unstableDateTimeEvaluationRuleFilter + - sum + - avg + - count + - max + - min + - p50 + - p75 + - p90 + - p95 + - p99 + - histogram + - uniq + unstableDashboardWidgetDimension: + title: unstableDashboardWidgetDimension + type: object + properties: + field: + type: string + required: + - field + unstableDashboardWidgetMetric: + title: unstableDashboardWidgetMetric type: object properties: - column: - type: string - description: Column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' - description: Comparison operator for datetime values. - value: + measure: type: string - format: date-time - description: Datetime value to compare against. + agg: + $ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation' required: - - column - - operator - - value - unstableStringEvaluationRuleFilter: - title: unstableStringEvaluationRuleFilter + - measure + - agg + unstableDashboardWidgetFilter: + title: unstableDashboardWidgetFilter type: object + description: >- + A filter in Langfuse filter-state shape. The `value` shape and the + + allowed operators depend on `type`: + + + | `type` | `value` | operators | + + |---|---|---| + + | `string` | string | `=`, `contains`, `does not contain`, `starts + with`, `ends with` | + + | `number` | number | `=`, `>`, `<`, `>=`, `<=` | + + | `datetime` | ISO datetime string | `>`, `<`, `>=`, `<=` | + + | `boolean` | boolean | `=`, `<>` | + + | `null` | `""` | `is null`, `is not null` | + + | `stringOptions` | list of strings | `any of`, `none of` | + + | `arrayOptions` | list of strings | `any of`, `none of`, `all of` | + + | `categoryOptions` | list of strings (requires `key`) | `any of`, `none + of` | + + | `stringObject` | string (requires `key`, e.g. a metadata key) | same + as `string` | + + | `numberObject` | number (requires `key`, e.g. a score name) | same as + `number` | + + | `booleanObject` | boolean (requires `key`) | `=`, `<>` | properties: column: type: string - description: Column to filter on. operator: - $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator' + type: string + type: + type: string value: + nullable: true + key: type: string + nullable: true required: - column - operator - - value - unstableNumberEvaluationRuleFilter: - title: unstableNumberEvaluationRuleFilter + - type + unstableDashboardWidgetChartConfig: + title: unstableDashboardWidgetChartConfig type: object + description: |- + Chart-specific widget configuration. + + `type` must match the top-level `chartType`. + `row_limit` applies to total-value charts and pivot tables. + `bins` applies to histograms. + `defaultSort` applies to pivot tables. properties: - column: - type: string - description: Column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' - value: - type: number - format: double + type: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + row_limit: + type: integer + nullable: true + show_value_labels: + type: boolean + nullable: true + bins: + type: integer + nullable: true + defaultSort: + $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort' + nullable: true required: - - column - - operator - - value - unstableStringOptionsEvaluationRuleFilter: - title: unstableStringOptionsEvaluationRuleFilter + - type + unstableDashboardWidgetDefaultSort: + title: unstableDashboardWidgetDefaultSort type: object properties: column: type: string - description: Column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator' - value: - type: array - items: - type: string - description: One or more allowed string values. + order: + $ref: '#/components/schemas/unstableDashboardWidgetSortOrder' required: - column - - operator - - value - unstableArrayOptionsEvaluationRuleFilter: - title: unstableArrayOptionsEvaluationRuleFilter + - order + unstableDashboardWidgetSortOrder: + title: unstableDashboardWidgetSortOrder + type: string + enum: + - ASC + - DESC + unstableDashboardWidgetChartConfigInput: + title: unstableDashboardWidgetChartConfigInput type: object + description: |- + Input-side chart config. `type` is optional and defaults to the + widget's `chartType`; when given it must match. properties: - column: + type: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + nullable: true + row_limit: + type: integer + nullable: true + show_value_labels: + type: boolean + nullable: true + bins: + type: integer + nullable: true + defaultSort: + $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort' + nullable: true + unstableCreateDashboardWidgetRequest: + title: unstableCreateDashboardWidgetRequest + type: object + properties: + name: type: string - description: Column to filter on. - operator: - $ref: >- - #/components/schemas/unstableEvaluationRuleArrayOptionsFilterOperator - value: + description: + type: string + nullable: true + description: Defaults to an empty string. + view: + $ref: '#/components/schemas/unstableDashboardWidgetView' + dimensions: type: array items: - type: string - description: One or more array elements to match. + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput' + nullable: true + description: Defaults to the plain config for `chartType`. required: - - column - - operator - - value - unstableStringObjectEvaluationRuleFilter: - title: unstableStringObjectEvaluationRuleFilter + - name + - view + - dimensions + - metrics + - filters + - chartType + unstableUpdateDashboardWidgetRequest: + title: unstableUpdateDashboardWidgetRequest type: object properties: - column: - type: string - description: >- - Object-valued column to filter on. In the unstable public API this - is currently `metadata`. - key: + name: type: string - description: Top-level key inside the object-valued column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleStringFilterOperator' - value: + nullable: true + description: type: string + nullable: true + view: + $ref: '#/components/schemas/unstableDashboardWidgetView' + nullable: true + dimensions: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + nullable: true + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + nullable: true + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfigInput' + nullable: true + unstableDashboardWidgetList: + title: unstableDashboardWidgetList + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidget' + meta: + $ref: '#/components/schemas/utilsMetaResponse' required: - - column - - key - - operator - - value - unstableNumberObjectEvaluationRuleFilter: - title: unstableNumberObjectEvaluationRuleFilter + - data + - meta + unstableDeleteDashboardWidgetResponse: + title: unstableDeleteDashboardWidgetResponse type: object properties: - column: - type: string - description: Object-valued column to filter on. - key: + message: type: string - description: Key inside the object-valued column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleNumberFilterOperator' - value: - type: number - format: double required: - - column - - key - - operator - - value - unstableCategoryOptionsEvaluationRuleFilter: - title: unstableCategoryOptionsEvaluationRuleFilter + - message + unstableDashboardWidget: + title: unstableDashboardWidget type: object properties: - column: + id: type: string - description: Object-valued column to filter on. - key: + createdAt: + type: string + format: date-time + updatedAt: + type: string + format: date-time + name: + type: string + description: type: string - description: Key inside the object-valued column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleOptionsFilterOperator' - value: + view: + $ref: '#/components/schemas/unstableDashboardWidgetViewWithLegacy' + dimensions: type: array items: - type: string + $ref: '#/components/schemas/unstableDashboardWidgetDimension' + metrics: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetMetric' + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + chartType: + $ref: '#/components/schemas/unstableDashboardWidgetChartType' + chartConfig: + $ref: '#/components/schemas/unstableDashboardWidgetChartConfig' required: - - column - - key - - operator - - value - unstableBooleanEvaluationRuleFilter: - title: unstableBooleanEvaluationRuleFilter + - id + - createdAt + - updatedAt + - name + - description + - view + - dimensions + - metrics + - filters + - chartType + - chartConfig + unstableDashboardPlacement: + title: unstableDashboardPlacement type: object properties: - column: + type: + type: string + enum: + - widget + - preset + id: + type: string + widgetId: + type: string + x: + type: integer + y: + type: integer + width: + type: integer + height: + type: integer + presetId: type: string - description: Column to filter on. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleBooleanFilterOperator' - value: - type: boolean required: - - column - - operator - - value - unstableNullEvaluationRuleFilter: - title: unstableNullEvaluationRuleFilter + - type + - id + - x + - y + - width + - height + unstableWidgetPlacement: + title: unstableWidgetPlacement type: object properties: - column: + id: type: string - description: >- - Column to filter on. In the unstable public API this is currently - `parentObservationId`. - operator: - $ref: '#/components/schemas/unstableEvaluationRuleNullFilterOperator' - value: + widgetId: type: string - nullable: true - description: >- - Ignored placeholder value. Clients may omit it or send an empty - string. + x: + type: integer + 'y': + type: integer + width: + type: integer + height: + type: integer required: - - column - - operator - unstableEvaluationRuleMapping: - title: unstableEvaluationRuleMapping + - id + - widgetId + - x + - 'y' + - width + - height + unstablePresetPlacement: + title: unstablePresetPlacement type: object - description: >- - Maps one evaluator variable to one source field from the target object. - - - 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 a `source` that is valid for the selected `target`. - - - `jsonPath` is optional. Use it only when the selected source is a JSON - object and you want to extract one nested field before inserting it into - the evaluator prompt. - - - Recovery guidance: - - - `invalid_variable_mapping`: the variable name is unknown for this - evaluator, or the selected `source` is not valid for the chosen `target` - - - `missing_variable_mapping`: one or more LLM-as-judge evaluator - variables are not mapped yet - - - `duplicate_variable_mapping`: the same evaluator variable appears more - than once - - - `invalid_json_path`: the JSONPath expression is malformed. Remove it - or correct it. properties: - variable: + id: type: string - description: >- - Prompt variable name without braces. - - - Example: for the prompt `Judge {{input}} against {{output}}`, use - `input` and `output`. - source: - $ref: '#/components/schemas/unstableEvaluationRuleMappingSource' - description: >- - Source field that should populate the prompt variable. - - - Quick reference: - - - `target=observation`: `input`, `output`, `metadata` - - - `target=experiment`: `input`, `output`, `metadata`, - `expected_output`, `experiment_item_metadata` - jsonPath: + presetId: type: string - nullable: true - description: >- - Optional JSONPath selector applied to the selected source before it - is passed to the evaluator prompt. - - - Requirements: - - - Must start with `$` - - - Must be a syntactically valid JSONPath expression - - - Most useful with `source=metadata` + x: + type: integer + 'y': + type: integer + width: + type: integer + height: + type: integer required: - - variable - - source - unstableEvaluationRuleFilter: - title: unstableEvaluationRuleFilter + - id + - presetId + - x + - 'y' + - width + - height + unstableCreateDashboardPlacementRequest: + title: unstableCreateDashboardPlacementRequest type: object properties: type: type: string enum: - - datetime - - string - - number - - stringOptions - - categoryOptions - - arrayOptions - - stringObject - - numberObject - - boolean - - 'null' - column: - type: string - description: Column to filter on. - operator: + - widget + - preset + id: type: string - description: Comparison operator for datetime values. - value: + nullable: true + description: Server-generated when omitted. + widgetId: type: string - description: Datetime value to compare against. - key: + x: + type: integer + nullable: true + description: Grid column (12-column grid). Defaults to `0`. + y: + type: integer + nullable: true + description: Grid row. Defaults to the first row below all existing tiles. + width: + type: integer + nullable: true + description: Width in grid columns. Defaults to `6`. + height: + type: integer + nullable: true + description: Height in grid rows. Defaults to `6`. + presetId: type: string - description: Key inside the object-valued column to filter on. required: - type - - column - - operator - unstableDashboardWidgetView: - title: unstableDashboardWidgetView - type: string - enum: - - observations - - scores-numeric - - scores-categorical - unstableDashboardWidgetChartType: - title: unstableDashboardWidgetChartType - type: string - enum: - - LINE_TIME_SERIES - - AREA_TIME_SERIES - - BAR_TIME_SERIES - - HORIZONTAL_BAR - - VERTICAL_BAR - - PIE - - NUMBER - - HISTOGRAM - - PIVOT_TABLE - unstableDashboardWidgetMetricAggregation: - title: unstableDashboardWidgetMetricAggregation - type: string - enum: - - sum - - avg - - count - - max - - min - - p50 - - p75 - - p90 - - p95 - - p99 - - histogram - - uniq - unstableDashboardWidgetDimension: - title: unstableDashboardWidgetDimension + unstableCreateWidgetPlacement: + title: unstableCreateWidgetPlacement type: object properties: - field: + id: type: string - required: - - field - unstableDashboardWidgetMetric: - title: unstableDashboardWidgetMetric - type: object - properties: - measure: + nullable: true + description: Server-generated when omitted. + widgetId: type: string - agg: - $ref: '#/components/schemas/unstableDashboardWidgetMetricAggregation' - required: - - measure - - agg - unstableDashboardWidgetFilter: - title: unstableDashboardWidgetFilter + x: + type: integer + nullable: true + description: Grid column (12-column grid). Defaults to `0`. + 'y': + type: integer + nullable: true + description: Grid row. Defaults to the first row below all existing tiles. + width: + type: integer + nullable: true + description: Width in grid columns. Defaults to `6`. + height: + type: integer + nullable: true + description: Height in grid rows. Defaults to `6`. + required: + - widgetId + unstableCreatePresetPlacement: + title: unstableCreatePresetPlacement type: object - description: >- - A dashboard widget filter in Langfuse filter-state shape. - - - Filter shapes depend on `type`, for example string filters use a string - `value`, - - option filters use a list of strings, and object filters include `key`. properties: - column: - type: string - operator: - type: string - type: + id: type: string - value: nullable: true - key: + description: Server-generated when omitted. + presetId: type: string + x: + type: integer + nullable: true + description: Grid column (12-column grid). Defaults to `0`. + 'y': + type: integer + nullable: true + description: Grid row. Defaults to the first row below all existing tiles. + width: + type: integer + nullable: true + description: Width in grid columns. Defaults to `6`. + height: + type: integer nullable: true + description: Height in grid rows. Defaults to `6`. required: - - column - - operator - - type - unstableDashboardWidgetChartConfig: - title: unstableDashboardWidgetChartConfig + - presetId + unstableUpdateDashboardPlacementRequest: + title: unstableUpdateDashboardPlacementRequest type: object - description: |- - Chart-specific widget configuration. - - `type` must match the top-level `chartType`. - `row_limit` applies to total-value charts and pivot tables. - `bins` applies to histograms. - `defaultSort` applies to pivot tables. properties: - type: - $ref: '#/components/schemas/unstableDashboardWidgetChartType' - row_limit: + x: type: integer nullable: true - show_value_labels: - type: boolean + description: Grid column (12-column grid). + 'y': + type: integer nullable: true - bins: + description: Grid row. + width: type: integer nullable: true - defaultSort: - $ref: '#/components/schemas/unstableDashboardWidgetDefaultSort' + description: Width in grid columns. + height: + type: integer nullable: true - required: - - type - unstableDashboardWidgetDefaultSort: - title: unstableDashboardWidgetDefaultSort + description: Height in grid rows. + unstableDeleteDashboardPlacementResponse: + title: unstableDeleteDashboardPlacementResponse type: object properties: - column: + message: type: string - order: - $ref: '#/components/schemas/unstableDashboardWidgetSortOrder' required: - - column - - order - unstableDashboardWidgetSortOrder: - title: unstableDashboardWidgetSortOrder - type: string - enum: - - ASC - - DESC - unstableCreateDashboardWidgetRequest: - title: unstableCreateDashboardWidgetRequest + - message + unstableDashboardDefinition: + title: unstableDashboardDefinition type: object properties: - name: - type: string - description: - type: string - view: - $ref: '#/components/schemas/unstableDashboardWidgetView' - dimensions: - type: array - items: - $ref: '#/components/schemas/unstableDashboardWidgetDimension' - metrics: - type: array - items: - $ref: '#/components/schemas/unstableDashboardWidgetMetric' - filters: + widgets: type: array items: - $ref: '#/components/schemas/unstableDashboardWidgetFilter' - chartType: - $ref: '#/components/schemas/unstableDashboardWidgetChartType' - chartConfig: - $ref: '#/components/schemas/unstableDashboardWidgetChartConfig' - minVersion: - type: integer - nullable: true + $ref: '#/components/schemas/unstableDashboardPlacement' required: - - name - - description - - view - - dimensions - - metrics - - filters - - chartType - - chartConfig - unstableDashboardWidget: - title: unstableDashboardWidget + - widgets + unstableDashboard: + title: unstableDashboard type: object properties: id: @@ -13677,39 +15154,79 @@ components: type: string description: type: string - view: - $ref: '#/components/schemas/unstableDashboardWidgetView' - dimensions: - type: array - items: - $ref: '#/components/schemas/unstableDashboardWidgetDimension' - metrics: - type: array - items: - $ref: '#/components/schemas/unstableDashboardWidgetMetric' + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' filters: type: array items: $ref: '#/components/schemas/unstableDashboardWidgetFilter' - chartType: - $ref: '#/components/schemas/unstableDashboardWidgetChartType' - chartConfig: - $ref: '#/components/schemas/unstableDashboardWidgetChartConfig' - minVersion: - type: integer + description: Dashboard-level filters applied to all widgets on the dashboard. required: - id - createdAt - updatedAt - name - description - - view - - dimensions - - metrics + - definition - filters - - chartType - - chartConfig - - minVersion + unstableDashboardList: + title: unstableDashboardList + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/unstableDashboard' + meta: + $ref: '#/components/schemas/utilsMetaResponse' + required: + - data + - meta + unstableCreateDashboardRequest: + title: unstableCreateDashboardRequest + type: object + properties: + name: + type: string + description: + type: string + nullable: true + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + required: + - name + unstableUpdateDashboardRequest: + title: unstableUpdateDashboardRequest + type: object + properties: + name: + type: string + nullable: true + description: + type: string + nullable: true + definition: + $ref: '#/components/schemas/unstableDashboardDefinition' + nullable: true + filters: + type: array + items: + $ref: '#/components/schemas/unstableDashboardWidgetFilter' + nullable: true + unstableDeleteDashboardResponse: + title: unstableDeleteDashboardResponse + type: object + properties: + message: + type: string + required: + - message unstablePublicApiErrorCode: title: unstablePublicApiErrorCode type: string @@ -13903,8 +15420,8 @@ components: required: - message - code - unstableEvaluationRule: - title: unstableEvaluationRule + unstableEvaluationRuleBase: + title: unstableEvaluationRuleBase type: object description: >- Live evaluation rule for incoming data. @@ -13953,9 +15470,6 @@ components: If you create a newer project version with the same evaluator name later, existing evaluation rules are moved to it automatically. - target: - $ref: '#/components/schemas/unstableEvaluationRuleTarget' - description: Target object type that should trigger scoring. enabled: type: boolean description: Desired enabled state configured by the client. @@ -13981,20 +15495,6 @@ components: Must be greater than `0` and less than or equal to `1`. - `1` means evaluate every matching target. - `0.25` means evaluate approximately 25% of matching targets. - filter: - type: array - items: - $ref: '#/components/schemas/unstableEvaluationRuleFilter' - description: >- - List of filter conditions used to decide whether a target should be - evaluated. - mapping: - type: array - items: - $ref: '#/components/schemas/unstableEvaluationRuleMapping' - description: >- - Variable mappings used to populate evaluator runtime variables from - the live target object. createdAt: type: string format: date-time @@ -14007,16 +15507,94 @@ components: - id - name - evaluator - - target - enabled - status - pausedReason - pausedMessage - sampling - - filter - - mapping - createdAt - updatedAt + unstableEvaluationRule: + title: unstableEvaluationRule + type: object + properties: + target: + $ref: '#/components/schemas/unstableEvaluationRuleTarget' + description: Target object type that should trigger scoring. + filter: + type: array + items: + $ref: '#/components/schemas/unstableEvaluationRuleFilter' + description: >- + List of filter conditions used to decide whether a target should be + evaluated. + mapping: + type: array + items: + $ref: '#/components/schemas/unstableEvaluationRuleMapping' + description: >- + Variable mappings used to populate evaluator runtime variables from + the live target object. + required: + - target + - filter + - mapping + allOf: + - $ref: '#/components/schemas/unstableEvaluationRuleBase' + unstableLegacyEvaluationRule: + title: unstableLegacyEvaluationRule + type: object + description: >- + Legacy trace- or dataset-level evaluation rule returned by list and get + for migration. + + + This resource is read-only through the unstable public API. Its mapping + preserves the trace, dataset item, or named observation that each + evaluator variable previously read from. Its filters use the persisted + legacy filter format so migration clients can read the configuration + without losing information. + properties: + target: + $ref: '#/components/schemas/unstableLegacyEvaluationRuleTarget' + delay: + type: integer + description: Delay in milliseconds before the legacy evaluation job runs. + timeScope: + type: array + items: + $ref: '#/components/schemas/unstableEvaluationRuleTimeScope' + description: >- + Whether the legacy rule evaluates newly ingested data, existing + data, or both. + filter: + type: array + items: + $ref: '#/components/schemas/unstableEvaluationRuleFilter' + description: Stored filters used by the legacy trace or dataset rule. + mapping: + type: array + items: + $ref: '#/components/schemas/unstableLegacyEvaluationRuleMapping' + description: >- + Stored variable mappings, including the trace, dataset item, or + named observation selected for each variable. + required: + - target + - delay + - timeScope + - filter + - mapping + allOf: + - $ref: '#/components/schemas/unstableEvaluationRuleBase' + unstableReadableEvaluationRule: + title: unstableReadableEvaluationRule + oneOf: + - $ref: '#/components/schemas/unstableEvaluationRule' + - $ref: '#/components/schemas/unstableLegacyEvaluationRule' + description: >- + Evaluation rule returned by list and get, including read-only legacy + trace and dataset rules. unstableEvaluationRules: title: unstableEvaluationRules type: object @@ -14025,7 +15603,7 @@ components: data: type: array items: - $ref: '#/components/schemas/unstableEvaluationRule' + $ref: '#/components/schemas/unstableReadableEvaluationRule' description: Evaluation rules in the current page. meta: $ref: '#/components/schemas/utilsMetaResponse' @@ -14338,6 +15916,67 @@ components: type: string enum: - llm_as_judge + unstableEvaluationRuleTimeScope: + title: unstableEvaluationRuleTimeScope + type: string + enum: + - NEW + - EXISTING + unstableLegacyEvaluationRuleTarget: + title: unstableLegacyEvaluationRuleTarget + type: string + enum: + - trace + - dataset + unstableLegacyEvaluationRuleMapping: + title: unstableLegacyEvaluationRuleMapping + type: object + description: >- + Maps one evaluator variable to a trace, dataset item, or field on a + named observation in a legacy rule. + properties: + variable: + type: string + description: Evaluator prompt variable populated by this mapping. + langfuseObject: + $ref: '#/components/schemas/unstableLegacyEvaluationObject' + description: >- + Trace, dataset item, or observation type from which the value is + read. + objectName: + type: string + nullable: true + description: >- + Observation name to match, or `null` when `langfuseObject` is + `trace` or `dataset_item`. + source: + type: string + description: Stored field selected from the trace, dataset item, or observation. + jsonPath: + type: string + nullable: true + description: Optional JSONPath selector applied to the selected field. + required: + - variable + - langfuseObject + - objectName + - source + unstableLegacyEvaluationObject: + title: unstableLegacyEvaluationObject + type: string + enum: + - trace + - span + - generation + - event + - agent + - tool + - chain + - retriever + - evaluator + - embedding + - guardrail + - dataset_item unstableEvaluationRuleEvaluator: title: unstableEvaluationRuleEvaluator type: object diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml new file mode 100644 index 0000000..441339a --- /dev/null +++ b/pnpm-lock.yaml @@ -0,0 +1,304 @@ +lockfileVersion: '9.0' + +settings: + autoInstallPeers: true + excludeLinksFromLockfile: false + +importers: + + .: + dependencies: + specli: + specifier: ^0.0.39 + version: 0.0.39(ai@6.0.240(zod@4.4.3))(zod@4.4.3) + devDependencies: + '@apidevtools/swagger-parser': + specifier: ^12.1.0 + version: 12.1.0(openapi-types@12.1.3) + '@types/bun': + specifier: ^1.3.14 + version: 1.3.14 + ajv: + specifier: ^8.17.1 + version: 8.20.0 + ajv-formats: + specifier: ^3.0.1 + version: 3.0.1(ajv@8.20.0) + yaml: + specifier: ^2.8.2 + version: 2.9.0 + +packages: + + '@ai-sdk/gateway@3.0.162': + resolution: {integrity: sha512-Ful2sKX4/5iRIULrbKAN88VSduJKVxEIqub84uBT4SZkhYnu6pfWaFEzZOrjCwMf+ScWuxiFSAkZeXFphTji2w==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/provider-utils@4.0.41': + resolution: {integrity: sha512-I7hhjfw01yEI8NkuAsT8Mv6xbWFr/lqLXMdaJQ2zWfXEpxog1eT7skDcv1+RY29/+5btzH8wD+vVvy48bk9oNQ==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + '@ai-sdk/provider@3.0.14': + resolution: {integrity: sha512-5X1k57JBJ4H7H1QjX7CnJYAB1I19r/trVZTMcSms7/kLNZ8RaU4Nt2agcwZzv82Hfx6Q7/TOLU7agAKeFfc8cA==} + engines: {node: '>=18'} + + '@apidevtools/json-schema-ref-parser@14.0.1': + resolution: {integrity: sha512-Oc96zvmxx1fqoSEdUmfmvvb59/KDOnUoJ7s2t7bISyAn0XEz57LCCw8k2Y4Pf3mwKaZLMciESALORLgfe2frCw==} + engines: {node: '>= 16'} + + '@apidevtools/openapi-schemas@2.1.0': + resolution: {integrity: sha512-Zc1AlqrJlX3SlpupFGpiLi2EbteyP7fXmUOGup6/DnkRgjP9bgMM/ag+n91rsv0U1Gpz0H3VILA/o3bW7Ua6BQ==} + engines: {node: '>=10'} + + '@apidevtools/swagger-methods@3.0.2': + resolution: {integrity: sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==} + + '@apidevtools/swagger-parser@12.1.0': + resolution: {integrity: sha512-e5mJoswsnAX0jG+J09xHFYQXb/bUc5S3pLpMxUuRUA2H8T2kni3yEoyz2R3Dltw5f4A6j6rPNMpWTK+iVDFlng==} + peerDependencies: + openapi-types: '>=7' + + '@fastify/busboy@2.1.1': + resolution: {integrity: sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==} + engines: {node: '>=14'} + + '@opentelemetry/api@1.9.1': + resolution: {integrity: sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==} + engines: {node: '>=8.0.0'} + + '@standard-schema/spec@1.1.0': + resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + + '@types/bun@1.3.14': + resolution: {integrity: sha512-h1hFqFVcvAvD9j9K7ZW7vd82aSA+rTdznZa+5bwvCwqSB1jmmfLcbIWhOLx1/+boy/xmjgCs/OMUL8hRJSmnPw==} + + '@types/json-schema@7.0.15': + resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} + + '@types/node@26.1.2': + resolution: {integrity: sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg==} + + '@vercel/oidc@3.2.0': + resolution: {integrity: sha512-UycprH3T6n3jH0k44NHMa7pnFHGu/N05MjojYr+Mc6I7obkoLIJujSWwin1pCvdy/eOxrI/l3uDLQsmcrOb4ug==} + engines: {node: '>= 20'} + + ai@6.0.240: + resolution: {integrity: sha512-nVytcmJmHAR+1UU3KlRQJ8Un8gePSAcbTfvShNGfbG9hYnQWKdyFRZWa4QBlKH5yiNLNqSS4Y9u0T0KcbY6FkA==} + engines: {node: '>=18'} + peerDependencies: + zod: ^3.25.76 || ^4.1.8 + + ajv-draft-04@1.0.0: + resolution: {integrity: sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==} + peerDependencies: + ajv: ^8.5.0 + peerDependenciesMeta: + ajv: + optional: true + + ajv-formats@3.0.1: + resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==} + peerDependencies: + ajv: ^8.0.0 + peerDependenciesMeta: + ajv: + optional: true + + ajv@8.20.0: + resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==} + + argparse@2.0.1: + resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==} + + bun-types@1.3.14: + resolution: {integrity: sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ==} + + call-me-maybe@1.0.2: + resolution: {integrity: sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==} + + commander@14.0.3: + resolution: {integrity: sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==} + engines: {node: '>=20'} + + eventsource-parser@3.1.0: + resolution: {integrity: sha512-kJezFj9YFAMLeORyi7aCLxLbD5/qWMQnoMVlVPyHIll7lgRJCc3JVln9Vgl9nwQi0YkMnhdGTMNn7CkRRAptMg==} + engines: {node: '>=18.0.0'} + + fast-deep-equal@3.1.3: + resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==} + + fast-uri@3.1.5: + resolution: {integrity: sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==} + + js-yaml@4.3.1: + resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==} + hasBin: true + + json-schema-traverse@1.0.0: + resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==} + + json-schema@0.4.0: + resolution: {integrity: sha512-es94M3nTIfsEPisRafak+HDLfHXnKBhV3vU5eqPcS3flIWqcxJWgXHXiey3YrpaNsanY5ei1VoYEbOzijuq9BA==} + + openapi-types@12.1.3: + resolution: {integrity: sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==} + + require-from-string@2.0.2: + resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==} + engines: {node: '>=0.10.0'} + + specli@0.0.39: + resolution: {integrity: sha512-1xS55AI1v0Rp8mQFvTJj3KeJj2Zpbl77X2VyCpWi2/RQUDpLAF6Op96Er8gpkVQ6EcPVxyMAySDQFdiyCLUlJA==} + hasBin: true + peerDependencies: + ai: ^6.0.0 + zod: ^4.0.0 + + undici-types@8.3.0: + resolution: {integrity: sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==} + + undici@5.29.0: + resolution: {integrity: sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==} + engines: {node: '>=14.0'} + + yaml@2.9.0: + resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==} + engines: {node: '>= 14.6'} + hasBin: true + + zod@4.4.3: + resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==} + +snapshots: + + '@ai-sdk/gateway@3.0.162(zod@4.4.3)': + dependencies: + '@ai-sdk/provider': 3.0.14 + '@ai-sdk/provider-utils': 4.0.41(zod@4.4.3) + '@vercel/oidc': 3.2.0 + zod: 4.4.3 + + '@ai-sdk/provider-utils@4.0.41(zod@4.4.3)': + dependencies: + '@ai-sdk/provider': 3.0.14 + '@standard-schema/spec': 1.1.0 + eventsource-parser: 3.1.0 + undici: 5.29.0 + zod: 4.4.3 + + '@ai-sdk/provider@3.0.14': + dependencies: + json-schema: 0.4.0 + + '@apidevtools/json-schema-ref-parser@14.0.1': + dependencies: + '@types/json-schema': 7.0.15 + js-yaml: 4.3.1 + + '@apidevtools/openapi-schemas@2.1.0': {} + + '@apidevtools/swagger-methods@3.0.2': {} + + '@apidevtools/swagger-parser@12.1.0(openapi-types@12.1.3)': + dependencies: + '@apidevtools/json-schema-ref-parser': 14.0.1 + '@apidevtools/openapi-schemas': 2.1.0 + '@apidevtools/swagger-methods': 3.0.2 + ajv: 8.20.0 + ajv-draft-04: 1.0.0(ajv@8.20.0) + call-me-maybe: 1.0.2 + openapi-types: 12.1.3 + + '@fastify/busboy@2.1.1': {} + + '@opentelemetry/api@1.9.1': {} + + '@standard-schema/spec@1.1.0': {} + + '@types/bun@1.3.14': + dependencies: + bun-types: 1.3.14 + + '@types/json-schema@7.0.15': {} + + '@types/node@26.1.2': + dependencies: + undici-types: 8.3.0 + + '@vercel/oidc@3.2.0': {} + + ai@6.0.240(zod@4.4.3): + dependencies: + '@ai-sdk/gateway': 3.0.162(zod@4.4.3) + '@ai-sdk/provider': 3.0.14 + '@ai-sdk/provider-utils': 4.0.41(zod@4.4.3) + '@opentelemetry/api': 1.9.1 + zod: 4.4.3 + + ajv-draft-04@1.0.0(ajv@8.20.0): + optionalDependencies: + ajv: 8.20.0 + + ajv-formats@3.0.1(ajv@8.20.0): + optionalDependencies: + ajv: 8.20.0 + + ajv@8.20.0: + dependencies: + fast-deep-equal: 3.1.3 + fast-uri: 3.1.5 + json-schema-traverse: 1.0.0 + require-from-string: 2.0.2 + + argparse@2.0.1: {} + + bun-types@1.3.14: + dependencies: + '@types/node': 26.1.2 + + call-me-maybe@1.0.2: {} + + commander@14.0.3: {} + + eventsource-parser@3.1.0: {} + + fast-deep-equal@3.1.3: {} + + fast-uri@3.1.5: {} + + js-yaml@4.3.1: + dependencies: + argparse: 2.0.1 + + json-schema-traverse@1.0.0: {} + + json-schema@0.4.0: {} + + openapi-types@12.1.3: {} + + require-from-string@2.0.2: {} + + specli@0.0.39(ai@6.0.240(zod@4.4.3))(zod@4.4.3): + dependencies: + '@apidevtools/swagger-parser': 12.1.0(openapi-types@12.1.3) + ai: 6.0.240(zod@4.4.3) + ajv: 8.20.0 + ajv-formats: 3.0.1(ajv@8.20.0) + commander: 14.0.3 + openapi-types: 12.1.3 + yaml: 2.9.0 + zod: 4.4.3 + + undici-types@8.3.0: {} + + undici@5.29.0: + dependencies: + '@fastify/busboy': 2.1.1 + + yaml@2.9.0: {} + + zod@4.4.3: {} diff --git a/scripts/openapi-deprecations.ts b/scripts/openapi-deprecations.ts new file mode 100644 index 0000000..e7094c5 --- /dev/null +++ b/scripts/openapi-deprecations.ts @@ -0,0 +1,29 @@ +const V3_DEPENDENT_OPERATIONS = new Set([ + "GET /api/public/traces", + "POST /api/public/traces", + "GET /api/public/traces/{traceId}", + "GET /api/public/observations", + "GET /api/public/observations/{observationId}", + "POST /api/public/events", + "POST /api/public/generations", + "PATCH /api/public/generations", + "POST /api/public/spans", + "PATCH /api/public/spans", + "GET /api/public/sessions", + "GET /api/public/sessions/{sessionId}", + "GET /api/public/scores", + "GET /api/public/scores/{scoreId}", + "GET /api/public/v2/scores", + "GET /api/public/v2/scores/{scoreId}", + "GET /api/public/metrics", + "GET /api/public/metrics/daily", + "POST /api/public/dataset-run-items", + "GET /api/public/dataset-run-items", + "GET /api/public/datasets/{datasetName}/runs", + "GET /api/public/datasets/{datasetName}/runs/{runName}", + "DELETE /api/public/datasets/{datasetName}/runs/{runName}", +]); + +export function isV3DependentOperation(path: string, method: string) { + return V3_DEPENDENT_OPERATIONS.has(`${method.toUpperCase()} ${path}`); +} diff --git a/scripts/patch-openapi.ts b/scripts/patch-openapi.ts index ebe1774..5b2a72c 100644 --- a/scripts/patch-openapi.ts +++ b/scripts/patch-openapi.ts @@ -13,7 +13,11 @@ import { parseDocument, type Document } from "yaml"; import { resolve } from "path"; import { parseArgs } from "util"; +import { isV3DependentOperation } from "./openapi-deprecations"; + const DEFAULT_OPENAPI_URL = "https://cloud.langfuse.com/generated/api/openapi.yml"; +const V3_DEPRECATED_PREFIX = "[DEPRECATED] "; +const V3_DEPRECATED_FALLBACK_SUMMARY = `${V3_DEPRECATED_PREFIX}Legacy API action`; const { values: args } = parseArgs({ args: process.argv.slice(2), @@ -183,6 +187,50 @@ if (paths?.items) { }); } +// Mark operations that require the legacy v3 data model. These return 404 after +// a Langfuse v4 deployment switches to events_only mode. +let deprecationCount = 0; +if (paths?.items) { + for (const pathPair of paths.items) { + const path = pathPair.key?.value; + const methods = pathPair.value; + if (typeof path !== "string" || !methods?.items) continue; + + for (const methodPair of methods.items) { + const method = methodPair.key?.value; + const operation = methodPair.value; + if ( + typeof method !== "string" || + !operation?.items || + !isV3DependentOperation(path, method) + ) { + continue; + } + + let changed = false; + if (operation.get("deprecated") !== true) { + operation.set("deprecated", true); + changed = true; + } + const summary = operation.get("summary"); + const deprecatedSummary = + typeof summary === "string" && summary.length > 0 + ? summary.startsWith(V3_DEPRECATED_PREFIX) + ? summary + : `${V3_DEPRECATED_PREFIX}${summary}` + : V3_DEPRECATED_FALLBACK_SUMMARY; + if (summary !== deprecatedSummary) { + operation.set("summary", deprecatedSummary); + changed = true; + } + if (!changed) continue; + + deprecationCount++; + console.log(`Deprecated operation: ${method.toUpperCase()} ${path}`); + } + } +} + // Patch operation descriptions with examples const examples: Record = { prompts_create: [ @@ -268,10 +316,12 @@ if (paths?.items) { } } -const dirty = patchCount > 0 || renameCount > 0; +const dirty = patchCount > 0 || renameCount > 0 || deprecationCount > 0; if (dirty) { writeFileSync(specPath, doc.toString({ singleQuote: true })); - console.log(`\nWrote patched spec to ${specPath} (${patchCount} schema(s), ${renameCount} param rename(s))`); + console.log( + `\nWrote patched spec to ${specPath} (${patchCount} schema(s), ${renameCount} param rename(s), ${deprecationCount} deprecated operation(s))`, + ); } else { console.log("No patches needed."); } diff --git a/src/cli.ts b/src/cli.ts index 2bad7f1..692e685 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -174,11 +174,10 @@ Options: Examples: langfuse api __schema List all available resources langfuse api --help Show actions for a resource - langfuse api traces list --limit 10 List traces langfuse api prompts list List prompts - langfuse api scores create --name quality \\ - --traceId --value 0.9 Create a score - langfuse api datasets create --name my-dataset Create a dataset`); + langfuse api prompts get --name my-prompt Get a prompt + langfuse api datasets create --name my-dataset Create a dataset + langfuse api dataset-items list --dataset-name List dataset items`); } function printApiHelp(resources: string[]): void {