0
# Common Types
1

2
The Langfuse Java client provides a rich set of common types shared across multiple API areas. These types are located in the `com.langfuse.client.resources.commons.types` package.
3

4
```java
5
import java.time.OffsetDateTime;
6
```
7

8
## Core Domain Objects
9

10
### Trace Types
11

12
#### Trace
13

14
Basic trace object representing a complete workflow or request.
15

16
```java { .api }
17
/**
18
 * Basic trace object
19
 */
20
public final class Trace {
21
    String getId();
22
    OffsetDateTime getTimestamp();
23
    Optional<String> getName();
24
    Optional<String> getUserId();
25
    Optional<Object> getMetadata();
26
    Optional<String> getRelease();
27
    Optional<String> getVersion();
28
    Optional<String> getProjectId();
29
    Optional<Boolean> getPublic();
30
    Optional<Boolean> getBookmarked();
31
    Optional<List<String>> getTags();
32
    Optional<Object> getInput();
33
    Optional<Object> getOutput();
34
    Optional<String> getSessionId();
35

36
    static Builder builder();
37
}
38
```
39

40
#### TraceWithDetails
41

42
Trace with its observations.
43

44
```java { .api }
45
/**
46
 * Trace with observations
47
 */
48
public final class TraceWithDetails extends Trace {
49
    List<Observation> getObservations();
50

51
    static Builder builder();
52
}
53
```
54

55
#### TraceWithFullDetails
56

57
Trace with observations and scores (full detail).
58

59
```java { .api }
60
/**
61
 * Trace with observations and scores
62
 */
63
public final class TraceWithFullDetails extends Trace {
64
    List<Observation> getObservations();
65
    List<ScoreV1> getScores();
66

67
    static Builder builder();
68
}
69
```
70

71
### Observation Types
72

73
#### Observation
74

75
Core observation object (span, event, or generation).
76

77
```java { .api }
78
/**
79
 * Observation within a trace
80
 * Can be a span, event, or generation
81
 */
82
public final class Observation {
83
    String getId();
84
    String getTraceId();
85
    Optional<ObservationType> getType();        // SPAN, EVENT, GENERATION
86
    Optional<String> getParentObservationId();
87
    Optional<String> getName();
88
    Optional<Object> getMetadata();
89
    Optional<String> getModel();
90
    Optional<Object> getModelParameters();
91
    OffsetDateTime getStartTime();
92
    Optional<OffsetDateTime> getEndTime();
93
    Optional<OffsetDateTime> getCompletionStartTime();
94
    Optional<Object> getInput();
95
    Optional<Object> getOutput();
96
    Optional<Usage> getUsage();
97
    Optional<ObservationLevel> getLevel();      // DEBUG, DEFAULT, WARNING, ERROR
98
    Optional<String> getStatusMessage();
99
    Optional<String> getVersion();
100

101
    static Builder builder();
102
}
103
```
104

105
#### ObservationsView
106

107
Observation with additional computed fields (costs, latency).
108

109
```java { .api }
110
/**
111
 * Observation view with computed fields
112
 */
113
public final class ObservationsView extends Observation {
114
    Optional<String> getPromptId();
115
    Optional<String> getPromptName();
116
    Optional<Integer> getPromptVersion();
117
    Optional<String> getEnvironment();
118
    Optional<ModelPrice> getModelPrice();
119
    Optional<Double> getTotalCost();      // Computed cost
120
    Optional<Double> getLatency();        // Computed latency in seconds
121

122
    static Builder builder();
123
}
124
```
125

126
### Session Types
127

128
#### Session
129

130
Session object grouping related traces.
131

132
```java { .api }
133
/**
134
 * Session grouping related traces
135
 */
136
public final class Session {
137
    String getId();
138
    OffsetDateTime getCreatedAt();
139
    Optional<String> getBookmarked();
140
    Optional<Boolean> getPublic();
141
    List<String> getUserIds();
142
    int getTraceCount();
143
    Optional<Double> getTotalCost();
144
    Optional<String> getEnvironment();
145

146
    static Builder builder();
147
}
148
```
149

150
#### SessionWithTraces
151

