feat(api): update API spec from langfuse/langfuse b19a2f5

langfuse/api/blob_storage_integrations/client.py

@@ -150,7 +150,7 @@ def upsert_blob_storage_integration(
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
 
         export_source : typing.Optional[BlobStorageExportSource]
-            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.
 
@@ -427,7 +427,7 @@ async def upsert_blob_storage_integration(
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
 
         export_source : typing.Optional[BlobStorageExportSource]
-            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.
 

langfuse/api/blob_storage_integrations/raw_client.py

@@ -207,7 +207,7 @@ def upsert_blob_storage_integration(
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
 
         export_source : typing.Optional[BlobStorageExportSource]
-            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.
 
@@ -702,7 +702,7 @@ async def upsert_blob_storage_integration(
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
 
         export_source : typing.Optional[BlobStorageExportSource]
-            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.
 

langfuse/api/blob_storage_integrations/types/blob_storage_export_source.py

@@ -14,7 +14,7 @@ class BlobStorageExportSource(enum.StrEnum):
     - `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.
     """
 
     LEGACY_TRACES_OBSERVATIONS = "LEGACY_TRACES_OBSERVATIONS"

langfuse/api/blob_storage_integrations/types/create_blob_storage_integration_request.py

@@ -97,7 +97,7 @@ class CreateBlobStorageIntegrationRequest(UniversalBaseModel):
         typing.Optional[BlobStorageExportSource], FieldMetadata(alias="exportSource")
     ] = pydantic.Field(default=None)
     """
-    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.
 

langfuse/api/comments/client.py

@@ -56,7 +56,7 @@ def create(
             The content of the comment. May include markdown. Currently limited to 5000 characters.
 
         author_user_id : typing.Optional[str]
-            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.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -241,7 +241,7 @@ async def create(
             The content of the comment. May include markdown. Currently limited to 5000 characters.
 
         author_user_id : typing.Optional[str]
-            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.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

langfuse/api/comments/raw_client.py

@@ -54,7 +54,7 @@ def create(
             The content of the comment. May include markdown. Currently limited to 5000 characters.
 
         author_user_id : typing.Optional[str]
-            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.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
@@ -418,7 +418,7 @@ async def create(
             The content of the comment. May include markdown. Currently limited to 5000 characters.
 
         author_user_id : typing.Optional[str]
-            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.
 
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.

langfuse/api/comments/types/create_comment_request.py

@@ -39,7 +39,7 @@ class CreateCommentRequest(UniversalBaseModel):
         typing.Optional[str], FieldMetadata(alias="authorUserId")
     ] = pydantic.Field(default=None)
     """
-    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.
     """
 
     model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(

langfuse/api/metrics/client.py

@@ -32,6 +32,7 @@ def 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)
 
@@ -56,6 +57,7 @@ def 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:**
@@ -192,6 +194,17 @@ def metrics(
             }
             ```
 
+            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"
+            }
+            ```
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
@@ -245,6 +258,7 @@ async def 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)
 
@@ -269,6 +283,7 @@ async def 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:**
@@ -405,6 +420,17 @@ async def metrics(
             }
             ```
 
+            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"
+            }
+            ```
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 

langfuse/api/metrics/raw_client.py

@@ -29,6 +29,7 @@ def 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)
 
@@ -53,6 +54,7 @@ def 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:**
@@ -189,6 +191,17 @@ def metrics(
             }
             ```
 
+            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"
+            }
+            ```
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 
@@ -296,6 +309,7 @@ async def 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)
 
@@ -320,6 +334,7 @@ async def 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:**
@@ -456,6 +471,17 @@ async def metrics(
             }
             ```
 
+            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"
+            }
+            ```
+
         request_options : typing.Optional[RequestOptions]
             Request-specific configuration.
 

langfuse/api/observations/client.py

@@ -35,6 +35,7 @@ def get_many(
         parse_io_as_json: typing.Optional[bool] = None,
         name: typing.Optional[str] = None,
         user_id: typing.Optional[str] = None,
+        session_id: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
         trace_id: typing.Optional[str] = None,
         level: typing.Optional[ObservationLevel] = None,
@@ -103,6 +104,9 @@ def get_many(
 
         user_id : typing.Optional[str]
 
+        session_id : typing.Optional[str]
+            Filter by session ID.
+
         type : typing.Optional[str]
             Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", "GUARDRAIL")
 
@@ -274,6 +278,7 @@ def get_many(
             parse_io_as_json=parse_io_as_json,
             name=name,
             user_id=user_id,
+            session_id=session_id,
             type=type,
             trace_id=trace_id,
             level=level,
@@ -314,6 +319,7 @@ async def get_many(
         parse_io_as_json: typing.Optional[bool] = None,
         name: typing.Optional[str] = None,
         user_id: typing.Optional[str] = None,
+        session_id: typing.Optional[str] = None,
         type: typing.Optional[str] = None,
         trace_id: typing.Optional[str] = None,
         level: typing.Optional[ObservationLevel] = None,
@@ -382,6 +388,9 @@ async def get_many(
 
         user_id : typing.Optional[str]
 
+        session_id : typing.Optional[str]
+            Filter by session ID.
+
         type : typing.Optional[str]
             Filter by observation type (e.g., "GENERATION", "SPAN", "EVENT", "AGENT", "TOOL", "CHAIN", "RETRIEVER", "EVALUATOR", "EMBEDDING", "GUARDRAIL")
 
@@ -561,6 +570,7 @@ async def main() -> None:
             parse_io_as_json=parse_io_as_json,
             name=name,
             user_id=user_id,
+            session_id=session_id,
             type=type,
             trace_id=trace_id,
             level=level,