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

[langfuse-bot]

Important

Add filter parameter to list() in TraceClient and AsyncTraceClient for complex JSON-based filtering, updating reference.md accordingly.

• Behavior:
  • Add filter parameter to list() in TraceClient and AsyncTraceClient in client.py for complex filtering using JSON string.
  • filter takes precedence over legacy parameters (userId, name, sessionId, etc.).
• Documentation:
  • Update reference.md to include filter parameter details for client.trace.list() method.

^{This description was created by for e8cc2d9. You can customize this summary. It will automatically update as commits are pushed.}

Disclaimer: Experimental PR review

Greptile Overview

Updated On: 2025-10-08 08:35:04 UTC

Summary

This PR introduces a new advanced filtering system for the trace list API in the Langfuse Python SDK. The change adds an optional `filter` parameter to both synchronous and asynchronous `list` methods in the `TraceClient` class, allowing users to specify complex filter conditions using a JSON-based approach.

The new filter parameter accepts a JSON string containing an array of filter conditions, each with a specific structure that includes type, column, operator, value, and optionally a key field. It supports various data types including datetime, string, number, boolean, array options, and nested object filtering. The system provides multiple operators for each data type (equality, comparison, containment, null checks, etc.) and includes special handling for filtering on nested fields like metadata.

This enhancement represents a significant evolution from the existing individual filter parameters (userId, name, sessionId, tags, etc.) to a more sophisticated and flexible filtering mechanism. The new filter takes precedence over legacy parameters when provided, indicating this is part of a broader API modernization effort. The change maintains backward compatibility by keeping existing parameters optional and functional.

The implementation includes comprehensive documentation with detailed JSON schema examples, making it clear how to construct complex filter conditions. This fits into the broader Langfuse ecosystem by providing more granular control over trace retrieval, which is essential for observability and debugging workflows where users need to query traces based on complex criteria.

Important Files Changed

Changed Files

Filename	Score	Overview
langfuse/api/resources/trace/client.py	5/5	Added new optional filter parameter to both sync and async trace list methods with comprehensive documentation
langfuse/api/reference.md	5/5	Added detailed documentation for the new filter parameter with JSON schema examples and usage instructions

Confidence score: 5/5

• This PR is safe to merge with minimal risk as it only adds an optional parameter without modifying existing functionality
• Score reflects the non-breaking nature of the change and thorough documentation provided
• No files require special attention as both changes are well-documented additions to the API

Sequence Diagram

sequenceDiagram
    participant User
    participant Client as "Client Application"
    participant HTTPClient as "HTTP Client"
    participant API as "Langfuse API"

    %% Get Trace
    User->>Client: "Request trace by ID"
    Client->>HTTPClient: "GET /api/public/traces/{trace_id}"
    HTTPClient->>API: "HTTP GET Request"
    alt Success (200-299)
        API->>HTTPClient: "TraceWithFullDetails response"
        HTTPClient->>Client: "Parse JSON response"
        Client->>User: "Return trace details"
    else Error (400)
        API->>HTTPClient: "Bad Request Error"
        HTTPClient->>Client: "Raise Error exception"
        Client->>User: "Error response"
    else Error (401)
        API->>HTTPClient: "Unauthorized Error"
        HTTPClient->>Client: "Raise UnauthorizedError"
        Client->>User: "Unauthorized response"
    else Error (403)
        API->>HTTPClient: "Access Denied Error"
        HTTPClient->>Client: "Raise AccessDeniedError"
        Client->>User: "Access denied response"
    else Error (404)
        API->>HTTPClient: "Not Found Error"
        HTTPClient->>Client: "Raise NotFoundError"
        Client->>User: "Not found response"
    else Error (405)
        API->>HTTPClient: "Method Not Allowed Error"
        HTTPClient->>Client: "Raise MethodNotAllowedError"
        Client->>User: "Method not allowed response"
    else JSON Decode Error
        HTTPClient->>Client: "JSONDecodeError"
        Client->>Client: "Raise ApiError with status and body"
        Client->>User: "API error response"
    end

    %% Delete Trace
    User->>Client: "Request trace deletion by ID"
    Client->>HTTPClient: "DELETE /api/public/traces/{trace_id}"
    HTTPClient->>API: "HTTP DELETE Request"
    alt Success (200-299)
        API->>HTTPClient: "DeleteTraceResponse"
        HTTPClient->>Client: "Parse JSON response"
        Client->>User: "Return deletion response"
    else Error responses
        Note over API,User: "Same error handling pattern as GET"
    end

    %% List Traces
    User->>Client: "Request trace list with filters"
    Client->>HTTPClient: "GET /api/public/traces with query params"
    HTTPClient->>API: "HTTP GET Request with filters"
    alt Success (200-299)
        API->>HTTPClient: "Traces response"
        HTTPClient->>Client: "Parse JSON response"
        Client->>User: "Return traces list"
    else Error responses
        Note over API,User: "Same error handling pattern as GET"
    end

    %% Delete Multiple Traces
    User->>Client: "Request multiple trace deletion"
    Client->>HTTPClient: "DELETE /api/public/traces with trace_ids array"
    HTTPClient->>API: "HTTP DELETE Request with JSON body"
    alt Success (200-299)
        API->>HTTPClient: "DeleteTraceResponse"
        HTTPClient->>Client: "Parse JSON response"
        Client->>User: "Return deletion response"
    else Error responses
        Note over API,User: "Same error handling pattern as GET"
    end

Loading

[greptile-apps]

_{2 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}