@langfuse/core 5.10.0 → 5.10.1

package/dist/index.d.cts

@@ -480,7 +480,7 @@ declare const BlobStorageExportFrequency: {
  * - `OBSERVATIONS_V2`: same data model as the `/api/public/v2/observations` endpoint, plus scores. Columns are controlled by `exportFieldGroups`.
  * - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation columns of both portions are controlled by `exportFieldGroups`.
  *
- * **Note:** `OBSERVATIONS_V2` and the enriched-observations portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` rely on the enriched observations table (Langfuse Fast Preview / v4), which is currently available on Langfuse Cloud only. See https://langfuse.com/docs/v4.
+ * **Note:** which sources a deployment accepts depends on how far it has moved to the v4 data model. `OBSERVATIONS_V2` and the enriched-observations portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations table, so they require a deployment that already populates it. `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and observations tables, so they require a deployment that still populates those. A deployment part-way through the migration populates both and accepts every source. Selecting a source the deployment cannot serve is rejected with `400`, rather than exporting an empty result. See https://langfuse.com/docs/v4.
  */
 type BlobStorageExportSource = "LEGACY_TRACES_OBSERVATIONS" | "OBSERVATIONS_V2" | "LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS";
 declare const BlobStorageExportSource: {
@@ -542,7 +542,7 @@ interface CreateBlobStorageIntegrationRequest {
     /** Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true. */
     compressed?: boolean;
     /**
-     * Data to export. When omitted on update, the existing value is preserved. When omitted on create: integrations on Langfuse Cloud default to `OBSERVATIONS_V2`; self-hosted deployments fall back to `LEGACY_TRACES_OBSERVATIONS`. Required when `exportFieldGroups` is provided.
+     * Data to export. When omitted on update, the existing value is preserved. When omitted on create, the default is `OBSERVATIONS_V2` on Langfuse Cloud, and on self-hosted deployments `LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the deployment no longer populates the legacy tables. The default is never a source the deployment cannot serve. Required when `exportFieldGroups` is provided.
      *
      * **Cloud-only project deprecation gate (effective 2026-05-20):** For projects created on or after 2026-05-20 on Langfuse Cloud, `LEGACY_TRACES_OBSERVATIONS` and `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP 400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted deployments are unaffected.
      *
@@ -677,7 +677,7 @@ interface CreateCommentRequest {
     objectId: string;
     /** The content of the comment. May include markdown. Currently limited to 5000 characters. */
     content: string;
-    /** The id of the user who created the comment. */
+    /** The id of the user who created the comment. Must be a member of the organization that owns the project, otherwise an error will be thrown. */
     authorUserId?: string;
 }
 
@@ -3742,6 +3742,17 @@ interface GetMetricsV2Request {
      *   }
      * }
      * ```
+     *
+     * 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"
+     * }
+     * ```
      */
     query: string;
 }
