Scores

The Score resource lets you create, retrieve, list, and delete scores in Langfuse. Scores are used to evaluate and annotate traces, observations, sessions, or dataset runs.

Access

$score = $langfuse->score();

Data types

Scores support three data types via the ScoreDataType enum:

use DIJ\Langfuse\PHP\Enums\ScoreDataType;

ScoreDataType::NUMERIC;     // float value (default)
ScoreDataType::CATEGORICAL; // string value
ScoreDataType::BOOLEAN;     // string "True" or "False"

Creating scores

Numeric score

$score = $langfuse->score()->create(
    name: 'accuracy',
    value: 0.95,
    traceId: 'trace-id-123',
    dataType: ScoreDataType::NUMERIC,
    comment: 'High accuracy score',
);

echo $score->id;    // "clx..."
echo $score->value; // 0.95

Categorical score

$score = $langfuse->score()->create(
    name: 'sentiment',
    value: 'positive',
    traceId: 'trace-id-123',
    dataType: ScoreDataType::CATEGORICAL,
);

Boolean score

$score = $langfuse->score()->create(
    name: 'is-correct',
    value: 'True',
    traceId: 'trace-id-123',
    dataType: ScoreDataType::BOOLEAN,
);

Score on an observation

$score = $langfuse->score()->create(
    name: 'quality',
    value: 0.8,
    traceId: 'trace-id-123',
    observationId: 'generation-id-456',
);

All create parameters

Parameter	Type	Required	Description
name	string	Yes	Name of the score
value	float|string	Yes	Score value
traceId	?string	No	Associated trace
dataType	?ScoreDataType	No	Defaults to NUMERIC
id	?string	No	Custom score ID
observationId	?string	No	Associated observation (generation/span)
comment	?string	No	Human-readable comment
configId	?string	No	Score config reference
sessionId	?string	No	Associated session
datasetRunId	?string	No	Associated dataset run
metadata	?array	No	Arbitrary metadata
environment	?string	No	Environment tag
queueId	?string	No	Queue reference

Retrieving a score

$score = $langfuse->score()->get('score-id-123');

echo $score->id;
echo $score->name;
echo $score->value;
echo $score->dataType->value; // "NUMERIC"
echo $score->source->value;   // "API"
echo $score->comment;

ScoreResponse properties

Property	Type	Description
id	string	Score ID
traceId	?string	Associated trace
name	string	Score name
value	float|string	Score value
dataType	ScoreDataType	NUMERIC, CATEGORICAL, or BOOLEAN
source	ScoreSource	API, ANNOTATION, or EVAL
observationId	?string	Associated observation
comment	?string	Comment
configId	?string	Config reference
queueId	?string	Queue reference
stringValue	?string	String representation of value
createdAt	?string	Creation timestamp
updatedAt	?string	Last update timestamp
authorUserId	?string	Author user ID

Listing scores

$result = $langfuse->score()->list(
    traceId: 'trace-id-123',
    limit: 10,
);

foreach ($result->data as $score) {
    echo $score->name . ': ' . $score->value;
}

echo $result->meta->totalItems;
echo $result->meta->totalPages;

Filtering

use DIJ\Langfuse\PHP\Enums\ScoreDataType;

// By data type
$result = $langfuse->score()->list(dataType: ScoreDataType::NUMERIC);

// By name
$result = $langfuse->score()->list(name: 'accuracy');

// By source
$result = $langfuse->score()->list(source: 'API');

// By date range
$result = $langfuse->score()->list(
    fromTimestamp: '2025-01-01T00:00:00Z',
    toTimestamp: '2025-12-31T23:59:59Z',
);

// By session
$result = $langfuse->score()->list(sessionId: 'session-123');

// By value with operator
$result = $langfuse->score()->list(
    operator: '>',
    value: 0.5,
);

// Pagination
$result = $langfuse->score()->list(page: 2, limit: 25);

All list parameters

Parameter	Type	Description
page	?int	Page number
limit	?int	Items per page
userId	?string	Filter by user
name	?string	Filter by score name
fromTimestamp	?string	Start of date range
toTimestamp	?string	End of date range
environment	?array	Filter by environment
source	?string	Filter by source (API, ANNOTATION, EVAL)
operator	?string	Comparison operator for value filter
value	?float	Value to compare against
configId	?string	Filter by config
sessionId	?string	Filter by session
datasetRunId	?string	Filter by dataset run
traceId	?string	Filter by trace
queueId	?string	Filter by queue
dataType	?ScoreDataType	Filter by data type
traceTags	?array	Filter by trace tags
fields	?string	Select specific fields
scoreIds	?string	Filter by score IDs

Deleting a score

$langfuse->score()->delete('score-id-123');

Returns void. Throws an exception if the score is not found.

Method reference

Method	Parameters	Returns
create()	See create parameters	ScoreResponse
get()	string $scoreId	ScoreResponse
list()	See list parameters	ScoreListResponse
delete()	string $scoreId	void