0
# Comments and Annotations
1

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

4
## Capabilities
5

6
### CommentsClient
7

8
Client for managing comments on various objects.
9

10
```java { .api }
11
/**
12
 * Create a comment
13
 * Can be attached to traces, observations, sessions, or prompts
14
 *
15
 * @param request Comment definition
16
 * @param requestOptions Optional request configuration
17
 */
18
CreateCommentResponse create(CreateCommentRequest request);
19
CreateCommentResponse create(CreateCommentRequest request, RequestOptions requestOptions);
20

21
/**
22
 * Get all comments with optional filters
23
 *
24
 * @param request Optional filters (objectType, objectId, author, pagination)
25
 * @param requestOptions Optional request configuration
26
 */
27
GetCommentsResponse get();
28
GetCommentsResponse get(GetCommentsRequest request);
29
GetCommentsResponse get(GetCommentsRequest request, RequestOptions requestOptions);
30

31
/**
32
 * Get a comment by ID
33
 *
34
 * @param commentId Comment ID
35
 * @param requestOptions Optional request configuration
36
 */
37
Comment getById(String commentId);
38
Comment getById(String commentId, RequestOptions requestOptions);
39
```
40

41
**Usage Examples:**
42

43
```java
44
import com.langfuse.client.LangfuseClient;
45
import com.langfuse.client.resources.comments.types.*;
46
import com.langfuse.client.resources.comments.requests.*;
47
import com.langfuse.client.resources.commons.types.*;
48

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

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

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

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

73
client.comments().create(obsComment);
74

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

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

86
// Get a specific comment
87
Comment comment = client.comments().getById("comment-789");
88
```
89

90
### AnnotationQueuesClient
91

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

94
```java { .api }
95
/**
96
 * List all annotation queues
97
 *
98
 * @param request Optional pagination parameters
99
 * @param requestOptions Optional request configuration
100
 */
101
PaginatedAnnotationQueues listQueues();
102
PaginatedAnnotationQueues listQueues(GetAnnotationQueuesRequest request);
103
PaginatedAnnotationQueues listQueues(GetAnnotationQueuesRequest request, RequestOptions requestOptions);
104

105
/**
106
 * Get an annotation queue by ID
107
 *
108
 * @param queueId Queue ID
109
 * @param requestOptions Optional request configuration
110
 */
111
AnnotationQueue getQueue(String queueId);
112
AnnotationQueue getQueue(String queueId, RequestOptions requestOptions);
113

114
/**
115
 * List items in an annotation queue
116
 *
117
 * @param queueId Queue ID
118
 * @param request Optional filters (status, pagination)
119
 * @param requestOptions Optional request configuration
120
 */
121
PaginatedAnnotationQueueItems listQueueItems(String queueId);
122
PaginatedAnnotationQueueItems listQueueItems(String queueId, GetAnnotationQueueItemsRequest request);
123
PaginatedAnnotationQueueItems listQueueItems(String queueId, GetAnnotationQueueItemsRequest request, RequestOptions requestOptions);
124

125
/**
126
 * Get a specific queue item
127
 *
128
 * @param queueId Queue ID
129
 * @param itemId Item ID
130
 * @param requestOptions Optional request configuration
131
 */
132
AnnotationQueueItem getQueueItem(String queueId, String itemId);
133
AnnotationQueueItem getQueueItem(String queueId, String itemId, RequestOptions requestOptions);
134

135
/**
136
 * Add an item to an annotation queue
137
 *
138
 * @param queueId Queue ID
139
 * @param request Item definition
140
 * @param requestOptions Optional request configuration
141
 */
142
AnnotationQueueItem createQueueItem(String queueId, CreateAnnotationQueueItemRequest request);
143
AnnotationQueueItem createQueueItem(String queueId, CreateAnnotationQueueItemRequest request, RequestOptions requestOptions);
144

145
/**
146
 * Update an annotation queue item
147
 *
148
 * @param queueId Queue ID
149
 * @param itemId Item ID
150
 * @param request Update data
151
 * @param requestOptions Optional request configuration
152
 */
153
AnnotationQueueItem updateQueueItem(String queueId, String itemId);
154
AnnotationQueueItem updateQueueItem(String queueId, String itemId, UpdateAnnotationQueueItemRequest request);
155
AnnotationQueueItem updateQueueItem(String queueId, String itemId, UpdateAnnotationQueueItemRequest request, RequestOptions requestOptions);
156

157
/**
158
 * Remove an item from an annotation queue
159
 *
160
 * @param queueId Queue ID
161
 * @param itemId Item ID
162
 * @param requestOptions Optional request configuration
163
 */
164
DeleteAnnotationQueueItemResponse deleteQueueItem(String queueId, String itemId);
165
DeleteAnnotationQueueItemResponse deleteQueueItem(String queueId, String itemId, RequestOptions requestOptions);
166
```
167

