API ReferenceScores

Create or update a log score

Create a score for a specific log/span. The backend keeps one score per (log, evaluator, scorer) and updates the existing score if the same combination is submitted again.

Authentication

AuthorizationBearer

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

OR
AuthorizationBearer

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

Path parameters

log_idstringRequired

Log/span unique ID to manage scores for.

Request

Use the value field matching the evaluator `score_value_type`: `numerical`/`percentage` -> `numerical_value`, `boolean` -> `boolean_value`, `single_select`/`multi_select`/`categorical` -> `categorical_value`, `text`/`comment` -> `string_value`, `json` -> `json_value`. The log ID comes from the path. The backend derives `scorer` from the authenticated user for this route.
evaluator_idstringOptional

Evaluator ID. Provide either evaluator_id or evaluator_slug.

evaluator_slugstringOptional

Custom evaluator slug. Provide either evaluator_id or evaluator_slug.

timestampdatetimeOptional
Log timestamp. Supplying it can avoid an additional log lookup.
environmentstringOptional
Score environment.
prompt_idstringOptional
prompt_version_numberintegerOptional
dataset_idstringOptional
automation_idstringOptional
scorerstringOptional

Optional score producer for general score creation. Log-scoped routes derive this from the authenticated user.

numerical_valuedouble or nullOptional

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring or nullOptional

Text score value. Use for text and legacy comment evaluators.

boolean_valueboolean or nullOptional

Boolean score value. Use for boolean evaluators.

categorical_valuelist of strings or nullOptional

Categorical score values. Use for single_select, multi_select, and legacy categorical evaluators.

json_valuestring or nullOptional

JSON score value encoded as a string. Use for json evaluators.

explanationstringOptional
Optional explanation for the score.

Response

Updated existing score for this log/evaluator/scorer.

idstring
Score ID.
created_atdatetime
When the score was created.
typeenumOptional
Evaluator execution type. Legacy rows may contain legacy type values.
environmentstringOptional
Environment associated with the score.
numerical_valuedouble or nullOptional

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring or nullOptional

Text score value. Use for text and legacy comment evaluators.

boolean_valueboolean or nullOptional

Boolean score value. Use for boolean evaluators.

categorical_valuelist of strings or nullOptional

Categorical score values. Use for single_select, multi_select, and legacy categorical evaluators.

json_valuestring or nullOptional

JSON score value encoded as a string. Use for json evaluators.

is_passedboolean or nullOptional
Whether the score passes the evaluator conditions.
costdouble or nullOptional
Evaluation cost in USD, when available.
evaluator_idstring or nullOptional
Evaluator ID associated with the score.
evaluator_slugstring or nullOptional
Evaluator slug associated with the score.
evaluator_namestring or nullOptional

Human-readable evaluator name, when available.

scorerstring or nullOptional

Who or what produced the score. For log-scoped score writes, the backend derives this from the authenticated user.

log_idstring or nullOptional

Associated log/span ID.

prompt_idstring or nullOptional
Associated prompt ID, when available.
prompt_version_numberinteger or nullOptional
Associated prompt version number, when available.
dataset_idstring or nullOptional
Associated dataset ID, when available.
automation_idstring or nullOptional
Associated automation ID, when available.
statusstring or nullOptional
Evaluation status, when available.
error_messagestring or nullOptional
Evaluation error message, when available.
explanationstringOptional
Optional explanation for the score.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error