152
Session with all its traces.
153

154
```java { .api }
155
/**
156
 * Session with all traces (not paginated)
157
 */
158
public final class SessionWithTraces extends Session {
159
    List<Trace> getTraces();
160

161
    static Builder builder();
162
}
163
```
164

165
## Score Types
166

167
### Score Variants
168

169
#### Score
170

171
Union type for different score variants.
172

173
```java { .api }
174
/**
175
 * Union type for scores
176
 * Discriminated by value type
177
 */
178
public final class Score {
179
    static Score base(BaseScore value);
180
    static Score boolean_(BooleanScore value);
181
    static Score categorical(CategoricalScore value);
182
    static Score numeric(NumericScore value);
183

184
    <T> T visit(Visitor<T> visitor);
185
}
186
```
187

188
#### BaseScore
189

190
Base score with generic value.
191

192
```java { .api }
193
/**
194
 * Base score type
195
 */
196
public final class BaseScore {
197
    String getId();
198
    OffsetDateTime getTimestamp();
199
    OffsetDateTime getCreatedAt();
200
    OffsetDateTime getUpdatedAt();
201
    String getProjectId();
202
    String getName();
203
    Object getValue();                  // Generic value
204
    ScoreSource getSource();            // API, EVAL, ANNOTATION
205
    Optional<String> getComment();
206
    Optional<String> getTraceId();
207
    Optional<String> getObservationId();
208
    Optional<ScoreDataType> getDataType(); // NUMERIC, CATEGORICAL, BOOLEAN
209
    Optional<String> getConfigId();
210
    Optional<String> getQueueId();
211

212
    static Builder builder();
213
}
214
```
215

216
#### BooleanScore
217

218
Boolean-valued score.
219

220
```java { .api }
221
/**
222
 * Boolean score
223
 */
224
public final class BooleanScore extends BaseScore {
225
    boolean getValue();
226

227
    static Builder builder();
228
}
229
```
230

231
#### CategoricalScore
232

233
Categorical score with string value.
234

235
```java { .api }
236
/**
237
 * Categorical score
238
 */
239
public final class CategoricalScore extends BaseScore {
240
    String getValue();
241

242
    static Builder builder();
243
}
244
```
245

246
#### NumericScore
247

248
Numeric score with double value.
249

250
```java { .api }
251
/**
252
 * Numeric score
253
 */
254
public final class NumericScore extends BaseScore {
255
    double getValue();
256

257
    static Builder builder();
258
}
259
```
260

261
### Score Configuration
262

263
#### ScoreConfig
264

265
Score configuration/template.
266

267
```java { .api }
268
/**
269
 * Score configuration template
270
 */
271
public final class ScoreConfig {
272
    String getId();
273
    String getName();
274
    ScoreDataType getDataType();
275
    Optional<Boolean> getIsArchived();
276
    Optional<List<ConfigCategory>> getCategories();
277
    Optional<Double> getMinValue();
278
    Optional<Double> getMaxValue();
279
    Optional<String> getDescription();
280
    OffsetDateTime getCreatedAt();
281
    OffsetDateTime getUpdatedAt();
282

283
    static Builder builder();
284
}
285
```
286

287
#### ConfigCategory
288

289
Category definition for categorical scores.
290

291
```java { .api }
292
/**
293
 * Category for categorical scores
294
 */
295
public final class ConfigCategory {
296
    String getValue();
297
    Optional<String> getLabel();
298

299
    static Builder builder();
300
}
301
```
302

303
## Dataset Types
304

305
#### Dataset
306

307
Dataset definition for evaluation.
308

309
```java { .api }
310
/**
311
 * Dataset for evaluation
312
 */
313
public final class Dataset {
314
    String getId();
315
    String getName();
316
    Optional<String> getDescription();
317
    Optional<Object> getMetadata();
318
    String getProjectId();
319
    OffsetDateTime getCreatedAt();
320
    OffsetDateTime getUpdatedAt();
321
    int getItems();                     // Number of items
322

323
    static Builder builder();
324
}
325
```
326

327
#### DatasetItem
328

329
Single item in a dataset (test case).
330