168
**Usage Examples:**
169

170
```java
171
import com.langfuse.client.resources.annotationqueues.types.*;
172
import com.langfuse.client.resources.annotationqueues.requests.*;
173

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

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

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

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

193
// List pending items in queue
194
GetAnnotationQueueItemsRequest listRequest = GetAnnotationQueueItemsRequest.builder()
195
    .status(AnnotationQueueStatus.PENDING)
196
    .build();
197

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

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

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

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

214
// Delete item
215
DeleteAnnotationQueueItemResponse deleteResp = client.annotationQueues()
216
    .deleteQueueItem("queue-123", item.getId());
217
```
218

219
## Request Types (Comments)
220

221
### CreateCommentRequest
222

223
```java { .api }
224
/**
225
 * Request for creating a comment
226
 *
227
 * Staged Builder Pattern (required order):
228
 * 1. projectId(String) - Project ID
229
 * 2. objectType(String) - Object type: "trace", "observation", "session", "prompt"
230
 * 3. objectId(String) - ID of the object
231
 * 4. content(String) - Comment text
232
 * 5. authorUserId(String) - Optional author user ID
233
 * 6. build() - Build the request
234
 */
235
public final class CreateCommentRequest {
236
    String getProjectId();            // Project ID
237
    String getObjectType();           // Object type as String
238
    String getObjectId();             // ID of the object
239
    String getContent();              // Comment text
240
    Optional<String> getAuthorUserId(); // Optional author user ID
241

242
    static ProjectIdStage builder();  // Returns staged builder starting with projectId()
243
}
244
```
245

246
### GetCommentsRequest
247

248
```java { .api }
249
/**
250
 * Request parameters for listing comments
251
 */
252
public final class GetCommentsRequest {
253
    Optional<Integer> getPage();              // Page number (default: 1)
254
    Optional<Integer> getLimit();             // Items per page (default: 50)
255
    Optional<String> getObjectType();         // Filter by object type: "trace", "observation", "session", "prompt"
256
    Optional<String> getObjectId();           // Filter by object ID
257
    Optional<String> getAuthorUserId();       // Filter by author
258

259
    static Builder builder();
260
}
261
```
262

263
## Request Types (Annotation Queues)
264

265
### GetAnnotationQueuesRequest
266

267
```java { .api }
268
/**
269
 * Request parameters for listing annotation queues
270
 */
271
public final class GetAnnotationQueuesRequest {
272
    Optional<Integer> getPage();   // Page number (default: 1)
273
    Optional<Integer> getLimit();  // Items per page (default: 50)
274

275
    static Builder builder();
276
}
277
```
278

279
### GetAnnotationQueueItemsRequest
280

281
```java { .api }
282
/**
283
 * Request parameters for listing queue items
284
 */
285
public final class GetAnnotationQueueItemsRequest {
286
    Optional<AnnotationQueueStatus> getStatus(); // Filter by status
287
    Optional<Integer> getPage();                 // Page number (default: 1)
288
    Optional<Integer> getLimit();                // Items per page (default: 50)
289

290
    static Builder builder();
291
}
292
```
293

