feat(traces): add list_traces and get_trace endpoints

Expose trace listing with full filter/pagination support and
single-trace fetch via the public API, with corresponding Client
delegation, tests, and API reference docs.

Author: kxzk

docs/API_REFERENCE.md

@@ -8,6 +8,7 @@ Complete method reference for the Langfuse Ruby SDK.
 - [Client Access](#client-access)
 - [Prompt Management](#prompt-management)
 - [Tracing & Observability](#tracing--observability)
+- [Traces](#traces)
 - [Scoring](#scoring)
 - [Datasets](#datasets)
 - [Experiments](#experiments)
@@ -513,6 +514,92 @@ obs.update(
 )
 ```
 
+## Traces
+
+### `Client#list_traces`
+
+List traces in the project.
+
+**Signature:**
+
+```ruby
+list_traces(page: nil, limit: nil, **filters)
+```
+
+**Parameters:**
+
+| Parameter        | Type          | Required | Description                                                                                                                   |
+| ---------------- | ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `page`           | Integer       | No       | Page number                                                                                                                   |
+| `limit`          | Integer       | No       | Results per page                                                                                                              |
+| `user_id`        | String        | No       | Filter by user ID                                                                                                             |
+| `name`           | String        | No       | Filter by trace name                                                                                                          |
+| `session_id`     | String        | No       | Filter by session ID                                                                                                          |
+| `from_timestamp` | Time          | No       | Filter traces after this time                                                                                                 |
+| `to_timestamp`   | Time          | No       | Filter traces before this time                                                                                                |
+| `order_by`       | String        | No       | Order by field                                                                                                                |
+| `tags`           | Array<String> | No       | Filter by tags                                                                                                                |
+| `version`        | String        | No       | Filter by version                                                                                                             |
+| `release`        | String        | No       | Filter by release                                                                                                             |
+| `environment`    | String        | No       | Filter by environment                                                                                                         |
+| `fields`         | String        | No       | Comma-separated field groups to include (e.g. `"core,scores,metrics"`). Available: `core`, `io`, `scores`, `observations`, `metrics`. All fields returned if omitted. |
+| `filter`         | String        | No       | JSON string for advanced filtering                                                                                            |
+
+**Returns:** `Array<Hash>` of trace data
+
+**Raises:**
+
+- `UnauthorizedError` if authentication fails
+- `ApiError` for other API errors
+
+**Examples:**
+
+```ruby
+# Basic listing
+traces = client.list_traces(page: 1, limit: 20)
+
+# Filter by user and name
+traces = client.list_traces(user_id: "user-123", name: "my-trace")
+
+# Time range with field selection
+traces = client.list_traces(
+  from_timestamp: Time.utc(2025, 1, 1),
+  to_timestamp: Time.utc(2025, 1, 31),
+  fields: "core,scores"
+)
+```
+
+### `Client#get_trace`
+
+Fetch a single trace by ID.
+
+**Signature:**
+
+```ruby
+get_trace(id) # => Hash
+```
+
+**Parameters:**
+
+| Parameter | Type   | Required | Description |
+| --------- | ------ | -------- | ----------- |
+| `id`      | String | Yes      | Trace ID    |
+
+**Returns:** `Hash` of trace data
+
+**Raises:**
+
+- `NotFoundError` if the trace doesn't exist
+- `UnauthorizedError` if authentication fails
+- `ApiError` for other API errors
+
+**Example:**
+
+```ruby
+trace = client.get_trace("trace-uuid-123")
+puts trace["name"]
+```
+
 ## Scoring
 
 ### `Client#create_score`

lib/langfuse/api_client.rb

@@ -285,6 +285,85 @@ def shutdown
       cache.shutdown if cache.respond_to?(:shutdown)
     end
 
+    # List traces in the project
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @param user_id [String, nil] Filter by user ID
+    # @param name [String, nil] Filter by trace name
+    # @param session_id [String, nil] Filter by session ID
+    # @param from_timestamp [Time, nil] Filter traces after this time
+    # @param to_timestamp [Time, nil] Filter traces before this time
+    # @param order_by [String, nil] Order by field
+    # @param tags [Array<String>, nil] Filter by tags
+    # @param version [String, nil] Filter by version
+    # @param release [String, nil] Filter by release
+    # @param environment [String, nil] Filter by environment
+    # @param fields [String, nil] Comma-separated field groups to include (e.g. "core,scores,metrics")
+    # @param filter [String, nil] JSON string for advanced filtering
+    # @return [Array<Hash>] Array of trace hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   traces = api_client.list_traces(page: 1, limit: 10, name: "my-trace")
+    # rubocop:disable Metrics/ParameterLists
+    def list_traces(page: nil, limit: nil, user_id: nil, name: nil, session_id: nil,
+                    from_timestamp: nil, to_timestamp: nil, order_by: nil,
+                    tags: nil, version: nil, release: nil, environment: nil,
+                    fields: nil, filter: nil)
+      result = list_traces_paginated(
+        page: page, limit: limit, user_id: user_id, name: name,
+        session_id: session_id, from_timestamp: from_timestamp,
+        to_timestamp: to_timestamp, order_by: order_by, tags: tags,
+        version: version, release: release, environment: environment,
+        fields: fields, filter: filter
+      )
+      result["data"] || []
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Full paginated response including "meta" for internal pagination use
+    #
+    # @api private
+    # @return [Hash] Full response hash with "data" array and "meta" pagination info
+    # rubocop:disable Metrics/ParameterLists
+    def list_traces_paginated(page: nil, limit: nil, user_id: nil, name: nil, session_id: nil,
+                              from_timestamp: nil, to_timestamp: nil, order_by: nil,
+                              tags: nil, version: nil, release: nil, environment: nil,
+                              fields: nil, filter: nil)
+      with_faraday_error_handling do
+        params = build_traces_params(
+          page: page, limit: limit, user_id: user_id, name: name,
+          session_id: session_id, from_timestamp: from_timestamp,
+          to_timestamp: to_timestamp, order_by: order_by, tags: tags,
+          version: version, release: release, environment: environment,
+          fields: fields, filter: filter
+        )
+        response = connection.get("/api/public/traces", params)
+        handle_response(response)
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Fetch a trace by ID
+    #
+    # @param id [String] Trace ID
+    # @return [Hash] The trace data
+    # @raise [NotFoundError] if the trace is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   trace = api_client.get_trace("trace-uuid-123")
+    def get_trace(id)
+      with_faraday_error_handling do
+        encoded_id = URI.encode_uri_component(id)
+        response = connection.get("/api/public/traces/#{encoded_id}")
+        handle_response(response)
+      end
+    end
+
     # List all datasets in the project
     #
     # @param page [Integer, nil] Optional page number for pagination
@@ -525,6 +604,23 @@ def build_dataset_items_params(dataset_name:, page:, limit:,
       }.compact
     end
 
+    # Build query params for list_traces, mapping snake_case to camelCase
+    # rubocop:disable Metrics/ParameterLists
+    def build_traces_params(page:, limit:, user_id:, name:, session_id:,
+                            from_timestamp:, to_timestamp:, order_by:,
+                            tags:, version:, release:, environment:, fields:, filter:)
+      {
+        page: page, limit: limit, userId: user_id, name: name,
+        sessionId: session_id,
+        fromTimestamp: from_timestamp&.iso8601,
+        toTimestamp: to_timestamp&.iso8601,
+        orderBy: order_by, tags: tags, version: version,
+        release: release, environment: environment, fields: fields,
+        filter: filter
+      }.compact
+    end
+    # rubocop:enable Metrics/ParameterLists
+
     # Fetch with SWR cache
     def fetch_with_swr_cache(cache_key, name, version, label)
       cache.fetch_with_stale_while_revalidate(cache_key) do

lib/langfuse/client.rb

@@ -439,6 +439,35 @@ def list_datasets(page: nil, limit: nil)
       api_client.list_datasets(page: page, limit: limit)
     end
 
+    # List traces in the project
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @param filters [Hash] Additional filters (user_id, name, session_id, etc.)
+    # @return [Array<Hash>] Array of trace hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   traces = client.list_traces(page: 1, limit: 10, name: "my-trace")
+    def list_traces(page: nil, limit: nil, **filters)
+      api_client.list_traces(page: page, limit: limit, **filters)
+    end
+
+    # Fetch a trace by ID
+    #
+    # @param id [String] Trace ID
+    # @return [Hash] The trace data
+    # @raise [NotFoundError] if the trace is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   trace = client.get_trace("trace-uuid-123")
+    def get_trace(id)
+      api_client.get_trace(id)
+    end
+
     # Create a new dataset item
     #
     # @param dataset_name [String] Name of the dataset to add item to (required)