0
# Scores
1

2
The Scores API provides management and retrieval of scores for traces and observations. Scores can be numeric, categorical, or boolean values used for evaluation, quality assessment, and analytics. The API supports both v1 (ScoreClient) and v2 (ScoreV2Client) endpoints, with v2 providing enhanced filtering capabilities.
3

4
## Capabilities
5

6
### ScoreClient
7

8
Client for creating and deleting scores.
9

10
```java { .api }
11
/**
12
 * Create a score for a trace or observation
13
 * Supports numeric, categorical, and boolean scores
14
 *
15
 * @param request Score definition
16
 * @param requestOptions Optional request configuration
17
 */
18
CreateScoreResponse create(CreateScoreRequest request);
19
CreateScoreResponse create(CreateScoreRequest request, RequestOptions requestOptions);
20

21
/**
22
 * Delete a score
23
 * Irreversible operation
24
 *
25
 * @param scoreId Score ID
26
 * @param requestOptions Optional request configuration
27
 */
28
void delete(String scoreId);
29
void delete(String scoreId, RequestOptions requestOptions);
30
```
31

32
**Usage Examples:**
33

34
```java
35
import com.langfuse.client.LangfuseClient;
36
import com.langfuse.client.resources.score.types.*;
37
import com.langfuse.client.resources.commons.types.*;
38

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

44
// Create a numeric score
45
CreateScoreRequest numericScore = CreateScoreRequest.builder()
46
    .name("quality")
47
    .value(CreateScoreValue.of(0.95))
48
    .traceId("trace-123")
49
    .dataType(ScoreDataType.NUMERIC)
50
    .comment("High quality response")
51
    .build();
52

53
CreateScoreResponse response = client.score().create(numericScore);
54

55
// Create a categorical score
56
CreateScoreRequest categoricalScore = CreateScoreRequest.builder()
57
    .name("sentiment")
58
    .value(CreateScoreValue.of("positive"))
59
    .traceId("trace-123")
60
    .dataType(ScoreDataType.CATEGORICAL)
61
    .build();
62

63
client.score().create(categoricalScore);
64

65
// Create a boolean score for an observation (use 0.0 or 1.0 for false/true)
66
CreateScoreRequest booleanScore = CreateScoreRequest.builder()
67
    .name("contains_pii")
68
    .value(CreateScoreValue.of(0.0))  // 0.0 = false, 1.0 = true
69
    .traceId("trace-123")
70
    .observationId("obs-456")
71
    .dataType(ScoreDataType.BOOLEAN)
72
    .build();
73

74
client.score().create(booleanScore);
75

76
// Delete a score
77
client.score().delete("score-123");
78
```
79

80
### ScoreV2Client
81

82
Enhanced client for retrieving scores with extensive filtering options.
83

84
```java { .api }
85
/**
86
 * Get a list of scores with extensive filtering
87
 * Supports filtering by user, name, date range, environment, source, value, etc.
88
 *
89
 * @param request Optional filters and pagination
90
 * @param requestOptions Optional request configuration
91
 */
92
GetScoresResponse get();
93
GetScoresResponse get(GetScoresRequest request);
94
GetScoresResponse get(GetScoresRequest request, RequestOptions requestOptions);
95

96
/**
97
 * Get a score by ID
98
 *
99
 * @param scoreId Score ID
100
 * @param requestOptions Optional request configuration
101
 */
102
Score getById(String scoreId);
103
Score getById(String scoreId, RequestOptions requestOptions);
104
```
105

106
**Usage Examples:**
107