@@ -3890,6 +3901,8 @@ interface GetObservationsV2Request {
     parseIoAsJson?: boolean;
     name?: string;
     userId?: string;
+    /** Filter by session ID. */
+    sessionId?: string;
     /** Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", "GUARDRAIL") */
     type?: string;
     traceId?: string;
@@ -4970,7 +4983,7 @@ interface CreateUserRequest {
     emails?: ScimEmail[];
     /** Whether the user is active */
     active?: boolean;
-    /** Initial password for the user */
+    /** Ignored. Accepted only for compatibility with identity providers that always send a password on user creation (Okta sends a placeholder value even when password sync is disabled). No credential is created for the user; provisioned users authenticate via SSO or set a password themselves through the password reset flow. */
     password?: string;
 }
 
@@ -6324,6 +6337,7 @@ interface EvaluationRuleMapping {
  * - `stringOptions`: `any of`, `none of`
  * - `arrayOptions`: `any of`, `none of`, `all of`
  * - `stringObject`: same operators as `string`
+ * - `boolean`: `"="`, `"<>"`
  * - `null`: `is null`, `is not null`
  *
  * Supported columns by target:
@@ -6338,6 +6352,7 @@ interface EvaluationRuleMapping {
  *   - `sessionId`: `string`
  *   - `tags`: `arrayOptions`, operators `any of` / `none of` / `all of`
  *   - `metadata`: `stringObject` with `key`
+ *   - `isRootObservation`: `boolean`, operators `=` / `<>`; true when the observation has no parent or is explicitly marked as an application root
  *   - `parentObservationId`: `null`, operators `is null` / `is not null`
  *   - `calledToolNames`: `arrayOptions`, operators `any of` / `none of` / `all of`
  *   - `toolCalls`: `number`
@@ -6376,6 +6391,14 @@ interface EvaluationRuleMapping {
  *
  * @example
  *     {
+ *         type: "boolean",
+ *         column: "isRootObservation",
+ *         operator: LangfuseAPI.unstable.EvaluationRuleBooleanFilterOperator.Equals,
+ *         value: true
+ *     }
+ *
+ * @example
+ *     {
  *         type: "arrayOptions",
  *         column: "tags",
  *         operator: LangfuseAPI.unstable.EvaluationRuleArrayOptionsFilterOperator.AnyOf,
@@ -9741,6 +9764,7 @@ declare class Metrics {
      * ## V2 Differences
      * - Supports `observations`, `scores-numeric`, `scores-boolean`, and `scores-categorical` views only (traces view not supported)
      * - Direct access to tags and release fields on observations
+     * - Semantic-root filtering and grouping through the v2-only `isRootObservation` dimension
      * - Backwards-compatible: traceName, traceRelease, traceVersion dimensions are still available on observations view
      * - High cardinality dimensions are not supported and will return a 400 error (see below)
      *
@@ -9765,6 +9789,7 @@ declare class Metrics {
      * - `providedModelName` - Name of the model used
      * - `promptName` - Name of the prompt used
      * - `promptVersion` - Version of the prompt used
+     * - `isRootObservation` - Boolean semantic-root status. `true` includes physical roots and app roots whose SDK parent is external (so `parentObservationId` may be non-null).
      * - `startTimeMonth` - Month of start_time in YYYY-MM format
      *
      * **Measures:**
@@ -11209,9 +11234,6 @@ declare class Scores {
     create(request: CreateScoreRequest, requestOptions?: Scores.RequestOptions): HttpResponsePromise<CreateScoreResponse>;
     private __create;
     /**
-     * **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
-     * is no longer available on Langfuse v4 and later.
-     *
      * Get a list of scores (supports both trace and session scores)
      *
      * @param {LangfuseAPI.GetScoresRequest} request
@@ -11229,9 +11251,6 @@ declare class Scores {
     getMany(request?: GetScoresRequest, requestOptions?: Scores.RequestOptions): HttpResponsePromise<GetScoresResponse>;
     private __getMany;
     /**
-     * **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
-     * instead. This endpoint is no longer available on Langfuse v4 and later.
-     *
      * Get a score (supports both trace and session scores)
      *
      * @param {string} scoreId - The unique langfuse identifier of a score

package/dist/index.d.ts

@@ -480,7 +480,7 @@ declare const BlobStorageExportFrequency: {
  * - `OBSERVATIONS_V2`: same data model as the `/api/public/v2/observations` endpoint, plus scores. Columns are controlled by `exportFieldGroups`.
  * - `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS`: both sets. Observation columns of both portions are controlled by `exportFieldGroups`.
  *
- * **Note:** `OBSERVATIONS_V2` and the enriched-observations portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` rely on the enriched observations table (Langfuse Fast Preview / v4), which is currently available on Langfuse Cloud only. See https://langfuse.com/docs/v4.
+ * **Note:** which sources a deployment accepts depends on how far it has moved to the v4 data model. `OBSERVATIONS_V2` and the enriched-observations portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the enriched observations table, so they require a deployment that already populates it. `LEGACY_TRACES_OBSERVATIONS` and the legacy portion of `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` read the legacy traces and observations tables, so they require a deployment that still populates those. A deployment part-way through the migration populates both and accepts every source. Selecting a source the deployment cannot serve is rejected with `400`, rather than exporting an empty result. See https://langfuse.com/docs/v4.
  */
 type BlobStorageExportSource = "LEGACY_TRACES_OBSERVATIONS" | "OBSERVATIONS_V2" | "LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS";
 declare const BlobStorageExportSource: {
@@ -542,7 +542,7 @@ interface CreateBlobStorageIntegrationRequest {
     /** Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true. */
     compressed?: boolean;
     /**
-     * Data to export. When omitted on update, the existing value is preserved. When omitted on create: integrations on Langfuse Cloud default to `OBSERVATIONS_V2`; self-hosted deployments fall back to `LEGACY_TRACES_OBSERVATIONS`. Required when `exportFieldGroups` is provided.
+     * Data to export. When omitted on update, the existing value is preserved. When omitted on create, the default is `OBSERVATIONS_V2` on Langfuse Cloud, and on self-hosted deployments `LEGACY_TRACES_OBSERVATIONS` — or `OBSERVATIONS_V2` where the deployment no longer populates the legacy tables. The default is never a source the deployment cannot serve. Required when `exportFieldGroups` is provided.
      *
      * **Cloud-only project deprecation gate (effective 2026-05-20):** For projects created on or after 2026-05-20 on Langfuse Cloud, `LEGACY_TRACES_OBSERVATIONS` and `LEGACY_TRACES_AND_ENRICHED_OBSERVATIONS` are rejected with HTTP 400. Use `OBSERVATIONS_V2` for all new integrations. Self-hosted deployments are unaffected.
      *
@@ -677,7 +677,7 @@ interface CreateCommentRequest {
     objectId: string;
     /** The content of the comment. May include markdown. Currently limited to 5000 characters. */
     content: string;
-    /** The id of the user who created the comment. */
+    /** The id of the user who created the comment. Must be a member of the organization that owns the project, otherwise an error will be thrown. */
     authorUserId?: string;
 }
 
@@ -3742,6 +3742,17 @@ interface GetMetricsV2Request {
      *   }
      * }
      * ```
+     *
+     * 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"
+     * }
+     * ```
      */
     query: string;
 }
@@ -3890,6 +3901,8 @@ interface GetObservationsV2Request {
     parseIoAsJson?: boolean;
     name?: string;
     userId?: string;
+    /** Filter by session ID. */
+    sessionId?: string;
     /** Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", "GUARDRAIL") */
     type?: string;
     traceId?: string;
@@ -4970,7 +4983,7 @@ interface CreateUserRequest {
     emails?: ScimEmail[];
     /** Whether the user is active */
     active?: boolean;
-    /** Initial password for the user */
+    /** Ignored. Accepted only for compatibility with identity providers that always send a password on user creation (Okta sends a placeholder value even when password sync is disabled). No credential is created for the user; provisioned users authenticate via SSO or set a password themselves through the password reset flow. */
     password?: string;
 }
 
@@ -6324,6 +6337,7 @@ interface EvaluationRuleMapping {
  * - `stringOptions`: `any of`, `none of`
  * - `arrayOptions`: `any of`, `none of`, `all of`
  * - `stringObject`: same operators as `string`
+ * - `boolean`: `"="`, `"<>"`
  * - `null`: `is null`, `is not null`
  *
  * Supported columns by target:
@@ -6338,6 +6352,7 @@ interface EvaluationRuleMapping {
  *   - `sessionId`: `string`
  *   - `tags`: `arrayOptions`, operators `any of` / `none of` / `all of`
  *   - `metadata`: `stringObject` with `key`
+ *   - `isRootObservation`: `boolean`, operators `=` / `<>`; true when the observation has no parent or is explicitly marked as an application root
  *   - `parentObservationId`: `null`, operators `is null` / `is not null`
  *   - `calledToolNames`: `arrayOptions`, operators `any of` / `none of` / `all of`
  *   - `toolCalls`: `number`
@@ -6376,6 +6391,14 @@ interface EvaluationRuleMapping {
  *
  * @example
  *     {
+ *         type: "boolean",
+ *         column: "isRootObservation",
+ *         operator: LangfuseAPI.unstable.EvaluationRuleBooleanFilterOperator.Equals,
+ *         value: true
+ *     }
+ *
+ * @example
+ *     {
  *         type: "arrayOptions",
  *         column: "tags",
  *         operator: LangfuseAPI.unstable.EvaluationRuleArrayOptionsFilterOperator.AnyOf,
@@ -9741,6 +9764,7 @@ declare class Metrics {
      * ## V2 Differences
      * - Supports `observations`, `scores-numeric`, `scores-boolean`, and `scores-categorical` views only (traces view not supported)
      * - Direct access to tags and release fields on observations
+     * - Semantic-root filtering and grouping through the v2-only `isRootObservation` dimension
      * - Backwards-compatible: traceName, traceRelease, traceVersion dimensions are still available on observations view
      * - High cardinality dimensions are not supported and will return a 400 error (see below)
      *
@@ -9765,6 +9789,7 @@ declare class Metrics {
      * - `providedModelName` - Name of the model used
      * - `promptName` - Name of the prompt used
      * - `promptVersion` - Version of the prompt used
+     * - `isRootObservation` - Boolean semantic-root status. `true` includes physical roots and app roots whose SDK parent is external (so `parentObservationId` may be non-null).
      * - `startTimeMonth` - Month of start_time in YYYY-MM format
      *
      * **Measures:**
@@ -11209,9 +11234,6 @@ declare class Scores {
     create(request: CreateScoreRequest, requestOptions?: Scores.RequestOptions): HttpResponsePromise<CreateScoreResponse>;
     private __create;
     /**
-     * **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
-     * is no longer available on Langfuse v4 and later.
-     *
      * Get a list of scores (supports both trace and session scores)
      *
      * @param {LangfuseAPI.GetScoresRequest} request
@@ -11229,9 +11251,6 @@ declare class Scores {
     getMany(request?: GetScoresRequest, requestOptions?: Scores.RequestOptions): HttpResponsePromise<GetScoresResponse>;
     private __getMany;
     /**
-     * **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
-     * instead. This endpoint is no longer available on Langfuse v4 and later.
-     *
      * Get a score (supports both trace and session scores)
      *
      * @param {string} scoreId - The unique langfuse identifier of a score

package/dist/index.mjs

@@ -276,7 +276,7 @@ var resetGlobalLogger = () => {
 // package.json
 var package_default = {
   name: "@langfuse/core",
-  version: "5.10.0",
+  version: "5.10.1",
   description: "Core functions and utilities for Langfuse packages",
   type: "module",
   sideEffects: false,
@@ -6711,9 +6711,6 @@ var Scores = class {
     }
   }
   /**
-   * **Deprecated.** Use `GET /api/public/v3/scores` instead. This endpoint
-   * is no longer available on Langfuse v4 and later.
-   *
    * Get a list of scores (supports both trace and session scores)
    *
    * @param {LangfuseAPI.GetScoresRequest} request
@@ -6912,9 +6909,6 @@ var Scores = class {
     }
   }
   /**
-   * **Deprecated.** Use `GET /api/public/v3/scores` with the `id` filter
-   * instead. This endpoint is no longer available on Langfuse v4 and later.
-   *
    * Get a score (supports both trace and session scores)
    *
    * @param {string} scoreId - The unique langfuse identifier of a score
@@ -7879,6 +7873,7 @@ var Metrics = class {
    * ## V2 Differences
    * - Supports `observations`, `scores-numeric`, `scores-boolean`, and `scores-categorical` views only (traces view not supported)
    * - Direct access to tags and release fields on observations
+   * - Semantic-root filtering and grouping through the v2-only `isRootObservation` dimension
    * - Backwards-compatible: traceName, traceRelease, traceVersion dimensions are still available on observations view
    * - High cardinality dimensions are not supported and will return a 400 error (see below)
    *
@@ -7903,6 +7898,7 @@ var Metrics = class {
    * - `providedModelName` - Name of the model used
    * - `promptName` - Name of the prompt used
    * - `promptVersion` - Version of the prompt used
+   * - `isRootObservation` - Boolean semantic-root status. `true` includes physical roots and app roots whose SDK parent is external (so `parentObservationId` may be non-null).
    * - `startTimeMonth` - Month of start_time in YYYY-MM format
    *
    * **Measures:**
@@ -8610,6 +8606,7 @@ var Observations = class {
       parseIoAsJson,
       name,
       userId,
+      sessionId,
       type: type_,
       traceId,
       level,
@@ -8643,6 +8640,9 @@ var Observations = class {
     if (userId != null) {
       _queryParams["userId"] = userId;
     }
+    if (sessionId != null) {
+      _queryParams["sessionId"] = sessionId;
+    }
     if (type_ != null) {
       _queryParams["type"] = type_;
     }