feat(api): update API spec from langfuse/langfuse efe3532 (#1425)

Co-authored-by: langfuse-bot <[email protected]>

Author: langfuse-bot

langfuse/api/__init__.py

@@ -134,6 +134,8 @@
     OpenAiResponseUsageSchema,
     OpenAiUsage,
     OptionalObservationBody,
+    OrganizationApiKey,
+    OrganizationApiKeysResponse,
     OrganizationProject,
     OrganizationProjectsResponse,
     OtelAttribute,
@@ -378,6 +380,8 @@
     "OpenAiResponseUsageSchema",
     "OpenAiUsage",
     "OptionalObservationBody",
+    "OrganizationApiKey",
+    "OrganizationApiKeysResponse",
     "OrganizationProject",
     "OrganizationProjectsResponse",
     "OtelAttribute",

langfuse/api/reference.md

@@ -3608,13 +3608,15 @@ client.observations.get_many()
 
 **filter:** `typing.Optional[str]` 
 
-JSON string containing an array of filter conditions. When provided, this takes precedence over legacy filter parameters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, type, level, environment, fromStartTime, ...).
+
+## Filter Structure
 Each filter condition has the following structure:
 ```json
 [
   {
     "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
-    "column": string,         // Required. Column to filter on
+    "column": string,         // Required. Column to filter on (see available columns below)
     "operator": string,       // Required. Operator based on type:
                               // - datetime: ">", "<", ">=", "<="
                               // - string: "=", "contains", "does not contain", "starts with", "ends with"
@@ -3631,6 +3633,78 @@ Each filter condition has the following structure:
   }
 ]
 ```