331
```java { .api }
332
/**
333
 * Dataset item (test case)
334
 */
335
public final class DatasetItem {
336
    String getId();
337
    DatasetStatus getStatus();          // ACTIVE, ARCHIVED
338
    Object getInput();
339
    Optional<Object> getExpectedOutput();
340
    Optional<Object> getMetadata();
341
    Optional<String> getSourceTraceId();
342
    Optional<String> getSourceObservationId();
343
    String getDatasetId();
344
    String getDatasetName();
345
    OffsetDateTime getCreatedAt();
346
    OffsetDateTime getUpdatedAt();
347

348
    static Builder builder();
349
}
350
```
351

352
#### DatasetRun
353

354
Dataset run (evaluation run).
355

356
```java { .api }
357
/**
358
 * Dataset run
359
 */
360
public final class DatasetRun {
361
    String getId();
362
    String getName();
363
    Optional<String> getDescription();
364
    Optional<Object> getMetadata();
365
    String getDatasetId();
366
    String getDatasetName();
367
    OffsetDateTime getCreatedAt();
368
    OffsetDateTime getUpdatedAt();
369

370
    static Builder builder();
371
}
372
```
373

374
#### DatasetRunItem
375

376
Dataset run item (links test case to result).
377

378
```java { .api }
379
/**
380
 * Dataset run item
381
 */
382
public final class DatasetRunItem {
383
    String getId();
384
    String getDatasetRunId();
385
    String getDatasetRunName();
386
    String getDatasetItemId();
387
    Optional<String> getTraceId();
388
    Optional<String> getObservationId();
389
    OffsetDateTime getCreatedAt();
390
    OffsetDateTime getUpdatedAt();
391

392
    static Builder builder();
393
}
394
```
395

396
#### DatasetRunWithItems
397

398
Dataset run with all its items.
399

400
```java { .api }
401
/**
402
 * Dataset run with items
403
 */
404
public final class DatasetRunWithItems extends DatasetRun {
405
    List<DatasetRunItem> getDatasetRunItems();
406

407
    static Builder builder();
408
}
409
```
410

411
## Model Types
412

413
#### Model
414

415
LLM model definition with pricing.
416

417
```java { .api }
418
/**
419
 * LLM model with pricing
420
 */
421
public final class Model {
422
    String getId();
423
    String getModelName();
424
    String getMatchPattern();           // Regex for matching
425
    Optional<OffsetDateTime> getStartDate();
426
    Optional<ModelPrice> getInputPrice();
427
    Optional<ModelPrice> getOutputPrice();
428
    Optional<ModelPrice> getTotalPrice();
429
    ModelUsageUnit getUnit();           // TOKENS, CHARACTERS, etc.
430
    Optional<String> getTokenizerId();
431
    Optional<Object> getTokenizerConfig();
432

433
    static Builder builder();
434
}
435
```
436

437
#### ModelPrice
438

439
Pricing information for a model.
440

441
```java { .api }
442
/**
443
 * Model pricing
444
 */
445
public final class ModelPrice {
446
    double getPrice();
447
    String getCurrency();               // e.g., "USD"
448

449
    static Builder builder();
450
}
451
```
452

453
#### Usage
454

455
Token usage information.
456

457
```java { .api }
458
/**
459
 * Token usage
460
 */
461
public final class Usage {
462
    Optional<Integer> getInput();
463
    Optional<Integer> getOutput();
464
    Optional<Integer> getTotal();
465
    Optional<ModelUsageUnit> getUnit();
466
    Optional<Double> getInputCost();
467
    Optional<Double> getOutputCost();
468
    Optional<Double> getTotalCost();
469

470
    static Builder builder();
471
}
472
```
473

474
## Comment Types
475

476
#### Comment
477

478
Comment on an object.
479

480
```java { .api }
481
/**
482
 * Comment on a trace, observation, session, or prompt
483
 */
484
public final class Comment {
485
    String getId();
486
    String getContent();
487
    CommentObjectType getObjectType();  // TRACE, OBSERVATION, SESSION, PROMPT
488
    String getObjectId();
489
    String getAuthorUserId();
490
    OffsetDateTime getCreatedAt();
491
    OffsetDateTime getUpdatedAt();
492

493
    static Builder builder();
494
}
495
```
496