108
```java
109
import com.langfuse.client.resources.scorev2.types.*;
110
import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;
111
import java.time.OffsetDateTime;
112

113
// Get all scores
114
GetScoresResponse scores = client.scoreV2().get();
115

116
// Filter by score IDs (comma-separated string)
117
GetScoresRequest request = GetScoresRequest.builder()
118
    .scoreIds("score-1,score-2")  // String, not List
119
    .build();
120

121
GetScoresResponse traceScores = client.scoreV2().get(request);
122

123
// Filter by name and date range
124
GetScoresRequest qualityRequest = GetScoresRequest.builder()
125
    .name("quality")
126
    .fromTimestamp(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
127
    .toTimestamp(OffsetDateTime.parse("2025-10-14T23:59:59Z"))
128
    .build();
129

130
GetScoresResponse qualityScores = client.scoreV2().get(qualityRequest);
131

132
// Filter by source and data type
133
GetScoresRequest apiScoresRequest = GetScoresRequest.builder()
134
    .source(ScoreSource.API)
135
    .dataType(ScoreDataType.NUMERIC)
136
    .limit(100)
137
    .build();
138

139
GetScoresResponse apiScores = client.scoreV2().get(apiScoresRequest);
140

141
// Get a specific score
142
Score score = client.scoreV2().getById("score-123");
143
```
144

145
### ScoreConfigsClient
146

147
Client for managing score configurations/templates.
148

149
```java { .api }
150
/**
151
 * Create a score configuration
152
 * Defines a reusable score template
153
 *
154
 * @param request Config definition
155
 * @param requestOptions Optional request configuration
156
 */
157
ScoreConfig create(CreateScoreConfigRequest request);
158
ScoreConfig create(CreateScoreConfigRequest request, RequestOptions requestOptions);
159

160
/**
161
 * Get all score configs
162
 *
163
 * @param request Optional pagination parameters
164
 * @param requestOptions Optional request configuration
165
 */
166
ScoreConfigs get();
167
ScoreConfigs get(GetScoreConfigsRequest request);
168
ScoreConfigs get(GetScoreConfigsRequest request, RequestOptions requestOptions);
169

170
/**
171
 * Get a score config by ID
172
 *
173
 * @param configId Config ID
174
 * @param requestOptions Optional request configuration
175
 */
176
ScoreConfig getById(String configId);
177
ScoreConfig getById(String configId, RequestOptions requestOptions);
178
```
179

180
**Usage Examples:**
181

182
```java
183
import com.langfuse.client.resources.scoreconfigs.types.*;
184

185
// Create a numeric score config
186
CreateScoreConfigRequest numericConfig = CreateScoreConfigRequest.builder()
187
    .name("quality")
188
    .dataType(ScoreDataType.NUMERIC)
189
    .minValue(0.0)
190
    .maxValue(1.0)
191
    .description("Quality score from 0 to 1")
192
    .build();
193

194
ScoreConfig config = client.scoreConfigs().create(numericConfig);
195

196
// Create a categorical score config
197
CreateScoreConfigRequest categoricalConfig = CreateScoreConfigRequest.builder()
198
    .name("sentiment")
199
    .dataType(ScoreDataType.CATEGORICAL)
200
    .categories(List.of(
201
        ConfigCategory.builder()
202
            .value("positive")
203
            .label("Positive")
204
            .build(),
205
        ConfigCategory.builder()
206
            .value("neutral")
207
            .label("Neutral")
208
            .build(),
209
        ConfigCategory.builder()
210
            .value("negative")
211
            .label("Negative")
212
            .build()
213
    ))
214
    .description("Sentiment classification")
215
    .build();
216

217
client.scoreConfigs().create(categoricalConfig);
218

219
// List all configs
220
ScoreConfigs configs = client.scoreConfigs().get();
221
for (ScoreConfig cfg : configs.getData()) {
222
    System.out.println(cfg.getName() + " (" + cfg.getDataType() + ")");
223
}
224

225
// Get a specific config
226
ScoreConfig retrieved = client.scoreConfigs().getById(config.getId());
227
```
228

229
## Request Types
230

231
### CreateScoreRequest
232

233
```java { .api }
234
/**
235
 * Request for creating a score
236
 */
237
public final class CreateScoreRequest {
238
    String getName();                           // Score name
239
    CreateScoreValue getValue();                // Union: String, Integer, or Double
240
    String getTraceId();                        // Trace ID
241
    Optional<String> getObservationId();        // Optional observation ID
242
    Optional<String> getComment();              // Optional comment/explanation
243
    Optional<ScoreDataType> getDataType();      // NUMERIC, CATEGORICAL, or BOOLEAN
244
    Optional<String> getConfigId();             // Reference to score config
245

246
    static Builder builder();
247
}
248
```
249

250
### CreateScoreValue
251

252
Union type for score values, supporting numeric and string data types.
253

254
**Import:** `import com.langfuse.client.resources.commons.types.CreateScoreValue;`
255

256
```java { .api }
257
/**
258
 * Union type for score values (double or String)
259
 *
260
 * For boolean scores, use 0.0 (false) or 1.0 (true)
261
 */
262
public final class CreateScoreValue {
263
    static CreateScoreValue of(double value);   // For numeric and boolean scores
264
    static CreateScoreValue of(String value);   // For categorical scores
265

266
    Object get();  // Get the underlying value
267
    <T> T visit(Visitor<T> visitor);  // Visitor pattern for type-safe access
268
}
269
```
270

271
### GetScoresRequest
272

273
**Import:** `import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;`
274

275
```java { .api }
276
/**
277
 * Request parameters for retrieving scores (v2 API)
278
 * Located in requests package (not types)
279
 */
280
public final class GetScoresRequest {
281
    Optional<Integer> getPage();                // Page number (default: 1)
282
    Optional<Integer> getLimit();               // Items per page (default: 50)
283
    Optional<String> getUserId();               // Filter by user ID
284
    Optional<String> getName();                 // Filter by score name
285
    Optional<OffsetDateTime> getFromTimestamp(); // Filter by start date
286
    Optional<OffsetDateTime> getToTimestamp();  // Filter by end date
287
    Optional<String> getEnvironment();          // Filter by environment
288
    Optional<ScoreSource> getSource();          // Filter by source
289
    Optional<String> getOperator();             // Filter operator for value (>=, <=, etc.)
290
    Optional<Double> getValue();                // Filter by value
291
    Optional<String> getScoreIds();             // Comma-separated score IDs
292
    Optional<String> getConfigId();             // Filter by config ID
293
    Optional<String> getQueueId();              // Filter by queue ID
294
    Optional<ScoreDataType> getDataType();      // Filter by data type
295
    Optional<String> getTraceTags();            // Comma-separated trace tags
296

297
    static Builder builder();
298
}
299
```
300

301
### CreateScoreConfigRequest
302

303
```java { .api }
304
/**
305
 * Request for creating a score configuration
306
 */
307
public final class CreateScoreConfigRequest {
308
    String getName();                          // Config name
309
    ScoreDataType getDataType();               // NUMERIC, CATEGORICAL, or BOOLEAN
310
    Optional<Boolean> getIsArchived();         // Archive status
311
    Optional<List<ConfigCategory>> getCategories(); // For categorical scores
312
    Optional<Double> getMinValue();            // For numeric scores
313
    Optional<Double> getMaxValue();            // For numeric scores
314
    Optional<String> getDescription();         // Description
315

316
    static Builder builder();
317
}
318
```
319

320
### GetScoreConfigsRequest
321

322
```java { .api }
323
/**
324
 * Request parameters for listing score configs
325
 */
326
public final class GetScoreConfigsRequest {
327
    Optional<Integer> getPage();   // Page number (default: 1)
328
    Optional<Integer> getLimit();  // Items per page (default: 50)
329

330
    static Builder builder();
331
}
332
```
333

334
## Response Types
335

336
### CreateScoreResponse
337

338
```java { .api }
339
/**
340
 * Response after creating a score
341
 */
342
public final class CreateScoreResponse {
343
    String getId();  // Score ID
344

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

349
### Score
350

351
Union type for different score variants (see [Common Types](./common-types.md)).
352

353
### GetScoresResponse
354

355
```java { .api }
356
/**
357
 * Paginated scores with trace data
358
 */
359
public final class GetScoresResponse {
360
    List<GetScoresResponseData> getData();
361
    MetaResponse getMeta();  // Pagination metadata
362

363
    static Builder builder();
364
}
365
```
366

367
### GetScoresResponseData
368

369
Union type for score data variants.
370

371
```java { .api }
372
/**
373
 * Union type for score response data
374
 * Discriminated by data type
375
 */
376
public final class GetScoresResponseData {
377
    static GetScoresResponseData numeric(GetScoresResponseDataNumeric value);
378
    static GetScoresResponseData categorical(GetScoresResponseDataCategorical value);
379
    static GetScoresResponseData boolean_(GetScoresResponseDataBoolean value);
380

381
    <T> T visit(Visitor<T> visitor);
382
}
383
```
384

385
### GetScoresResponseDataNumeric
386

387
```java { .api }
388
/**
389
 * Numeric score response data
390
 */
391
public final class GetScoresResponseDataNumeric {
392
    String getId();
393
    String getTimestamp();                      // ISO 8601 timestamp
394
    String getName();
395
    ScoreSource getSource();                    // API, EVAL, ANNOTATION
396
    double getValue();                          // Numeric value
397
    Optional<String> getComment();
398
    Optional<String> getConfigId();
399
    Optional<String> getQueueId();
400
    GetScoresResponseTraceData getTraceData();  // Associated trace info
401

402
    static Builder builder();
403
}
404
```
405

406
### GetScoresResponseDataCategorical
407

408
```java { .api }
409
/**
410
 * Categorical score response data
411
 */
412
public final class GetScoresResponseDataCategorical {
413
    String getId();
414
    String getTimestamp();
415
    String getName();
416
    ScoreSource getSource();
417
    String getValue();                          // Categorical value (string)
418
    Optional<String> getComment();
419
    Optional<String> getConfigId();
420
    Optional<String> getQueueId();
421
    GetScoresResponseTraceData getTraceData();
422

423
    static Builder builder();
424
}
425
```
426

427
### GetScoresResponseDataBoolean
428

429
```java { .api }
430
/**
431
 * Boolean score response data
432
 */
