feat(api): update API spec from langfuse/langfuse 811f641 (#1738)

Co-authored-by: langfuse-bot <langfuse-bot@langfuse.com>

Author: langfuse-bot

langfuse/api/__init__.py

@@ -14,6 +14,7 @@
         dataset_items,
         dataset_run_items,
         datasets,
+        experiments,
         health,
         ingestion,
         legacy,
@@ -58,6 +59,7 @@
         BlobStorageExportSource,
         BlobStorageIntegrationDeletionResponse,
         BlobStorageIntegrationFileType,
+        BlobStorageIntegrationFileTypeResponse,
         BlobStorageIntegrationResponse,
         BlobStorageIntegrationStatusResponse,
         BlobStorageIntegrationType,
@@ -147,6 +149,13 @@
         PaginatedDatasetRuns,
         PaginatedDatasets,
     )
+    from .experiments import (
+        Experiment,
+        ExperimentItem,
+        ExperimentItemsResponse,
+        ExperimentsResponse,
+        ExperimentsResponseMeta,
+    )
     from .health import HealthResponse, ServiceUnavailableError
     from .ingestion import (
         BaseEvent,
@@ -352,6 +361,7 @@
     "BlobStorageExportSource": ".blob_storage_integrations",
     "BlobStorageIntegrationDeletionResponse": ".blob_storage_integrations",
     "BlobStorageIntegrationFileType": ".blob_storage_integrations",
+    "BlobStorageIntegrationFileTypeResponse": ".blob_storage_integrations",
     "BlobStorageIntegrationResponse": ".blob_storage_integrations",
     "BlobStorageIntegrationStatusResponse": ".blob_storage_integrations",
     "BlobStorageIntegrationType": ".blob_storage_integrations",
@@ -415,6 +425,11 @@
     "DeleteTraceResponse": ".trace",
     "EmptyResponse": ".scim",
     "Error": ".commons",
+    "Experiment": ".experiments",
+    "ExperimentItem": ".experiments",
+    "ExperimentItemsResponse": ".experiments",
+    "ExperimentsResponse": ".experiments",
+    "ExperimentsResponseMeta": ".experiments",
     "FilterConfig": ".scim",
     "GetCommentsResponse": ".comments",
     "GetMediaResponse": ".media",
@@ -601,6 +616,7 @@
     "dataset_items": ".dataset_items",
     "dataset_run_items": ".dataset_run_items",
     "datasets": ".datasets",
+    "experiments": ".experiments",
     "health": ".health",
     "ingestion": ".ingestion",
     "legacy": ".legacy",
@@ -676,6 +692,7 @@ def __dir__():
     "BlobStorageExportSource",
     "BlobStorageIntegrationDeletionResponse",
     "BlobStorageIntegrationFileType",
+    "BlobStorageIntegrationFileTypeResponse",
     "BlobStorageIntegrationResponse",
     "BlobStorageIntegrationStatusResponse",
     "BlobStorageIntegrationType",
@@ -739,6 +756,11 @@ def __dir__():
     "DeleteTraceResponse",
     "EmptyResponse",
     "Error",
+    "Experiment",
+    "ExperimentItem",
+    "ExperimentItemsResponse",
+    "ExperimentsResponse",
+    "ExperimentsResponseMeta",
     "FilterConfig",
     "GetCommentsResponse",
     "GetMediaResponse",
@@ -925,6 +947,7 @@ def __dir__():
     "dataset_items",
     "dataset_run_items",
     "datasets",
+    "experiments",
     "health",
     "ingestion",
     "legacy",

langfuse/api/blob_storage_integrations/__init__.py

@@ -13,6 +13,7 @@
         BlobStorageExportSource,
         BlobStorageIntegrationDeletionResponse,
         BlobStorageIntegrationFileType,
+        BlobStorageIntegrationFileTypeResponse,
         BlobStorageIntegrationResponse,
         BlobStorageIntegrationStatusResponse,
         BlobStorageIntegrationType,
@@ -27,6 +28,7 @@
     "BlobStorageExportSource": ".types",
     "BlobStorageIntegrationDeletionResponse": ".types",
     "BlobStorageIntegrationFileType": ".types",
+    "BlobStorageIntegrationFileTypeResponse": ".types",
     "BlobStorageIntegrationResponse": ".types",
     "BlobStorageIntegrationStatusResponse": ".types",
     "BlobStorageIntegrationType": ".types",
@@ -70,6 +72,7 @@ def __dir__():
     "BlobStorageExportSource",
     "BlobStorageIntegrationDeletionResponse",
     "BlobStorageIntegrationFileType",
+    "BlobStorageIntegrationFileTypeResponse",
     "BlobStorageIntegrationResponse",
     "BlobStorageIntegrationStatusResponse",
     "BlobStorageIntegrationType",

langfuse/api/blob_storage_integrations/client.py

@@ -144,7 +144,7 @@ def upsert_blob_storage_integration(
             Path prefix for exported files (must end with forward slash if provided)
 
         export_start_date : typing.Optional[dt.datetime]
-            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE)
+            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for timezone differences).
 
         compressed : typing.Optional[bool]
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
@@ -421,7 +421,7 @@ async def upsert_blob_storage_integration(
             Path prefix for exported files (must end with forward slash if provided)
 
         export_start_date : typing.Optional[dt.datetime]
-            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE)
+            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for timezone differences).
 
         compressed : typing.Optional[bool]
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.