497
## Utility Types
498

499
#### MapValue
500

501
Union type for map values.
502

503
```java { .api }
504
/**
505
 * Union type for map values
506
 * Supports various primitive and complex types
507
 */
508
public final class MapValue {
509
    static MapValue string(String value);
510
    static MapValue integer(int value);
511
    static MapValue _double(double value);
512
    static MapValue boolean_(boolean value);
513
    static MapValue list(List<MapValue> value);
514
    static MapValue map(Map<String, MapValue> value);
515

516
    <T> T visit(Visitor<T> visitor);
517
}
518
```
519

520
## Enums
521

522
### ObservationType
523

524
```java { .api }
525
/**
526
 * Type of observation
527
 */
528
public enum ObservationType {
529
    SPAN,       // Operation or sub-process
530
    EVENT,      // Point-in-time occurrence
531
    GENERATION  // LLM generation call
532
}
533
```
534

535
### ObservationLevel
536

537
```java { .api }
538
/**
539
 * Log level for observations
540
 */
541
public enum ObservationLevel {
542
    DEBUG,
543
    DEFAULT,
544
    WARNING,
545
    ERROR
546
}
547
```
548

549
### ScoreDataType
550

551
```java { .api }
552
/**
553
 * Data type for scores
554
 */
555
public enum ScoreDataType {
556
    NUMERIC,      // Double value
557
    CATEGORICAL,  // String value
558
    BOOLEAN       // Boolean value
559
}
560
```
561

562
### ScoreSource
563

564
```java { .api }
565
/**
566
 * Source of the score
567
 */
568
public enum ScoreSource {
569
    ANNOTATION,  // Created by annotation
570
    API,         // Created via API
571
    EVAL         // Created by evaluation
572
}
573
```
574

575
### DatasetStatus
576

577
```java { .api }
578
/**
579
 * Status of dataset item
580
 */
581
public enum DatasetStatus {
582
    ACTIVE,     // Active, included in evaluations
583
    ARCHIVED    // Archived, excluded
584
}
585
```
586

587
### ModelUsageUnit
588

589
```java { .api }
590
/**
591
 * Unit for usage measurement
592
 */
593
public enum ModelUsageUnit {
594
    CHARACTERS,
595
    TOKENS,
596
    REQUESTS,
597
    IMAGES,
598
    SECONDS
599
}
600
```
601

602
### CommentObjectType
603

604
```java { .api }
605
/**
606
 * Object types that can have comments
607
 */
608
public enum CommentObjectType {
609
    TRACE,
610
    OBSERVATION,
611
    SESSION,
612
    PROMPT
613
}
614
```
615

616
## Interfaces
617

618
### ITrace
619

620
Interface for trace properties.
621

622
```java { .api }
623
/**
624
 * Interface for trace properties
625
 */
626
public interface ITrace {
627
    String getId();
628
    OffsetDateTime getTimestamp();
629
    Optional<String> getName();
630
    Optional<String> getUserId();
631
    Optional<Object> getMetadata();
632
    // ... other trace properties
633
}
634
```
635

636
### IObservation
637

638
Interface for observation properties.
639

640
```java { .api }
641
/**
642
 * Interface for observation properties
643
 */
644
public interface IObservation {
645
    String getId();
646
    String getTraceId();
647
    Optional<ObservationType> getType();
648
    Optional<String> getName();
649
    OffsetDateTime getStartTime();
650
    Optional<OffsetDateTime> getEndTime();
651
    // ... other observation properties
652
}
653
```
654

655
### ISession
656

657
Interface for session properties.
658

659
```java { .api }
660
/**
661
 * Interface for session properties
662
 */
663
public interface ISession {
664
    String getId();
665
    OffsetDateTime getCreatedAt();
666
    List<String> getUserIds();
667
    // ... other session properties
668
}
669
```
670

671
### IBaseScore
672

673
Interface for base score properties.
674

675
```java { .api }
676
/**
677
 * Interface for score properties
678
 */
679
public interface IBaseScore {
680
    String getId();
681
    OffsetDateTime getTimestamp();
682
    OffsetDateTime getCreatedAt();
683
    OffsetDateTime getUpdatedAt();
684
    String getName();
685
    Object getValue();
686
    ScoreSource getSource();
687
    // ... other score properties
688
}
689
```
690

691
### IDatasetRun
692

693
Interface for dataset run properties.
694

695
```java { .api }
696
/**
697
 * Interface for dataset run properties
698
 */
699
public interface IDatasetRun {
700
    String getId();
701
    String getName();
702
    Optional<String> getDescription();
703
    Optional<Object> getMetadata();
704
    String getDatasetId();
705
    String getDatasetName();
706
    // ... other dataset run properties
707
}
708
```
709

710
## Type Usage Examples
711

712
### Working with Scores
713

714
```java
715
// Score is a union type - use visitor pattern
716
Score score = client.scoreV2().getById("score-123");
717

718
score.visit(new Score.Visitor<Void>() {
719
    @Override
720
    public Void visitNumeric(NumericScore numeric) {
721
        System.out.println("Numeric: " + numeric.getValue());
722
        return null;
723
    }
724

725
    @Override
726
    public Void visitCategorical(CategoricalScore categorical) {
727
        System.out.println("Categorical: " + categorical.getValue());
728
        return null;
729
    }
730

731
    @Override
732
    public Void visitBoolean(BooleanScore bool) {
733
        System.out.println("Boolean: " + bool.getValue());
734
        return null;
735
    }
736

737
    @Override
738
    public Void visitBase(BaseScore base) {
739
        System.out.println("Base: " + base.getValue());
740
        return null;
741
    }
742

743
    @Override
744
    public Void visitUnknown(String unknownType) {
745
        return null;
746
    }
747
});
748
```
749

750
### Working with Observations
751

752
```java
753
Observation observation = ...;
754

755
// Check observation type
756
if (observation.getType().isPresent()) {
757
    switch (observation.getType().get()) {
758
        case SPAN:
759
            System.out.println("This is a span");
760
            break;
761
        case EVENT:
762
            System.out.println("This is an event");
763
            break;
764
        case GENERATION:
765
            System.out.println("This is a generation");
766
            if (observation.getModel().isPresent()) {
767
                System.out.println("Model: " + observation.getModel().get());
768
            }
769
            break;
770
    }
771
}
772

773
// Check observation level
774
if (observation.getLevel().isPresent() &&
775
    observation.getLevel().get() == ObservationLevel.ERROR) {
776
    System.err.println("Error in observation: " +
777
        observation.getStatusMessage().orElse("no message"));
778
}
779
```
780

781
### Working with Usage Information
782

783
```java
784
ObservationsView view = client.observations().get("obs-123");
785

786
if (view.getUsage().isPresent()) {
787
    Usage usage = view.getUsage().get();
788

789
    System.out.println("Input tokens: " + usage.getInput().orElse(0));
790
    System.out.println("Output tokens: " + usage.getOutput().orElse(0));
791
    System.out.println("Total tokens: " + usage.getTotal().orElse(0));
792

793
    if (usage.getTotalCost().isPresent()) {
794
        System.out.println("Cost: $" + usage.getTotalCost().get());
795
    }
796
}
797
```
798

799
## Type Relationships
800

801
```
802
Trace
803
├── TraceWithDetails (adds observations)
804
└── TraceWithFullDetails (adds observations + scores)
805

806
Observation
807
└── ObservationsView (adds computed fields)
808

809
Session
810
└── SessionWithTraces (adds traces)
811

812
DatasetRun
813
└── DatasetRunWithItems (adds items)
814

815
Score (union)
816
├── BaseScore
817
├── BooleanScore
818
├── CategoricalScore
819
└── NumericScore
820
```
821

822
## Related Documentation
823

824
- [Traces and Observations](./traces-observations.md) - Using trace and observation types
825
- [Scores](./scores.md) - Using score types
826
- [Datasets](./datasets.md) - Using dataset types
827
- [Sessions](./sessions.md) - Using session types
828
- [Models](./models.md) - Using model types
829