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

scores.mddocs/

Scores

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.

Capabilities

ScoreClient

Client for creating and deleting scores.

/**
 * Create a score for a trace or observation
 * Supports numeric, categorical, and boolean scores
 *
 * @param request Score definition
 * @param requestOptions Optional request configuration
 */
CreateScoreResponse create(CreateScoreRequest request);
CreateScoreResponse create(CreateScoreRequest request, RequestOptions requestOptions);

/**
 * Delete a score
 * Irreversible operation
 *
 * @param scoreId Score ID
 * @param requestOptions Optional request configuration
 */
void delete(String scoreId);
void delete(String scoreId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.score.types.*;
import com.langfuse.client.resources.commons.types.*;

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

// Create a numeric score
CreateScoreRequest numericScore = CreateScoreRequest.builder()
    .name("quality")
    .value(CreateScoreValue.of(0.95))
    .traceId("trace-123")
    .dataType(ScoreDataType.NUMERIC)
    .comment("High quality response")
    .build();

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

// Create a categorical score
CreateScoreRequest categoricalScore = CreateScoreRequest.builder()
    .name("sentiment")
    .value(CreateScoreValue.of("positive"))
    .traceId("trace-123")
    .dataType(ScoreDataType.CATEGORICAL)
    .build();

client.score().create(categoricalScore);

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

client.score().create(booleanScore);

// Delete a score
client.score().delete("score-123");

ScoreV2Client

Enhanced client for retrieving scores with extensive filtering options.

/**
 * Get a list of scores with extensive filtering
 * Supports filtering by user, name, date range, environment, source, value, etc.
 *
 * @param request Optional filters and pagination
 * @param requestOptions Optional request configuration
 */
GetScoresResponse get();
GetScoresResponse get(GetScoresRequest request);
GetScoresResponse get(GetScoresRequest request, RequestOptions requestOptions);

/**
 * Get a score by ID
 *
 * @param scoreId Score ID
 * @param requestOptions Optional request configuration
 */
Score getById(String scoreId);
Score getById(String scoreId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.resources.scorev2.types.*;
import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;
import java.time.OffsetDateTime;

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

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

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

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

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

// Filter by source and data type
GetScoresRequest apiScoresRequest = GetScoresRequest.builder()
    .source(ScoreSource.API)
    .dataType(ScoreDataType.NUMERIC)
    .limit(100)
    .build();

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

// Get a specific score
Score score = client.scoreV2().getById("score-123");

ScoreConfigsClient

Client for managing score configurations/templates.

/**
 * Create a score configuration
 * Defines a reusable score template
 *
 * @param request Config definition
 * @param requestOptions Optional request configuration
 */
ScoreConfig create(CreateScoreConfigRequest request);
ScoreConfig create(CreateScoreConfigRequest request, RequestOptions requestOptions);

/**
 * Get all score configs
 *
 * @param request Optional pagination parameters
 * @param requestOptions Optional request configuration
 */
ScoreConfigs get();
ScoreConfigs get(GetScoreConfigsRequest request);
ScoreConfigs get(GetScoreConfigsRequest request, RequestOptions requestOptions);

/**
 * Get a score config by ID
 *
 * @param configId Config ID
 * @param requestOptions Optional request configuration
 */
ScoreConfig getById(String configId);
ScoreConfig getById(String configId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.resources.scoreconfigs.types.*;

// Create a numeric score config
CreateScoreConfigRequest numericConfig = CreateScoreConfigRequest.builder()
    .name("quality")
    .dataType(ScoreDataType.NUMERIC)
    .minValue(0.0)
    .maxValue(1.0)
    .description("Quality score from 0 to 1")
    .build();

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

// Create a categorical score config
CreateScoreConfigRequest categoricalConfig = CreateScoreConfigRequest.builder()
    .name("sentiment")
    .dataType(ScoreDataType.CATEGORICAL)
    .categories(List.of(
        ConfigCategory.builder()
            .value("positive")
            .label("Positive")
            .build(),
        ConfigCategory.builder()
            .value("neutral")
            .label("Neutral")
            .build(),
        ConfigCategory.builder()
            .value("negative")
            .label("Negative")
            .build()
    ))
    .description("Sentiment classification")
    .build();

client.scoreConfigs().create(categoricalConfig);

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

// Get a specific config
ScoreConfig retrieved = client.scoreConfigs().getById(config.getId());

Request Types

CreateScoreRequest

/**
 * Request for creating a score
 */
public final class CreateScoreRequest {
    String getName();                           // Score name
    CreateScoreValue getValue();                // Union: String, Integer, or Double
    String getTraceId();                        // Trace ID
    Optional<String> getObservationId();        // Optional observation ID
    Optional<String> getComment();              // Optional comment/explanation
    Optional<ScoreDataType> getDataType();      // NUMERIC, CATEGORICAL, or BOOLEAN
    Optional<String> getConfigId();             // Reference to score config

    static Builder builder();
}

CreateScoreValue

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

Import: import com.langfuse.client.resources.commons.types.CreateScoreValue;

/**
 * Union type for score values (double or String)
 *
 * For boolean scores, use 0.0 (false) or 1.0 (true)
 */
public final class CreateScoreValue {
    static CreateScoreValue of(double value);   // For numeric and boolean scores
    static CreateScoreValue of(String value);   // For categorical scores

    Object get();  // Get the underlying value
    <T> T visit(Visitor<T> visitor);  // Visitor pattern for type-safe access
}

GetScoresRequest

Import: import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;

/**
 * Request parameters for retrieving scores (v2 API)
 * Located in requests package (not types)
 */
public final class GetScoresRequest {
    Optional<Integer> getPage();                // Page number (default: 1)
    Optional<Integer> getLimit();               // Items per page (default: 50)
    Optional<String> getUserId();               // Filter by user ID
    Optional<String> getName();                 // Filter by score name
    Optional<OffsetDateTime> getFromTimestamp(); // Filter by start date
    Optional<OffsetDateTime> getToTimestamp();  // Filter by end date
    Optional<String> getEnvironment();          // Filter by environment
    Optional<ScoreSource> getSource();          // Filter by source
    Optional<String> getOperator();             // Filter operator for value (>=, <=, etc.)
    Optional<Double> getValue();                // Filter by value
    Optional<String> getScoreIds();             // Comma-separated score IDs
    Optional<String> getConfigId();             // Filter by config ID
    Optional<String> getQueueId();              // Filter by queue ID
    Optional<ScoreDataType> getDataType();      // Filter by data type
    Optional<String> getTraceTags();            // Comma-separated trace tags

    static Builder builder();
}

CreateScoreConfigRequest

/**
 * Request for creating a score configuration
 */
public final class CreateScoreConfigRequest {
    String getName();                          // Config name
    ScoreDataType getDataType();               // NUMERIC, CATEGORICAL, or BOOLEAN
    Optional<Boolean> getIsArchived();         // Archive status
    Optional<List<ConfigCategory>> getCategories(); // For categorical scores
    Optional<Double> getMinValue();            // For numeric scores
    Optional<Double> getMaxValue();            // For numeric scores
    Optional<String> getDescription();         // Description

    static Builder builder();
}

GetScoreConfigsRequest

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

    static Builder builder();
}

Response Types

CreateScoreResponse

/**
 * Response after creating a score
 */
public final class CreateScoreResponse {
    String getId();  // Score ID

    static Builder builder();
}

Score

Union type for different score variants (see Common Types).

GetScoresResponse

/**
 * Paginated scores with trace data
 */
public final class GetScoresResponse {
    List<GetScoresResponseData> getData();
    MetaResponse getMeta();  // Pagination metadata

    static Builder builder();
}

GetScoresResponseData

Union type for score data variants.

/**
 * Union type for score response data
 * Discriminated by data type
 */
public final class GetScoresResponseData {
    static GetScoresResponseData numeric(GetScoresResponseDataNumeric value);
    static GetScoresResponseData categorical(GetScoresResponseDataCategorical value);
    static GetScoresResponseData boolean_(GetScoresResponseDataBoolean value);

    <T> T visit(Visitor<T> visitor);
}

GetScoresResponseDataNumeric

/**
 * Numeric score response data
 */
public final class GetScoresResponseDataNumeric {
    String getId();
    String getTimestamp();                      // ISO 8601 timestamp
    String getName();
    ScoreSource getSource();                    // API, EVAL, ANNOTATION
    double getValue();                          // Numeric value
    Optional<String> getComment();
    Optional<String> getConfigId();
    Optional<String> getQueueId();
    GetScoresResponseTraceData getTraceData();  // Associated trace info

    static Builder builder();
}

GetScoresResponseDataCategorical

/**
 * Categorical score response data
 */
public final class GetScoresResponseDataCategorical {
    String getId();
    String getTimestamp();
    String getName();
    ScoreSource getSource();
    String getValue();                          // Categorical value (string)
    Optional<String> getComment();
    Optional<String> getConfigId();
    Optional<String> getQueueId();
    GetScoresResponseTraceData getTraceData();

    static Builder builder();
}

GetScoresResponseDataBoolean

/**
 * Boolean score response data
 */
public final class GetScoresResponseDataBoolean {
    String getId();
    String getTimestamp();
    String getName();
    ScoreSource getSource();
    boolean getValue();                         // Boolean value
    Optional<String> getComment();
    Optional<String> getConfigId();
    Optional<String> getQueueId();
    GetScoresResponseTraceData getTraceData();

    static Builder builder();
}

GetScoresResponseTraceData

/**
 * Associated trace information for a score
 */
public final class GetScoresResponseTraceData {
    String getTraceId();
    Optional<String> getTraceName();
    Optional<String> getUserId();
    Optional<Object> getMetadata();
    Optional<String> getRelease();
    Optional<String> getVersion();
    Optional<String> getSessionId();
    Optional<List<String>> getTags();
    Optional<String> getEnvironment();

    static Builder builder();
}

ScoreConfig

/**
 * Score configuration/template
 */
public final class ScoreConfig {
    String getId();
    String getName();
    ScoreDataType getDataType();                // NUMERIC, CATEGORICAL, BOOLEAN
    Optional<Boolean> getIsArchived();
    Optional<List<ConfigCategory>> getCategories();
    Optional<Double> getMinValue();
    Optional<Double> getMaxValue();
    Optional<String> getDescription();
    String getCreatedAt();  // ISO 8601 timestamp
    String getUpdatedAt();  // ISO 8601 timestamp

    static Builder builder();
}

ConfigCategory

/**
 * Category definition for categorical scores
 */
public final class ConfigCategory {
    String getValue();         // Category value
    Optional<String> getLabel(); // Display label

    static Builder builder();
}

ScoreConfigs

/**
 * List of score configs
 */
public final class ScoreConfigs {
    List<ScoreConfig> getData();

    static Builder builder();
}

Enums

ScoreDataType

/**
 * Data type for scores
 */
public enum ScoreDataType {
    NUMERIC,      // Double value
    CATEGORICAL,  // String value from predefined categories
    BOOLEAN       // Boolean value
}

ScoreSource

/**
 * Source of the score
 */
public enum ScoreSource {
    API,         // Created via API
    EVAL,        // Created by evaluation
    ANNOTATION   // Created by human annotation
}

Complete Scoring Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.score.types.*;
import com.langfuse.client.resources.scorev2.types.*;
import com.langfuse.client.resources.scorev2.requests.GetScoresRequest;
import com.langfuse.client.resources.scoreconfigs.types.*;
import com.langfuse.client.resources.commons.types.*;
import java.time.OffsetDateTime;
import java.util.List;

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

        // 1. Create score configurations
        CreateScoreConfigRequest qualityConfig = CreateScoreConfigRequest.builder()
            .name("quality")
            .dataType(ScoreDataType.NUMERIC)
            .minValue(0.0)
            .maxValue(1.0)
            .description("Response quality score (0-1)")
            .build();

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

        CreateScoreConfigRequest sentimentConfig = CreateScoreConfigRequest.builder()
            .name("sentiment")
            .dataType(ScoreDataType.CATEGORICAL)
            .categories(List.of(
                ConfigCategory.builder().value("positive").label("Positive").build(),
                ConfigCategory.builder().value("neutral").label("Neutral").build(),
                ConfigCategory.builder().value("negative").label("Negative").build()
            ))
            .description("Sentiment classification")
            .build();

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

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

        // Quality score (numeric)
        CreateScoreRequest qualityScore = CreateScoreRequest.builder()
            .name("quality")
            .value(CreateScoreValue.of(0.87))
            .traceId(traceId)
            .dataType(ScoreDataType.NUMERIC)
            .configId(qualityCfg.getId())
            .comment("Good response, minor issues")
            .build();

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

        // Sentiment score (categorical)
        CreateScoreRequest sentimentScore = CreateScoreRequest.builder()
            .name("sentiment")
            .value(CreateScoreValue.of("positive"))
            .traceId(traceId)
            .dataType(ScoreDataType.CATEGORICAL)
            .configId(sentimentCfg.getId())
            .build();

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

        // PII detection (boolean - use 0.0 or 1.0)
        CreateScoreRequest piiScore = CreateScoreRequest.builder()
            .name("contains_pii")
            .value(CreateScoreValue.of(0.0))  // 0.0 = false, 1.0 = true
            .traceId(traceId)
            .dataType(ScoreDataType.BOOLEAN)
            .comment("No PII detected")
            .build();

        client.score().create(piiScore);

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

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

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

                @Override
                public Void visitCategorical(GetScoresResponseDataCategorical categorical) {
                    System.out.println("  " + categorical.getName() + ": " + categorical.getValue());
                    return null;
                }

                @Override
                public Void visitBoolean(GetScoresResponseDataBoolean bool) {
                    System.out.println("  " + bool.getName() + ": " + bool.getValue());
                    return null;
                }

                @Override
                public Void visitUnknown(String unknownType) {
                    return null;
                }
            });
        }

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

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

        // 5. Query by source
        GetScoresRequest apiScoresRequest = GetScoresRequest.builder()
            .source(ScoreSource.API)
            .dataType(ScoreDataType.NUMERIC)
            .limit(50)
            .build();

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

        // 6. List all score configs
        ScoreConfigs configs = client.scoreConfigs().get();
        System.out.println("\nScore configurations:");
        for (ScoreConfig config : configs.getData()) {
            System.out.println("  " + config.getName() +
                             " (" + config.getDataType() + ")" +
                             " - " + config.getDescription().orElse(""));
        }
    }
}

Best Practices

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

Related Documentation

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