langfuse/api/blob_storage_integrations/raw_client.py

@@ -201,7 +201,7 @@ def upsert_blob_storage_integration(
             Path prefix for exported files (must end with forward slash if provided)
 
         export_start_date : typing.Optional[dt.datetime]
-            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE)
+            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for timezone differences).
 
         compressed : typing.Optional[bool]
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.
@@ -696,7 +696,7 @@ async def upsert_blob_storage_integration(
             Path prefix for exported files (must end with forward slash if provided)
 
         export_start_date : typing.Optional[dt.datetime]
-            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE)
+            Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for timezone differences).
 
         compressed : typing.Optional[bool]
             Enable gzip compression for exported files (.csv.gz, .json.gz, .jsonl.gz). Defaults to true.

langfuse/api/blob_storage_integrations/types/__init__.py

@@ -14,6 +14,9 @@
         BlobStorageIntegrationDeletionResponse,
     )
     from .blob_storage_integration_file_type import BlobStorageIntegrationFileType
+    from .blob_storage_integration_file_type_response import (
+        BlobStorageIntegrationFileTypeResponse,
+    )
     from .blob_storage_integration_response import BlobStorageIntegrationResponse
     from .blob_storage_integration_status_response import (
         BlobStorageIntegrationStatusResponse,
@@ -31,6 +34,7 @@
     "BlobStorageExportSource": ".blob_storage_export_source",
     "BlobStorageIntegrationDeletionResponse": ".blob_storage_integration_deletion_response",
     "BlobStorageIntegrationFileType": ".blob_storage_integration_file_type",
+    "BlobStorageIntegrationFileTypeResponse": ".blob_storage_integration_file_type_response",
     "BlobStorageIntegrationResponse": ".blob_storage_integration_response",
     "BlobStorageIntegrationStatusResponse": ".blob_storage_integration_status_response",
     "BlobStorageIntegrationType": ".blob_storage_integration_type",
@@ -74,6 +78,7 @@ def __dir__():
     "BlobStorageExportSource",
     "BlobStorageIntegrationDeletionResponse",
     "BlobStorageIntegrationFileType",
+    "BlobStorageIntegrationFileTypeResponse",
     "BlobStorageIntegrationResponse",
     "BlobStorageIntegrationStatusResponse",
     "BlobStorageIntegrationType",

langfuse/api/blob_storage_integrations/types/blob_storage_integration_file_type_response.py

@@ -0,0 +1,34 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from ...core import enum
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class BlobStorageIntegrationFileTypeResponse(enum.StrEnum):
+    """
+    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).
+    """
+
+    JSON = "JSON"
+    CSV = "CSV"
+    JSONL = "JSONL"
+    PARQUET = "PARQUET"
+
+    def visit(
+        self,
+        json: typing.Callable[[], T_Result],
+        csv: typing.Callable[[], T_Result],
+        jsonl: typing.Callable[[], T_Result],
+        parquet: typing.Callable[[], T_Result],
+    ) -> T_Result:
+        if self is BlobStorageIntegrationFileTypeResponse.JSON:
+            return json()
+        if self is BlobStorageIntegrationFileTypeResponse.CSV:
+            return csv()
+        if self is BlobStorageIntegrationFileTypeResponse.JSONL:
+            return jsonl()
+        if self is BlobStorageIntegrationFileTypeResponse.PARQUET:
+            return parquet()

langfuse/api/blob_storage_integrations/types/blob_storage_integration_response.py

@@ -11,7 +11,9 @@
 from .blob_storage_export_frequency import BlobStorageExportFrequency
 from .blob_storage_export_mode import BlobStorageExportMode
 from .blob_storage_export_source import BlobStorageExportSource
-from .blob_storage_integration_file_type import BlobStorageIntegrationFileType
+from .blob_storage_integration_file_type_response import (
+    BlobStorageIntegrationFileTypeResponse,
+)
 from .blob_storage_integration_type import BlobStorageIntegrationType
 
 
@@ -34,7 +36,7 @@ class BlobStorageIntegrationResponse(UniversalBaseModel):
         bool, FieldMetadata(alias="forcePathStyle")
     ]
     file_type: typing_extensions.Annotated[
-        BlobStorageIntegrationFileType, FieldMetadata(alias="fileType")
+        BlobStorageIntegrationFileTypeResponse, FieldMetadata(alias="fileType")
     ]
     export_mode: typing_extensions.Annotated[
         BlobStorageExportMode, FieldMetadata(alias="exportMode")

langfuse/api/blob_storage_integrations/types/blob_storage_sync_status.py

@@ -12,8 +12,9 @@ class BlobStorageSyncStatus(enum.StrEnum):
     Sync status of the blob storage integration:
     - `disabled` — integration is not enabled
     - `error` — last export failed (see `lastError` for details)
-    - `idle` — enabled but has never exported yet
+    - `running` — an export job is currently being processed
     - `queued` — next export is overdue (`nextSyncAt` is in the past) and waiting to be picked up by the worker
+    - `idle` — enabled but has never exported yet and no export is queued
     - `up_to_date` — all available data has been exported; next export is scheduled for the future
 
     **ETL usage**: poll this endpoint and check for `up_to_date` status. Compare `lastSyncAt` against your
@@ -22,6 +23,7 @@ class BlobStorageSyncStatus(enum.StrEnum):
     """
 
     IDLE = "idle"
+    RUNNING = "running"
     QUEUED = "queued"
     UP_TO_DATE = "up_to_date"
     DISABLED = "disabled"
@@ -30,13 +32,16 @@ class BlobStorageSyncStatus(enum.StrEnum):
     def visit(
         self,
         idle: typing.Callable[[], T_Result],
+        running: typing.Callable[[], T_Result],
         queued: typing.Callable[[], T_Result],
         up_to_date: typing.Callable[[], T_Result],
         disabled: typing.Callable[[], T_Result],
         error: typing.Callable[[], T_Result],
     ) -> T_Result:
         if self is BlobStorageSyncStatus.IDLE:
             return idle()
+        if self is BlobStorageSyncStatus.RUNNING:
+            return running()
         if self is BlobStorageSyncStatus.QUEUED:
             return queued()
         if self is BlobStorageSyncStatus.UP_TO_DATE:

langfuse/api/blob_storage_integrations/types/create_blob_storage_integration_request.py

@@ -85,7 +85,7 @@ class CreateBlobStorageIntegrationRequest(UniversalBaseModel):
         typing.Optional[dt.datetime], FieldMetadata(alias="exportStartDate")
     ] = pydantic.Field(default=None)
     """
-    Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE)
+    Custom start date for exports (required when exportMode is FROM_CUSTOM_DATE). Must not be in the future (27 h tolerance for timezone differences).
     """
 
     compressed: typing.Optional[bool] = pydantic.Field(default=None)

langfuse/api/client.py

@@ -23,6 +23,7 @@
         DatasetRunItemsClient,
     )
     from .datasets.client import AsyncDatasetsClient, DatasetsClient
+    from .experiments.client import AsyncExperimentsClient, ExperimentsClient
     from .health.client import AsyncHealthClient, HealthClient
     from .ingestion.client import AsyncIngestionClient, IngestionClient
     from .legacy.client import AsyncLegacyClient, LegacyClient
@@ -131,6 +132,7 @@ def __init__(
         self._dataset_items: typing.Optional[DatasetItemsClient] = None
         self._dataset_run_items: typing.Optional[DatasetRunItemsClient] = None
         self._datasets: typing.Optional[DatasetsClient] = None
+        self._experiments: typing.Optional[ExperimentsClient] = None
         self._health: typing.Optional[HealthClient] = None
         self._ingestion: typing.Optional[IngestionClient] = None
         self._legacy: typing.Optional[LegacyClient] = None
@@ -208,6 +210,14 @@ def datasets(self):
             self._datasets = DatasetsClient(client_wrapper=self._client_wrapper)
         return self._datasets
 
+    @property
+    def experiments(self):
+        if self._experiments is None:
+            from .experiments.client import ExperimentsClient  # noqa: E402
+
+            self._experiments = ExperimentsClient(client_wrapper=self._client_wrapper)
+        return self._experiments
+
     @property
     def health(self):
         if self._health is None:
@@ -465,6 +475,7 @@ def __init__(
         self._dataset_items: typing.Optional[AsyncDatasetItemsClient] = None
         self._dataset_run_items: typing.Optional[AsyncDatasetRunItemsClient] = None
         self._datasets: typing.Optional[AsyncDatasetsClient] = None
+        self._experiments: typing.Optional[AsyncExperimentsClient] = None
         self._health: typing.Optional[AsyncHealthClient] = None
         self._ingestion: typing.Optional[AsyncIngestionClient] = None
         self._legacy: typing.Optional[AsyncLegacyClient] = None
@@ -544,6 +555,16 @@ def datasets(self):
             self._datasets = AsyncDatasetsClient(client_wrapper=self._client_wrapper)
         return self._datasets
 
+    @property
+    def experiments(self):
+        if self._experiments is None:
+            from .experiments.client import AsyncExperimentsClient  # noqa: E402
+
+            self._experiments = AsyncExperimentsClient(
+                client_wrapper=self._client_wrapper
+            )
+        return self._experiments
+
     @property
     def health(self):
         if self._health is None: