Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hassiebp merged 1 commit into from
Nov 3, 2025
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions langfuse/api/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,8 @@
OpenAiResponseUsageSchema,
OpenAiUsage,
OptionalObservationBody,
OrganizationApiKey,
OrganizationApiKeysResponse,
OrganizationProject,
OrganizationProjectsResponse,
OtelAttribute,
Expand Down Expand Up @@ -378,6 +380,8 @@
"OpenAiResponseUsageSchema",
"OpenAiUsage",
"OptionalObservationBody",
"OrganizationApiKey",
"OrganizationApiKeysResponse",
"OrganizationProject",
"OrganizationProjectsResponse",
"OtelAttribute",
Expand Down
229 changes: 225 additions & 4 deletions langfuse/api/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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"
Expand All @@ -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>
Expand Down
4 changes: 4 additions & 0 deletions langfuse/api/resources/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,8 @@
MembershipResponse,
MembershipRole,
MembershipsResponse,
OrganizationApiKey,
OrganizationApiKeysResponse,
OrganizationProject,
OrganizationProjectsResponse,
)
Expand Down Expand Up @@ -399,6 +401,8 @@
"OpenAiResponseUsageSchema",
"OpenAiUsage",
"OptionalObservationBody",
"OrganizationApiKey",
"OrganizationApiKeysResponse",
"OrganizationProject",
"OrganizationProjectsResponse",
"OtelAttribute",
Expand Down
Loading