+
+## Available Columns
+
+### Core Observation Fields
+- `id` (string) - Observation ID
+- `type` (string) - Observation type (SPAN, GENERATION, EVENT)
+- `name` (string) - Observation name
+- `traceId` (string) - Associated trace ID
+- `startTime` (datetime) - Observation start time
+- `endTime` (datetime) - Observation end time
+- `environment` (string) - Environment tag
+- `level` (string) - Log level (DEBUG, DEFAULT, WARNING, ERROR)
+- `statusMessage` (string) - Status message
+- `version` (string) - Version tag
+
+### Performance Metrics
+- `latency` (number) - Latency in seconds (calculated: end_time - start_time)
+- `timeToFirstToken` (number) - Time to first token in seconds
+- `tokensPerSecond` (number) - Output tokens per second
+
+### Token Usage
+- `inputTokens` (number) - Number of input tokens
+- `outputTokens` (number) - Number of output tokens
+- `totalTokens` (number) - Total tokens (alias: `tokens`)
+
+### Cost Metrics
+- `inputCost` (number) - Input cost in USD
+- `outputCost` (number) - Output cost in USD
+- `totalCost` (number) - Total cost in USD
+
+### Model Information
+- `model` (string) - Provided model name
+- `promptName` (string) - Associated prompt name
+- `promptVersion` (number) - Associated prompt version
+
+### Structured Data
+- `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.
+
+### Scores (requires join with scores table)
+- `scores_avg` (number) - Average of numeric scores (alias: `scores`)
+- `score_categories` (categoryOptions) - Categorical score values
+
+### Associated Trace Fields (requires join with traces table)
+- `userId` (string) - User ID from associated trace
+- `traceName` (string) - Name from associated trace
+- `traceEnvironment` (string) - Environment from associated trace
+- `traceTags` (arrayOptions) - Tags from associated trace
+
+## Filter Examples
+```json
+[
+  {
+    "type": "string",
+    "column": "type",
+    "operator": "=",
+    "value": "GENERATION"
+  },
+  {
+    "type": "number",
+    "column": "latency",
+    "operator": ">=",
+    "value": 2.5
+  },
+  {
+    "type": "stringObject",
+    "column": "metadata",
+    "key": "environment",
+    "operator": "=",
+    "value": "production"
+  }
+]
+```
 
 </dd>
 </dl>
@@ -4330,6 +4404,71 @@ client.organizations.get_organization_projects()
 </dl>
 
 
+</dd>
+</dl>
+</details>
+
+<details><summary><code>client.organizations.<a href="src/langfuse/resources/organizations/client.py">get_organization_api_keys</a>()</code></summary>
+<dl>
+<dd>
+
+#### 📝 Description
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+Get all API keys for the organization associated with the API key (requires organization-scoped API key)
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### 🔌 Usage
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+```python
+from langfuse.client import FernLangfuse
+
+client = FernLangfuse(
+    x_langfuse_sdk_name="YOUR_X_LANGFUSE_SDK_NAME",
+    x_langfuse_sdk_version="YOUR_X_LANGFUSE_SDK_VERSION",
+    x_langfuse_public_key="YOUR_X_LANGFUSE_PUBLIC_KEY",
+    username="YOUR_USERNAME",
+    password="YOUR_PASSWORD",
+    base_url="https://yourhost.com/path/to/api",
+)
+client.organizations.get_organization_api_keys()
+
+```
+</dd>
+</dl>
+</dd>
+</dl>
+
+#### ⚙️ Parameters
+
+<dl>
+<dd>
+
+<dl>
+<dd>
+
+**request_options:** `typing.Optional[RequestOptions]` — Request-specific configuration.
+    
+</dd>
+</dl>
+</dd>
+</dl>
+
+
 </dd>
 </dl>
 </details>
@@ -7104,13 +7243,15 @@ client.trace.list()
 
 **filter:** `typing.Optional[str]` 
 
-JSON string containing an array of filter conditions. When provided, this takes precedence over legacy filter parameters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+JSON string containing an array of filter conditions. When provided, this takes precedence over query parameter filters (userId, name, sessionId, tags, version, release, environment, fromTimestamp, toTimestamp).
+
+## Filter Structure
 Each filter condition has the following structure:
 ```json
 [
   {
     "type": string,           // Required. One of: "datetime", "string", "number", "stringOptions", "categoryOptions", "arrayOptions", "stringObject", "numberObject", "boolean", "null"
-    "column": string,         // Required. Column to filter on
+    "column": string,         // Required. Column to filter on (see available columns below)
     "operator": string,       // Required. Operator based on type:
                               // - datetime: ">", "<", ">=", "<="
                               // - string: "=", "contains", "does not contain", "starts with", "ends with"
@@ -7127,6 +7268,86 @@ Each filter condition has the following structure:
   }
 ]
 ```
+
+## Available Columns
+
+### Core Trace Fields
+- `id` (string) - Trace ID
+- `name` (string) - Trace name
+- `timestamp` (datetime) - Trace timestamp
+- `userId` (string) - User ID
+- `sessionId` (string) - Session ID
+- `environment` (string) - Environment tag
+- `version` (string) - Version tag
+- `release` (string) - Release tag
+- `tags` (arrayOptions) - Array of tags
+- `bookmarked` (boolean) - Bookmark status
+
+### Structured Data
+- `metadata` (stringObject/numberObject/categoryOptions) - Metadata key-value pairs. Use `key` parameter to filter on specific metadata keys.
+
+### Aggregated Metrics (from observations)
+These metrics are aggregated from all observations within the trace:
+- `latency` (number) - Latency in seconds (time from first observation start to last observation end)
+- `inputTokens` (number) - Total input tokens across all observations
+- `outputTokens` (number) - Total output tokens across all observations
+- `totalTokens` (number) - Total tokens (alias: `tokens`)
+- `inputCost` (number) - Total input cost in USD
+- `outputCost` (number) - Total output cost in USD
+- `totalCost` (number) - Total cost in USD
+
+### Observation Level Aggregations
+These fields aggregate observation levels within the trace:
+- `level` (string) - Highest severity level (ERROR > WARNING > DEFAULT > DEBUG)
+- `warningCount` (number) - Count of WARNING level observations
+- `errorCount` (number) - Count of ERROR level observations
+- `defaultCount` (number) - Count of DEFAULT level observations
+- `debugCount` (number) - Count of DEBUG level observations
+
+### Scores (requires join with scores table)
+- `scores_avg` (number) - Average of numeric scores (alias: `scores`)
+- `score_categories` (categoryOptions) - Categorical score values
+
+## Filter Examples
+```json
+[
+  {
+    "type": "datetime",
+    "column": "timestamp",
+    "operator": ">=",
+    "value": "2024-01-01T00:00:00Z"
+  },
+  {
+    "type": "string",
+    "column": "userId",
+    "operator": "=",
+    "value": "user-123"
+  },
+  {
+    "type": "number",
+    "column": "totalCost",
+    "operator": ">=",
+    "value": 0.01
+  },
+  {
+    "type": "arrayOptions",
+    "column": "tags",
+    "operator": "all of",
+    "value": ["production", "critical"]
+  },
+  {
+    "type": "stringObject",
+    "column": "metadata",
+    "key": "customer_tier",
+    "operator": "=",
+    "value": "enterprise"
+  }
+]
+```
+
+## Performance Notes
+- Filtering on `userId`, `sessionId`, or `metadata` may enable skip indexes for better query performance
+- Score filters require a join with the scores table and may impact query performance
 
 </dd>
 </dl>

langfuse/api/resources/__init__.py

@@ -193,6 +193,8 @@
     MembershipResponse,
     MembershipRole,
     MembershipsResponse,
+    OrganizationApiKey,
+    OrganizationApiKeysResponse,
     OrganizationProject,
     OrganizationProjectsResponse,
 )
@@ -399,6 +401,8 @@
     "OpenAiResponseUsageSchema",
     "OpenAiUsage",
     "OptionalObservationBody",
+    "OrganizationApiKey",
+    "OrganizationApiKeysResponse",
     "OrganizationProject",
     "OrganizationProjectsResponse",
     "OtelAttribute",