feat(api): update API spec from langfuse/langfuse d59b6a3 (#1489)

langfuse-bot · langfuse-bot · web-flow · commit 3008a5372510 · 2026-01-03T07:55:31.000+01:00
Co-authored-by: langfuse-bot &lt;langfuse-bot@langfuse.com&gt;
diff --git a/langfuse/api/__init__.py b/langfuse/api/__init__.py
@@ -137,6 +137,7 @@
     OpenAiResponseUsageSchema,
     OpenAiUsage,
     OptionalObservationBody,
+    Organization,
     OrganizationApiKey,
     OrganizationApiKeysResponse,
     OrganizationProject,
@@ -187,6 +188,7 @@
     Score,
     ScoreBody,
     ScoreConfig,
+    ScoreConfigDataType,
     ScoreConfigs,
     ScoreDataType,
     ScoreEvent,
@@ -392,6 +394,7 @@
     "OpenAiResponseUsageSchema",
     "OpenAiUsage",
     "OptionalObservationBody",
+    "Organization",
     "OrganizationApiKey",
     "OrganizationApiKeysResponse",
     "OrganizationProject",
@@ -442,6 +445,7 @@
     "Score",
     "ScoreBody",
     "ScoreConfig",
+    "ScoreConfigDataType",
     "ScoreConfigs",
     "ScoreDataType",
     "ScoreEvent",
diff --git a/langfuse/api/reference.md b/langfuse/api/reference.md
@@ -3191,6 +3191,8 @@ JSON string containing the query parameters with the following structure:
 
 Get metrics from the Langfuse project using a query object.
 
+Consider using the [v2 metrics endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for better performance.
+
 For more details, see the [Metrics API documentation](https://langfuse.com/docs/metrics/features/metrics-api).
 </dd>
 </dl>
@@ -4007,7 +4009,9 @@ client.observations.get(
 <dl>
 <dd>
 
-Get a list of observations
+Get a list of observations.
+
+Consider using the [v2 observations endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations) for cursor-based pagination and field selection.
 </dd>
 </dl>
 </dd>
@@ -6666,7 +6670,7 @@ Create a score configuration (config). Score configs are used to define the stru
 <dd>
 
 ```python
-from langfuse import CreateScoreConfigRequest, ScoreDataType
+from langfuse import CreateScoreConfigRequest, ScoreConfigDataType
 from langfuse.client import FernLangfuse
 
 client = FernLangfuse(
@@ -6680,7 +6684,7 @@ client = FernLangfuse(
 client.score_configs.create(
     request=CreateScoreConfigRequest(
         name="name",
-        data_type=ScoreDataType.NUMERIC,
+        data_type=ScoreConfigDataType.NUMERIC,
     ),
 )
 
@@ -7157,6 +7161,14 @@ client.score_v_2.get()
 <dl>
 <dd>
 
+**fields:** `typing.Optional[str]` — Comma-separated list of field groups to include in the response. Available field groups: 'score' (core score fields), 'trace' (trace properties: userId, tags, environment). If not specified, both 'score' and 'trace' are returned by default. Example: 'score' to exclude trace data, 'score,trace' to include both. Note: When filtering by trace properties (using userId or traceTags parameters), the 'trace' field group must be included, otherwise a 400 error will be returned.
+    
+</dd>
+</dl>
+
+<dl>
+<dd>
+
 **request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
     
 </dd>
diff --git a/langfuse/api/resources/__init__.py b/langfuse/api/resources/__init__.py
@@ -92,6 +92,7 @@
     PricingTierOperator,
     Score,
     ScoreConfig,
+    ScoreConfigDataType,
     ScoreDataType,
     ScoreSource,
     ScoreV1,
@@ -211,6 +212,7 @@
     ApiKeyList,
     ApiKeyResponse,
     ApiKeySummary,
+    Organization,
     Project,
     ProjectDeletionResponse,
     Projects,
@@ -412,6 +414,7 @@
     "OpenAiResponseUsageSchema",
     "OpenAiUsage",
     "OptionalObservationBody",
+    "Organization",
     "OrganizationApiKey",
     "OrganizationApiKeysResponse",
     "OrganizationProject",
@@ -462,6 +465,7 @@
     "Score",
     "ScoreBody",
     "ScoreConfig",
+    "ScoreConfigDataType",
     "ScoreConfigs",
     "ScoreDataType",
     "ScoreEvent",
diff --git a/langfuse/api/resources/commons/__init__.py b/langfuse/api/resources/commons/__init__.py
@@ -32,6 +32,7 @@
     PricingTierOperator,
     Score,
     ScoreConfig,
+    ScoreConfigDataType,
     ScoreDataType,
     ScoreSource,
     ScoreV1,
@@ -92,6 +93,7 @@
     "PricingTierOperator",
     "Score",
     "ScoreConfig",
+    "ScoreConfigDataType",
     "ScoreDataType",
     "ScoreSource",
     "ScoreV1",
diff --git a/langfuse/api/resources/commons/types/__init__.py b/langfuse/api/resources/commons/types/__init__.py
@@ -31,6 +31,7 @@
 from .pricing_tier_operator import PricingTierOperator
 from .score import Score, Score_Boolean, Score_Categorical, Score_Numeric
 from .score_config import ScoreConfig
+from .score_config_data_type import ScoreConfigDataType
 from .score_data_type import ScoreDataType
 from .score_source import ScoreSource
 from .score_v_1 import ScoreV1, ScoreV1_Boolean, ScoreV1_Categorical, ScoreV1_Numeric
@@ -73,6 +74,7 @@
     "PricingTierOperator",
     "Score",
     "ScoreConfig",
+    "ScoreConfigDataType",
     "ScoreDataType",
     "ScoreSource",
     "ScoreV1",
diff --git a/langfuse/api/resources/commons/types/score_config.py b/langfuse/api/resources/commons/types/score_config.py
@@ -6,7 +6,7 @@
 from ....core.datetime_utils import serialize_datetime
 from ....core.pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
 from .config_category import ConfigCategory
-from .score_data_type import ScoreDataType
+from .score_config_data_type import ScoreConfigDataType
 
 
 class ScoreConfig(pydantic_v1.BaseModel):
@@ -19,7 +19,7 @@ class ScoreConfig(pydantic_v1.BaseModel):
     created_at: dt.datetime = pydantic_v1.Field(alias="createdAt")
     updated_at: dt.datetime = pydantic_v1.Field(alias="updatedAt")
     project_id: str = pydantic_v1.Field(alias="projectId")
-    data_type: ScoreDataType = pydantic_v1.Field(alias="dataType")
+    data_type: ScoreConfigDataType = pydantic_v1.Field(alias="dataType")
     is_archived: bool = pydantic_v1.Field(alias="isArchived")
     """
     Whether the score config is archived. Defaults to false
diff --git a/langfuse/api/resources/commons/types/score_config_data_type.py b/langfuse/api/resources/commons/types/score_config_data_type.py
@@ -0,0 +1,25 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import enum
+import typing
+
+T_Result = typing.TypeVar("T_Result")
+
+
+class ScoreConfigDataType(str, enum.Enum):
+    NUMERIC = "NUMERIC"
+    BOOLEAN = "BOOLEAN"
+    CATEGORICAL = "CATEGORICAL"
+
+    def visit(
+        self,
+        numeric: typing.Callable[[], T_Result],
+        boolean: typing.Callable[[], T_Result],
+        categorical: typing.Callable[[], T_Result],
+    ) -> T_Result:
+        if self is ScoreConfigDataType.NUMERIC:
+            return numeric()
+        if self is ScoreConfigDataType.BOOLEAN:
+            return boolean()
+        if self is ScoreConfigDataType.CATEGORICAL:
+            return categorical()
diff --git a/langfuse/api/resources/commons/types/score_data_type.py b/langfuse/api/resources/commons/types/score_data_type.py
@@ -10,16 +10,20 @@ class ScoreDataType(str, enum.Enum):
     NUMERIC = "NUMERIC"
     BOOLEAN = "BOOLEAN"
     CATEGORICAL = "CATEGORICAL"
+    CORRECTION = "CORRECTION"
 
     def visit(
         self,
         numeric: typing.Callable[[], T_Result],
         boolean: typing.Callable[[], T_Result],
         categorical: typing.Callable[[], T_Result],
+        correction: typing.Callable[[], T_Result],
     ) -> T_Result:
         if self is ScoreDataType.NUMERIC:
             return numeric()
         if self is ScoreDataType.BOOLEAN:
             return boolean()
         if self is ScoreDataType.CATEGORICAL:
             return categorical()
+        if self is ScoreDataType.CORRECTION:
+            return correction()
diff --git a/langfuse/api/resources/ingestion/types/score_body.py b/langfuse/api/resources/ingestion/types/score_body.py
@@ -33,7 +33,11 @@ class ScoreBody(pydantic_v1.BaseModel):
     dataset_run_id: typing.Optional[str] = pydantic_v1.Field(
         alias="datasetRunId", default=None
     )
-    name: str
+    name: str = pydantic_v1.Field()
+    """
+    The name of the score. Always overrides "output" for correction scores.
+    """
+
     environment: typing.Optional[str] = None
     queue_id: typing.Optional[str] = pydantic_v1.Field(alias="queueId", default=None)
     """
diff --git a/langfuse/api/resources/metrics/client.py b/langfuse/api/resources/metrics/client.py
@@ -25,6 +25,8 @@ def metrics(
         """
         Get metrics from the Langfuse project using a query object.
 
+        Consider using the [v2 metrics endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for better performance.
+
         For more details, see the [Metrics API documentation](https://langfuse.com/docs/metrics/features/metrics-api).
 
         Parameters
@@ -138,6 +140,8 @@ async def metrics(
         """
         Get metrics from the Langfuse project using a query object.
 
+        Consider using the [v2 metrics endpoint](/api-reference#tag/metricsv2/GET/api/public/v2/metrics) for better performance.
+
         For more details, see the [Metrics API documentation](https://langfuse.com/docs/metrics/features/metrics-api).
 
         Parameters
diff --git a/langfuse/api/resources/observations/client.py b/langfuse/api/resources/observations/client.py
@@ -111,7 +111,9 @@ def get_many(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ObservationsViews:
         """
-        Get a list of observations
+        Get a list of observations.
+
+        Consider using the [v2 observations endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations) for cursor-based pagination and field selection.
 
         Parameters
         ----------
@@ -412,7 +414,9 @@ async def get_many(
         request_options: typing.Optional[RequestOptions] = None,
     ) -> ObservationsViews:
         """
-        Get a list of observations
+        Get a list of observations.
+
+        Consider using the [v2 observations endpoint](/api-reference#tag/observationsv2/GET/api/public/v2/observations) for cursor-based pagination and field selection.
 
         Parameters
         ----------
diff --git a/langfuse/api/resources/projects/__init__.py b/langfuse/api/resources/projects/__init__.py
@@ -5,6 +5,7 @@
     ApiKeyList,
     ApiKeyResponse,
     ApiKeySummary,
+    Organization,
     Project,
     ProjectDeletionResponse,
     Projects,
@@ -15,6 +16,7 @@
     "ApiKeyList",
     "ApiKeyResponse",
     "ApiKeySummary",
+    "Organization",
     "Project",
     "ProjectDeletionResponse",
     "Projects",
diff --git a/langfuse/api/resources/projects/types/__init__.py b/langfuse/api/resources/projects/types/__init__.py
@@ -4,6 +4,7 @@
 from .api_key_list import ApiKeyList
 from .api_key_response import ApiKeyResponse
 from .api_key_summary import ApiKeySummary
+from .organization import Organization
 from .project import Project
 from .project_deletion_response import ProjectDeletionResponse
 from .projects import Projects
@@ -13,6 +14,7 @@
     "ApiKeyList",
     "ApiKeyResponse",
     "ApiKeySummary",
+    "Organization",
     "Project",
     "ProjectDeletionResponse",
     "Projects",
diff --git a/langfuse/api/resources/projects/types/organization.py b/langfuse/api/resources/projects/types/organization.py
@@ -0,0 +1,50 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import datetime as dt
+import typing
+
+from ....core.datetime_utils import serialize_datetime
+from ....core.pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
+
+
+class Organization(pydantic_v1.BaseModel):
+    id: str = pydantic_v1.Field()
+    """
+    The unique identifier of the organization
+    """
+
+    name: str = pydantic_v1.Field()
+    """
+    The name of the organization
+    """
+
+    def json(self, **kwargs: typing.Any) -> str:
+        kwargs_with_defaults: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        return super().json(**kwargs_with_defaults)
+
+    def dict(self, **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
+        kwargs_with_defaults_exclude_unset: typing.Any = {
+            "by_alias": True,
+            "exclude_unset": True,
+            **kwargs,
+        }
+        kwargs_with_defaults_exclude_none: typing.Any = {
+            "by_alias": True,
+            "exclude_none": True,
+            **kwargs,
+        }
+
+        return deep_union_pydantic_dicts(
+            super().dict(**kwargs_with_defaults_exclude_unset),
+            super().dict(**kwargs_with_defaults_exclude_none),
+        )
+
+    class Config:
+        frozen = True
+        smart_union = True
+        extra = pydantic_v1.Extra.allow
+        json_encoders = {dt.datetime: serialize_datetime}
diff --git a/langfuse/api/resources/projects/types/project.py b/langfuse/api/resources/projects/types/project.py
@@ -5,11 +5,17 @@
 
 from ....core.datetime_utils import serialize_datetime
 from ....core.pydantic_utilities import deep_union_pydantic_dicts, pydantic_v1
+from .organization import Organization
 
 
 class Project(pydantic_v1.BaseModel):
     id: str
     name: str
+    organization: Organization = pydantic_v1.Field()
+    """
+    The organization this project belongs to
+    """
+
     metadata: typing.Dict[str, typing.Any] = pydantic_v1.Field()
     """
     Metadata for the project
diff --git a/langfuse/api/resources/score_configs/client.py b/langfuse/api/resources/score_configs/client.py
diff --git a/langfuse/api/resources/score_configs/types/create_score_config_request.py b/langfuse/api/resources/score_configs/types/create_score_config_request.py
diff --git a/langfuse/api/resources/score_v_2/client.py b/langfuse/api/resources/score_v_2/client.py
