CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview
Eval results
Files

comments-annotations.mddocs/

Comments and Annotations

The Comments and Annotations APIs provide management of comments on traces, observations, sessions, and prompts, as well as annotation queues for human review workflows.

Capabilities

CommentsClient

Client for managing comments on various objects.

/**
 * Create a comment
 * Can be attached to traces, observations, sessions, or prompts
 *
 * @param request Comment definition
 * @param requestOptions Optional request configuration
 */
CreateCommentResponse create(CreateCommentRequest request);
CreateCommentResponse create(CreateCommentRequest request, RequestOptions requestOptions);

/**
 * Get all comments with optional filters
 *
 * @param request Optional filters (objectType, objectId, author, pagination)
 * @param requestOptions Optional request configuration
 */
GetCommentsResponse get();
GetCommentsResponse get(GetCommentsRequest request);
GetCommentsResponse get(GetCommentsRequest request, RequestOptions requestOptions);

/**
 * Get a comment by ID
 *
 * @param commentId Comment ID
 * @param requestOptions Optional request configuration
 */
Comment getById(String commentId);
Comment getById(String commentId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.comments.types.*;
import com.langfuse.client.resources.comments.requests.*;
import com.langfuse.client.resources.commons.types.*;

LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("pk-lf-...", "sk-lf-...")
    .build();

// Create a comment on a trace
// Note: Staged builder requires projectId() -> objectType() -> objectId() -> content()
CreateCommentRequest traceComment = CreateCommentRequest.builder()
    .projectId("your-project-id")  // Required first: project ID
    .objectType("trace")  // Required second: object type as String
    .objectId("trace-123")  // Required third: object ID
    .content("This trace shows excellent performance")  // Required fourth: content
    .build();

CreateCommentResponse response = client.comments().create(traceComment);

// Create a comment on an observation
CreateCommentRequest obsComment = CreateCommentRequest.builder()
    .projectId("your-project-id")  // Required first
    .objectType("observation")  // Required second: String, not enum
    .objectId("obs-456")  // Required third
    .content("Check model parameters here")  // Required fourth
    .build();

client.comments().create(obsComment);

// Get all comments for a trace
GetCommentsRequest request = GetCommentsRequest.builder()
    .objectType("trace")  // String, not enum
    .objectId("trace-123")
    .build();

GetCommentsResponse comments = client.comments().get(request);
for (Comment comment : comments.getData()) {
    System.out.println(comment.getContent());
}

// Get a specific comment
Comment comment = client.comments().getById("comment-789");

AnnotationQueuesClient

Client for managing annotation queues and queue items for human review.

/**
 * List all annotation queues
 *
 * @param request Optional pagination parameters
 * @param requestOptions Optional request configuration
 */
PaginatedAnnotationQueues listQueues();
PaginatedAnnotationQueues listQueues(GetAnnotationQueuesRequest request);
PaginatedAnnotationQueues listQueues(GetAnnotationQueuesRequest request, RequestOptions requestOptions);

/**
 * Get an annotation queue by ID
 *
 * @param queueId Queue ID
 * @param requestOptions Optional request configuration
 */
AnnotationQueue getQueue(String queueId);
AnnotationQueue getQueue(String queueId, RequestOptions requestOptions);

/**
 * List items in an annotation queue
 *
 * @param queueId Queue ID
 * @param request Optional filters (status, pagination)
 * @param requestOptions Optional request configuration
 */
PaginatedAnnotationQueueItems listQueueItems(String queueId);
PaginatedAnnotationQueueItems listQueueItems(String queueId, GetAnnotationQueueItemsRequest request);
PaginatedAnnotationQueueItems listQueueItems(String queueId, GetAnnotationQueueItemsRequest request, RequestOptions requestOptions);

/**
 * Get a specific queue item
 *
 * @param queueId Queue ID
 * @param itemId Item ID
 * @param requestOptions Optional request configuration
 */
AnnotationQueueItem getQueueItem(String queueId, String itemId);
AnnotationQueueItem getQueueItem(String queueId, String itemId, RequestOptions requestOptions);

/**
 * Add an item to an annotation queue
 *
 * @param queueId Queue ID
 * @param request Item definition
 * @param requestOptions Optional request configuration
 */
AnnotationQueueItem createQueueItem(String queueId, CreateAnnotationQueueItemRequest request);
AnnotationQueueItem createQueueItem(String queueId, CreateAnnotationQueueItemRequest request, RequestOptions requestOptions);

/**
 * Update an annotation queue item
 *
 * @param queueId Queue ID
 * @param itemId Item ID
 * @param request Update data
 * @param requestOptions Optional request configuration
 */
AnnotationQueueItem updateQueueItem(String queueId, String itemId);
AnnotationQueueItem updateQueueItem(String queueId, String itemId, UpdateAnnotationQueueItemRequest request);
AnnotationQueueItem updateQueueItem(String queueId, String itemId, UpdateAnnotationQueueItemRequest request, RequestOptions requestOptions);

/**
 * Remove an item from an annotation queue
 *
 * @param queueId Queue ID
 * @param itemId Item ID
 * @param requestOptions Optional request configuration
 */
DeleteAnnotationQueueItemResponse deleteQueueItem(String queueId, String itemId);
DeleteAnnotationQueueItemResponse deleteQueueItem(String queueId, String itemId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.resources.annotationqueues.types.*;
import com.langfuse.client.resources.annotationqueues.requests.*;

// List all queues
PaginatedAnnotationQueues queues = client.annotationQueues().listQueues();
for (AnnotationQueue queue : queues.getData()) {
    System.out.println("Queue: " + queue.getName());
}

// Get a specific queue
AnnotationQueue queue = client.annotationQueues().getQueue("queue-123");

// Add a trace to the queue for review
CreateAnnotationQueueItemRequest itemRequest = CreateAnnotationQueueItemRequest.builder()
    .objectId("trace-123")
    .objectType(AnnotationQueueObjectType.TRACE)
    .data(Map.of("priority", "high", "category", "quality-check"))
    .build();

AnnotationQueueItem item = client.annotationQueues()
    .createQueueItem("queue-123", itemRequest);

// List pending items in queue
GetAnnotationQueueItemsRequest listRequest = GetAnnotationQueueItemsRequest.builder()
    .status(AnnotationQueueStatus.PENDING)
    .build();

PaginatedAnnotationQueueItems items = client.annotationQueues()
    .listQueueItems("queue-123", listRequest);

// Get a specific item
AnnotationQueueItem retrieved = client.annotationQueues()
    .getQueueItem("queue-123", item.getId());

// Update item after review
UpdateAnnotationQueueItemRequest updateRequest = UpdateAnnotationQueueItemRequest.builder()
    .status(AnnotationQueueStatus.COMPLETED)
    .data(Map.of("reviewed_by", "user-456", "verdict", "approved"))
    .build();

AnnotationQueueItem updated = client.annotationQueues()
    .updateQueueItem("queue-123", item.getId(), updateRequest);

// Delete item
DeleteAnnotationQueueItemResponse deleteResp = client.annotationQueues()
    .deleteQueueItem("queue-123", item.getId());

Request Types (Comments)

CreateCommentRequest

/**
 * Request for creating a comment
 *
 * Staged Builder Pattern (required order):
 * 1. projectId(String) - Project ID
 * 2. objectType(String) - Object type: "trace", "observation", "session", "prompt"
 * 3. objectId(String) - ID of the object
 * 4. content(String) - Comment text
 * 5. authorUserId(String) - Optional author user ID
 * 6. build() - Build the request
 */
public final class CreateCommentRequest {
    String getProjectId();            // Project ID
    String getObjectType();           // Object type as String
    String getObjectId();             // ID of the object
    String getContent();              // Comment text
    Optional<String> getAuthorUserId(); // Optional author user ID

    static ProjectIdStage builder();  // Returns staged builder starting with projectId()
}

GetCommentsRequest

/**
 * Request parameters for listing comments
 */
public final class GetCommentsRequest {
    Optional<Integer> getPage();              // Page number (default: 1)
    Optional<Integer> getLimit();             // Items per page (default: 50)
    Optional<String> getObjectType();         // Filter by object type: "trace", "observation", "session", "prompt"
    Optional<String> getObjectId();           // Filter by object ID
    Optional<String> getAuthorUserId();       // Filter by author

    static Builder builder();
}

Request Types (Annotation Queues)

GetAnnotationQueuesRequest

/**
 * Request parameters for listing annotation queues
 */
public final class GetAnnotationQueuesRequest {
    Optional<Integer> getPage();   // Page number (default: 1)
    Optional<Integer> getLimit();  // Items per page (default: 50)

    static Builder builder();
}

GetAnnotationQueueItemsRequest

/**
 * Request parameters for listing queue items
 */
public final class GetAnnotationQueueItemsRequest {
    Optional<AnnotationQueueStatus> getStatus(); // Filter by status
    Optional<Integer> getPage();                 // Page number (default: 1)
    Optional<Integer> getLimit();                // Items per page (default: 50)

    static Builder builder();
}

CreateAnnotationQueueItemRequest

/**
 * Request for adding an item to a queue
 */
public final class CreateAnnotationQueueItemRequest {
    String getObjectId();                      // Object ID (trace, observation)
    AnnotationQueueObjectType getObjectType(); // TRACE, OBSERVATION
    Optional<Object> getData();                // Custom metadata

    static Builder builder();
}

UpdateAnnotationQueueItemRequest

/**
 * Request for updating a queue item
 */
public final class UpdateAnnotationQueueItemRequest {
    Optional<AnnotationQueueStatus> getStatus(); // PENDING, COMPLETED
    Optional<Object> getData();                  // Updated metadata

    static Builder builder();
}

Response Types

Comment

/**
 * Comment on an object
 *
 * Required imports:
 * import com.langfuse.client.resources.commons.types.Comment;
 * import com.langfuse.client.resources.commons.types.CommentObjectType;
 * import java.time.OffsetDateTime;
 */
public final class Comment {
    String getId();
    String getProjectId();
    OffsetDateTime getCreatedAt();        // Timestamp
    OffsetDateTime getUpdatedAt();        // Timestamp
    CommentObjectType getObjectType();    // Enum: TRACE, OBSERVATION, SESSION, PROMPT
    String getObjectId();
    String getContent();
    Optional<String> getAuthorUserId();

    static Builder builder();
}

CreateCommentResponse

/**
 * Response after creating a comment
 */
public final class CreateCommentResponse {
    String getId();  // The ID of the created comment

    static Builder builder();
}

GetCommentsResponse

/**
 * Paginated list of comments
 */
public final class GetCommentsResponse {
    List<Comment> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

AnnotationQueue

/**
 * Annotation queue definition
 *
 * Required imports:
 * import com.langfuse.client.resources.annotationqueues.types.AnnotationQueue;
 * import java.time.OffsetDateTime;
 */
public final class AnnotationQueue {
    String getId();
    String getName();
    Optional<String> getDescription();
    List<String> getScoreConfigIds();  // List of score config IDs
    OffsetDateTime getCreatedAt();     // Timestamp
    OffsetDateTime getUpdatedAt();     // Timestamp

    static Builder builder();
}

PaginatedAnnotationQueues

/**
 * Paginated list of annotation queues
 */
public final class PaginatedAnnotationQueues {
    List<AnnotationQueue> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

AnnotationQueueItem

/**
 * Item in an annotation queue
 */
public final class AnnotationQueueItem {
    String getId();
    String getQueueId();
    String getObjectId();
    AnnotationQueueObjectType getObjectType();
    AnnotationQueueStatus getStatus();
    Optional<Object> getData();
    Optional<String> getCompletedAt();  // ISO 8601 timestamp
    Optional<String> getAssignedTo();   // User ID
    String getCreatedAt();              // ISO 8601 timestamp
    String getUpdatedAt();              // ISO 8601 timestamp

    static Builder builder();
}

PaginatedAnnotationQueueItems

/**
 * Paginated list of annotation queue items
 */
public final class PaginatedAnnotationQueueItems {
    List<AnnotationQueueItem> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

DeleteAnnotationQueueItemResponse

/**
 * Response after deleting a queue item
 */
public final class DeleteAnnotationQueueItemResponse {
    boolean getSuccess();

    static Builder builder();
}

Enums

CommentObjectType

/**
 * Object types that can have comments
 */
public enum CommentObjectType {
    TRACE,
    OBSERVATION,
    SESSION,
    PROMPT
}

AnnotationQueueObjectType

/**
 * Object types for annotation queues
 */
public enum AnnotationQueueObjectType {
    TRACE,
    OBSERVATION
}

AnnotationQueueStatus

/**
 * Status of annotation queue items
 */
public enum AnnotationQueueStatus {
    PENDING,    // Pending review
    COMPLETED   // Review completed
}

Complete Annotation Workflow Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.comments.types.*;
import com.langfuse.client.resources.comments.requests.*;
import com.langfuse.client.resources.annotationqueues.types.*;
import com.langfuse.client.resources.annotationqueues.requests.*;
import com.langfuse.client.resources.commons.types.*;
import java.util.Map;

public class AnnotationWorkflowExample {
    public static void main(String[] args) {
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("pk-lf-...", "sk-lf-...")
            .build();

        String queueId = "queue-123";
        String traceId = "trace-456";

        // 1. Add trace to annotation queue
        CreateAnnotationQueueItemRequest itemRequest = CreateAnnotationQueueItemRequest.builder()
            .objectId(traceId)
            .objectType(AnnotationQueueObjectType.TRACE)
            .data(Map.of(
                "priority", "high",
                "reason", "user_reported",
                "issue_type", "quality"
            ))
            .build();

        AnnotationQueueItem item = client.annotationQueues()
            .createQueueItem(queueId, itemRequest);

        System.out.println("Added to queue: " + item.getId());

        // 2. Reviewer comments on the trace
        CreateCommentRequest commentRequest = CreateCommentRequest.builder()
            .projectId("your-project-id")
            .objectType("trace")  // String, not enum
            .objectId(traceId)
            .content("The response contains factual errors. Needs retraining.")
            .build();

        CreateCommentResponse comment = client.comments().create(commentRequest);

        // 3. Update queue item status
        UpdateAnnotationQueueItemRequest updateRequest = UpdateAnnotationQueueItemRequest.builder()
            .status(AnnotationQueueStatus.COMPLETED)
            .data(Map.of(
                "reviewed_by", "reviewer-123",
                "verdict", "needs_improvement",
                "comment_id", comment.getId()
            ))
            .build();

        AnnotationQueueItem updated = client.annotationQueues()
            .updateQueueItem(queueId, item.getId(), updateRequest);

        // 4. List all comments for the trace
        GetCommentsRequest getCommentsRequest = GetCommentsRequest.builder()
            .objectType("trace")  // String, not enum
            .objectId(traceId)
            .build();

        GetCommentsResponse comments = client.comments().get(getCommentsRequest);

        System.out.println("Comments on trace:");
        for (Comment c : comments.getData()) {
            System.out.println("  " + c.getAuthorUserId() + ": " + c.getContent());
        }

        // 5. Process pending items in queue
        GetAnnotationQueueItemsRequest pendingRequest = GetAnnotationQueueItemsRequest.builder()
            .status(AnnotationQueueStatus.PENDING)
            .limit(10)
            .build();

        PaginatedAnnotationQueueItems pending = client.annotationQueues()
            .listQueueItems(queueId, pendingRequest);

        System.out.println("\nPending items: " + pending.getData().size());
        for (AnnotationQueueItem pendingItem : pending.getData()) {
            System.out.println("  Item: " + pendingItem.getObjectId());
        }
    }
}

Best Practices

  1. Structured Data: Use the data field to store structured review metadata
  2. Comment Context: Include context in comments for future reference
  3. Status Tracking: Keep queue items updated with current status
  4. Assign Reviewers: Use assignedTo field to track reviewer assignment
  5. Priority Queuing: Use data field to implement priority systems
  6. Audit Trail: Comments provide an audit trail for reviews
  7. Bulk Processing: Process queue items in batches for efficiency

Related Documentation

  • Traces and Observations - Objects that can be commented/reviewed
  • Common Types - Shared type definitions
  • Pagination - Pagination utilities

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json