Sign in

4e064cf81dae

latestOpenAPI 3.1.02026-08-131831,331960.0 KB
scores

Create a score

Create an evaluation score. Prefer the log-scoped route POST /api/logs/{log_id}/scores/ when creating a score for a known log.

post/api/scores/

Headers

Authorizationstring required

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.

Request body

evaluator_idstring

Evaluator ID. Provide either evaluator_id or evaluator_slug.

evaluator_slugstring

Custom evaluator slug. Provide either evaluator_id or evaluator_slug.

log_idstring

Log/span ID. Required for general score creation when not using the log-scoped route.

timestampstring date-time

Log timestamp. Supplying it can avoid an additional log lookup.

environmentstring

Score environment.

prompt_idstring
prompt_version_numberinteger
dataset_idstring
automation_idstring
scorerstring

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

numerical_valuenumber double nullable

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring nullable

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

boolean_valueboolean nullable

Boolean score value. Use for boolean evaluators.

categorical_valuestring[] nullable

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

json_valuestring nullable

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

explanationstring

Optional explanation for the score.

Response

Created score.

idstring required

Score ID.

created_atstring date-time required

When the score was created.

type'llm' | 'human' | 'code' | 'function' | 'human_numerical' | 'human_boolean' | 'human_categorical' | 'human_text' | 'custom'

Evaluator execution type. Legacy rows may contain legacy type values.

environmentstring

Environment associated with the score.

numerical_valuenumber double nullable

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring nullable

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

boolean_valueboolean nullable

Boolean score value. Use for boolean evaluators.

categorical_valuestring[] nullable

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

json_valuestring nullable

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

is_passedboolean nullable

Whether the score passes the evaluator conditions.

costnumber double nullable

Evaluation cost in USD, when available.

evaluator_idstring nullable

Evaluator ID associated with the score.

evaluator_slugstring nullable

Evaluator slug associated with the score.

evaluator_namestring nullable

Human-readable evaluator name, when available.

scorerstring nullable

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

log_idstring nullable

Associated log/span ID.

prompt_idstring nullable

Associated prompt ID, when available.

prompt_version_numberinteger nullable

Associated prompt version number, when available.

dataset_idstring nullable

Associated dataset ID, when available.

automation_idstring nullable

Associated automation ID, when available.

statusstring nullable

Evaluation status, when available.

error_messagestring nullable

Evaluation error message, when available.

explanationstring

Optional explanation for the score.