433
public final class GetScoresResponseDataBoolean {
434
    String getId();
435
    String getTimestamp();
436
    String getName();
437
    ScoreSource getSource();
438
    boolean getValue();                         // Boolean value
439
    Optional<String> getComment();
440
    Optional<String> getConfigId();
441
    Optional<String> getQueueId();
442
    GetScoresResponseTraceData getTraceData();
443

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

448
### GetScoresResponseTraceData
449

450
```java { .api }
451
/**
452
 * Associated trace information for a score
453
 */
454
public final class GetScoresResponseTraceData {
455
    String getTraceId();
456
    Optional<String> getTraceName();
457
    Optional<String> getUserId();
458
    Optional<Object> getMetadata();
459
    Optional<String> getRelease();
460
    Optional<String> getVersion();
461
    Optional<String> getSessionId();
462
    Optional<List<String>> getTags();
463
    Optional<String> getEnvironment();
464

465
    static Builder builder();
466
}
467
```
468

469
### ScoreConfig
470

471
```java { .api }
472
/**
473
 * Score configuration/template
474
 */
475
public final class ScoreConfig {
476
    String getId();
477
    String getName();
478
    ScoreDataType getDataType();                // NUMERIC, CATEGORICAL, BOOLEAN
479
    Optional<Boolean> getIsArchived();
480
    Optional<List<ConfigCategory>> getCategories();
481
    Optional<Double> getMinValue();
482
    Optional<Double> getMaxValue();
483
    Optional<String> getDescription();
484
    String getCreatedAt();  // ISO 8601 timestamp
485
    String getUpdatedAt();  // ISO 8601 timestamp
486

487
    static Builder builder();
488
}
489
```
490

491
### ConfigCategory
492

493
```java { .api }
494
/**
495
 * Category definition for categorical scores
496
 */
497
public final class ConfigCategory {
498
    String getValue();         // Category value
499
    Optional<String> getLabel(); // Display label
500

501
    static Builder builder();
502
}
503
```
504

505
### ScoreConfigs
506

507
```java { .api }
508
/**
509
 * List of score configs
510
 */
511
public final class ScoreConfigs {
512
    List<ScoreConfig> getData();
513

514
    static Builder builder();
515
}
516
```
517

518
## Enums
519

520
### ScoreDataType
521

522
```java { .api }
523
/**
524
 * Data type for scores
525
 */
526
public enum ScoreDataType {
527
    NUMERIC,      // Double value
528
    CATEGORICAL,  // String value from predefined categories
529
    BOOLEAN       // Boolean value
530
}
531
```
532

533
### ScoreSource
534

535
```java { .api }
536
/**
537
 * Source of the score
538
 */
539
public enum ScoreSource {
540
    API,         // Created via API
541
    EVAL,        // Created by evaluation
542
    ANNOTATION   // Created by human annotation
543
}
544
```
545

546
## Complete Scoring Example
547

548
```java
549
import com.langfuse.client.LangfuseClient;
550
import com.langfuse.client.resources.score.types.*;
551
import com.langfuse.client.resources.scorev2.types.*;
552
import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;
553
import com.langfuse.client.resources.scoreconfigs.types.*;
554
import com.langfuse.client.resources.commons.types.*;
555
import java.time.OffsetDateTime;
556
import java.util.List;
557

558
public class ScoringExample {
559
    public static void main(String[] args) {
560
        LangfuseClient client = LangfuseClient.builder()
561
            .url("https://cloud.langfuse.com")
562
            .credentials("pk-lf-...", "sk-lf-...")
563
            .build();
564

565
        // 1. Create score configurations
566
        CreateScoreConfigRequest qualityConfig = CreateScoreConfigRequest.builder()
567
            .name("quality")
568
            .dataType(ScoreDataType.NUMERIC)
569
            .minValue(0.0)
570
            .maxValue(1.0)
571
            .description("Response quality score (0-1)")
572
            .build();
573

574
        ScoreConfig qualityCfg = client.scoreConfigs().create(qualityConfig);
575

576
        CreateScoreConfigRequest sentimentConfig = CreateScoreConfigRequest.builder()
577
            .name("sentiment")
578
            .dataType(ScoreDataType.CATEGORICAL)
579
            .categories(List.of(
580
                ConfigCategory.builder().value("positive").label("Positive").build(),
581
                ConfigCategory.builder().value("neutral").label("Neutral").build(),
582
                ConfigCategory.builder().value("negative").label("Negative").build()
583
            ))
584
            .description("Sentiment classification")
585
            .build();
586

587
        ScoreConfig sentimentCfg = client.scoreConfigs().create(sentimentConfig);
588

589
        // 2. Create scores for a trace
590
        String traceId = "trace-123";
591

592
        // Quality score (numeric)
593
        CreateScoreRequest qualityScore = CreateScoreRequest.builder()
594
            .name("quality")
595
            .value(CreateScoreValue.of(0.87))
596
            .traceId(traceId)
597
            .dataType(ScoreDataType.NUMERIC)
598
            .configId(qualityCfg.getId())
599
            .comment("Good response, minor issues")
600
            .build();
601

602
        CreateScoreResponse qResp = client.score().create(qualityScore);
603
        System.out.println("Created quality score: " + qResp.getId());
604

605
        // Sentiment score (categorical)
606
        CreateScoreRequest sentimentScore = CreateScoreRequest.builder()
607
            .name("sentiment")
608
            .value(CreateScoreValue.of("positive"))
609
            .traceId(traceId)
610
            .dataType(ScoreDataType.CATEGORICAL)
611
            .configId(sentimentCfg.getId())
612
            .build();
613

614
        CreateScoreResponse sResp = client.score().create(sentimentScore);
615

616
        // PII detection (boolean - use 0.0 or 1.0)
617
        CreateScoreRequest piiScore = CreateScoreRequest.builder()
618
            .name("contains_pii")
619
            .value(CreateScoreValue.of(0.0))  // 0.0 = false, 1.0 = true
620
            .traceId(traceId)
621
            .dataType(ScoreDataType.BOOLEAN)
622
            .comment("No PII detected")
623
            .build();
624

625
        client.score().create(piiScore);
626

627
        // 3. Retrieve scores
628
        // Note: scoreIds expects comma-separated string, not List
629
        GetScoresRequest getRequest = GetScoresRequest.builder()
630
            .scoreIds(traceId)  // String, not List
631
            .build();
632

633
        GetScoresResponse scores = client.scoreV2().get(getRequest);
634

635
        System.out.println("\nScores for trace:");
636
        for (GetScoresResponseData scoreData : scores.getData()) {
637
            scoreData.visit(new GetScoresResponseData.Visitor<Void>() {
638
                @Override
639
                public Void visitNumeric(GetScoresResponseDataNumeric numeric) {
640
                    System.out.println("  " + numeric.getName() + ": " + numeric.getValue());
641
                    return null;
642
                }
643

644
                @Override
645
                public Void visitCategorical(GetScoresResponseDataCategorical categorical) {
646
                    System.out.println("  " + categorical.getName() + ": " + categorical.getValue());
647
                    return null;
648
                }
649

650
                @Override
651
                public Void visitBoolean(GetScoresResponseDataBoolean bool) {
652
                    System.out.println("  " + bool.getName() + ": " + bool.getValue());
653
                    return null;
654
                }
655

656
                @Override
657
                public Void visitUnknown(String unknownType) {
658
                    return null;
659
                }
660
            });
661
        }
662

663
        // 4. Query scores by criteria
664
        GetScoresRequest highQualityRequest = GetScoresRequest.builder()
665
            .name("quality")
666
            .operator(">=")
667
            .value(0.8)
668
            .fromTimestamp(OffsetDateTime.parse("2025-10-01T00:00:00Z"))
669
            .build();
670

671
        GetScoresResponse highQualityScores = client.scoreV2().get(highQualityRequest);
672
        System.out.println("\nHigh quality scores: " + highQualityScores.getData().size());
673

674
        // 5. Query by source
675
        GetScoresRequest apiScoresRequest = GetScoresRequest.builder()
676
            .source(ScoreSource.API)
677
            .dataType(ScoreDataType.NUMERIC)
678
            .limit(50)
679
            .build();
680

681
        GetScoresResponse apiScores = client.scoreV2().get(apiScoresRequest);
682

683
        // 6. List all score configs
684
        ScoreConfigs configs = client.scoreConfigs().get();
685
        System.out.println("\nScore configurations:");
686
        for (ScoreConfig config : configs.getData()) {
687
            System.out.println("  " + config.getName() +
688
                             " (" + config.getDataType() + ")" +
689
                             " - " + config.getDescription().orElse(""));
690
        }
691
    }
692
}
693
```
694

695
## Best Practices
696

697
1. **Use Score Configs**: Define reusable score configurations for consistency
698
2. **Standardize Names**: Use consistent score names across your application
699
3. **Add Comments**: Include comments for human-reviewable scores
700
4. **Link to Configs**: Reference configId to enforce validation and constraints
701
5. **Track Sources**: Use source field to distinguish between API, eval, and annotation scores
702
6. **Query Efficiently**: Use specific filters (name, date range, source) to narrow results
703
7. **Normalize Numeric Scores**: Use 0-1 range for numeric scores when possible
704
8. **Version Configs**: Create new configs instead of modifying existing ones
705
9. **Archive Old Configs**: Set isArchived=true instead of deleting
706

707
## Related Documentation
708

709
- [Traces and Observations](./traces-observations.md) - Scoring targets
710
- [Ingestion API](./ingestion.md) - Creating scores via ingestion
711
- [Common Types](./common-types.md) - Score type definitions
712
- [Pagination](./pagination.md) - Pagination utilities
713