294
### CreateAnnotationQueueItemRequest
295

296
```java { .api }
297
/**
298
 * Request for adding an item to a queue
299
 */
300
public final class CreateAnnotationQueueItemRequest {
301
    String getObjectId();                      // Object ID (trace, observation)
302
    AnnotationQueueObjectType getObjectType(); // TRACE, OBSERVATION
303
    Optional<Object> getData();                // Custom metadata
304

305
    static Builder builder();
306
}
307
```
308

309
### UpdateAnnotationQueueItemRequest
310

311
```java { .api }
312
/**
313
 * Request for updating a queue item
314
 */
315
public final class UpdateAnnotationQueueItemRequest {
316
    Optional<AnnotationQueueStatus> getStatus(); // PENDING, COMPLETED
317
    Optional<Object> getData();                  // Updated metadata
318

319
    static Builder builder();
320
}
321
```
322

323
## Response Types
324

325
### Comment
326

327
```java { .api }
328
/**
329
 * Comment on an object
330
 *
331
 * Required imports:
332
 * import com.langfuse.client.resources.commons.types.Comment;
333
 * import com.langfuse.client.resources.commons.types.CommentObjectType;
334
 * import java.time.OffsetDateTime;
335
 */
336
public final class Comment {
337
    String getId();
338
    String getProjectId();
339
    OffsetDateTime getCreatedAt();        // Timestamp
340
    OffsetDateTime getUpdatedAt();        // Timestamp
341
    CommentObjectType getObjectType();    // Enum: TRACE, OBSERVATION, SESSION, PROMPT
342
    String getObjectId();
343
    String getContent();
344
    Optional<String> getAuthorUserId();
345

346
    static Builder builder();
347
}
348
```
349

350
### CreateCommentResponse
351

352
```java { .api }
353
/**
354
 * Response after creating a comment
355
 */
356
public final class CreateCommentResponse {
357
    String getId();  // The ID of the created comment
358

359
    static Builder builder();
360
}
361
```
362

363
### GetCommentsResponse
364

365
```java { .api }
366
/**
367
 * Paginated list of comments
368
 */
369
public final class GetCommentsResponse {
370
    List<Comment> getData();
371
    MetaResponse getMeta();  // Pagination metadata
372

373
    static Builder builder();
374
}
375
```
376

377
### AnnotationQueue
378

379
```java { .api }
380
/**
381
 * Annotation queue definition
382
 *
383
 * Required imports:
384
 * import com.langfuse.client.resources.annotationqueues.types.AnnotationQueue;
385
 * import java.time.OffsetDateTime;
386
 */
387
public final class AnnotationQueue {
388
    String getId();
389
    String getName();
390
    Optional<String> getDescription();
391
    List<String> getScoreConfigIds();  // List of score config IDs
392
    OffsetDateTime getCreatedAt();     // Timestamp
393
    OffsetDateTime getUpdatedAt();     // Timestamp
394

395
    static Builder builder();
396
}
397
```
398

399
### PaginatedAnnotationQueues
400

401
```java { .api }
402
/**
403
 * Paginated list of annotation queues
404
 */
405
public final class PaginatedAnnotationQueues {
406
    List<AnnotationQueue> getData();
407
    MetaResponse getMeta();  // Pagination metadata
408

409
    static Builder builder();
410
}
411
```
412

413
### AnnotationQueueItem
414

415
```java { .api }
416
/**
417
 * Item in an annotation queue
418
 */
419
public final class AnnotationQueueItem {
420
    String getId();
421
    String getQueueId();
422
    String getObjectId();
423
    AnnotationQueueObjectType getObjectType();
424
    AnnotationQueueStatus getStatus();
425
    Optional<Object> getData();
426
    Optional<String> getCompletedAt();  // ISO 8601 timestamp
427
    Optional<String> getAssignedTo();   // User ID
428
    String getCreatedAt();              // ISO 8601 timestamp
429
    String getUpdatedAt();              // ISO 8601 timestamp
430

431
    static Builder builder();
432
}
433
```
434

