feat(traces): add list_traces and get_trace endpoints

[kxzk]

TL;DR

Add list_traces and get_trace methods to the SDK for querying traces via the Langfuse public API.

Why

The SDK had no way to read traces back from Langfuse. These endpoints enable fetching trace data for debugging, monitoring, and building tooling on top of the SDK.

Checklist

• Has label
• Has linked issue
• Tests added for new behavior
• Docs updated (if user-facing)

Closes #

[Copilot]

Pull request overview

Adds trace read APIs to the Langfuse Ruby SDK so users can query traces back from the Langfuse public API for debugging/monitoring/tooling use cases.

Changes:

• Add Client#list_traces and Client#get_trace methods delegating to the API client.
• Add ApiClient#list_traces, #list_traces_paginated, and #get_trace plus query-param building for trace filters.
• Add specs for the new client and API client methods and update API reference docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
spec/langfuse/client_spec.rb	Adds client-level tests for list_traces and get_trace.
spec/langfuse/api_client_spec.rb	Adds API client tests covering params, filters, errors, and pagination response shape.
lib/langfuse/client.rb	Exposes list_traces / get_trace on the public SDK client.
lib/langfuse/api_client.rb	Implements HTTP calls + query param mapping for trace listing and fetching.
docs/API_REFERENCE.md	Documents the new Client#list_traces and Client#get_trace APIs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The Client#get_trace parameters table also uses || instead of standard Markdown | separators, so it likely won't render as a table. Please convert these rows to proper single-pipe table syntax.

[Copilot]

The parameters table markup uses double leading pipes (|| ...) which breaks GitHub-flavored Markdown table rendering. Update the header and rows to use single pipes (| ... |) consistently so the table renders correctly.

[greptile-apps]

Greptile Overview

Greptile Summary

Adds trace read support to the Ruby SDK by introducing list_traces and get_trace methods, wiring them through Langfuse::Client to Langfuse::ApiClient, and documenting their usage in the API reference. The PR also adds specs that validate both the client-facing API and the underlying request construction to the Langfuse public API.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk.
• Reviewed the changed code paths for request construction, parameter mapping, URL encoding, and delegation; no definite functional or runtime issues introduced were found, and specs cover the new behavior.
• No files require special attention

Important Files Changed

Filename	Overview
docs/API_REFERENCE.md	Documents new list_traces and get_trace SDK methods and their parameters/usage.
lib/langfuse/api_client.rb	Adds list_traces/get_trace API client methods plus parameter mapping for trace list queries.
lib/langfuse/client.rb	Exposes list_traces and get_trace on the high-level client by delegating to ApiClient.
spec/langfuse/api_client_spec.rb	Adds request/response specs for trace listing and retrieval, including query parameter mapping.
spec/langfuse/client_spec.rb	Adds high-level client specs ensuring list_traces/get_trace delegate correctly to ApiClient.

Sequence Diagram

sequenceDiagram
  autonumber
  participant U as User Code
  participant C as Langfuse::Client
  participant A as Langfuse::ApiClient
  participant F as Langfuse Public API

  U->>C: list_traces(params)
  C->>A: get("/api/public/traces", query: params)
  A->>F: HTTP GET /api/public/traces?...
  F-->>A: 200 JSON (trace list)
  A-->>C: parsed response
  C-->>U: traces

  U->>C: get_trace(trace_id)
  C->>A: get("/api/public/traces/{trace_id}")
  A->>F: HTTP GET /api/public/traces/{trace_id}
  F-->>A: 200 JSON (trace)
  A-->>C: parsed response
  C-->>U: trace

Loading