435
### PaginatedAnnotationQueueItems
436

437
```java { .api }
438
/**
439
 * Paginated list of annotation queue items
440
 */
441
public final class PaginatedAnnotationQueueItems {
442
    List<AnnotationQueueItem> getData();
443
    MetaResponse getMeta();  // Pagination metadata
444

445
    static Builder builder();
446
}
447
```
448

449
### DeleteAnnotationQueueItemResponse
450

451
```java { .api }
452
/**
453
 * Response after deleting a queue item
454
 */
455
public final class DeleteAnnotationQueueItemResponse {
456
    boolean getSuccess();
457

458
    static Builder builder();
459
}
460
```
461

462
## Enums
463

464
### CommentObjectType
465

466
```java { .api }
467
/**
468
 * Object types that can have comments
469
 */
470
public enum CommentObjectType {
471
    TRACE,
472
    OBSERVATION,
473
    SESSION,
474
    PROMPT
475
}
476
```
477

478
### AnnotationQueueObjectType
479

480
```java { .api }
481
/**
482
 * Object types for annotation queues
483
 */
484
public enum AnnotationQueueObjectType {
485
    TRACE,
486
    OBSERVATION
487
}
488
```
489

490
### AnnotationQueueStatus
491

492
```java { .api }
493
/**
494
 * Status of annotation queue items
495
 */
496
public enum AnnotationQueueStatus {
497
    PENDING,    // Pending review
498
    COMPLETED   // Review completed
499
}
500
```
501

502
## Complete Annotation Workflow Example
503

504
```java
505
import com.langfuse.client.LangfuseClient;
506
import com.langfuse.client.resources.comments.types.*;
507
import com.langfuse.client.resources.comments.requests.*;
508
import com.langfuse.client.resources.annotationqueues.types.*;
509
import com.langfuse.client.resources.annotationqueues.requests.*;
510
import com.langfuse.client.resources.commons.types.*;
511
import java.util.Map;
512

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

520
        String queueId = "queue-123";
521
        String traceId = "trace-456";
522

523
        // 1. Add trace to annotation queue
524
        CreateAnnotationQueueItemRequest itemRequest = CreateAnnotationQueueItemRequest.builder()
525
            .objectId(traceId)
526
            .objectType(AnnotationQueueObjectType.TRACE)
527
            .data(Map.of(
528
                "priority", "high",
529
                "reason", "user_reported",
530
                "issue_type", "quality"
531
            ))
532
            .build();
533

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

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

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

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

549
        // 3. Update queue item status
550
        UpdateAnnotationQueueItemRequest updateRequest = UpdateAnnotationQueueItemRequest.builder()
551
            .status(AnnotationQueueStatus.COMPLETED)
552
            .data(Map.of(
553
                "reviewed_by", "reviewer-123",
554
                "verdict", "needs_improvement",
555
                "comment_id", comment.getId()
556
            ))
557
            .build();
558

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

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

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

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

575
        // 5. Process pending items in queue
576
        GetAnnotationQueueItemsRequest pendingRequest = GetAnnotationQueueItemsRequest.builder()
577
            .status(AnnotationQueueStatus.PENDING)
578
            .limit(10)
579
            .build();
580

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

584
        System.out.println("\nPending items: " + pending.getData().size());
585
        for (AnnotationQueueItem pendingItem : pending.getData()) {
586
            System.out.println("  Item: " + pendingItem.getObjectId());
587
        }
588
    }
589
}
590
```
591

592
## Best Practices
593

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

602
## Related Documentation
603

604
- [Traces and Observations](./traces-observations.md) - Objects that can be commented/reviewed
605
- [Common Types](./common-types.md) - Shared type definitions
606
- [Pagination](./pagination.md) - Pagination utilities
607