For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
DiscordPlatform
DocumentationIntegrationsAPI referenceSDKsChangelog
DocumentationIntegrationsAPI referenceSDKsChangelog
  • API Reference
      • POSTCreate a score
      • GETList scores
      • GETRetrieve a score
      • PATCHUpdate a score
      • DELDelete a score
      • POSTCreate or update a log score
      • GETList log scores
      • GETRetrieve a log score
      • PATCHUpdate a log score
      • DELDelete a log score
      • POSTFilter scores
      • PUTReplace a score
      • PUTReplace a log score
  • Reference
    • Filters API Reference
LogoLogo
DiscordPlatform
API ReferenceScores

Create or update a log score

POST
https://api.respan.ai/api/logs/:log_id/scores/
POST
/api/logs/:log_id/scores/
$curl -X POST https://api.respan.ai/api/logs/log_id/scores/ \
>     -H "Authorization: Bearer sk_live_xxxxx" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "evaluator_slug": "response_quality",
>  "timestamp": "2026-04-10T12:00:00Z",
>  "numerical_value": 4.5
>}'
1{
2  "id": "score_9f8b7c6d",
3  "created_at": "2024-01-15T09:30:00Z",
4  "type": "llm",
5  "environment": "production",
6  "numerical_value": 4.5,
7  "string_value": "Good response quality",
8  "boolean_value": true,
9  "categorical_value": [
10    "excellent"
11  ],
12  "json_value": "{\"rating\": 5, \"reason\": \"Accurate\"}",
13  "is_passed": true,
14  "cost": 0,
15  "evaluator_id": "evl_9f8b7c6d",
16  "evaluator_slug": "response_quality",
17  "evaluator_name": "Response Quality",
18  "scorer": "marcus@example.com",
19  "log_id": "log_abc123",
20  "prompt_id": "prompt_12345",
21  "prompt_version_number": 2,
22  "dataset_id": "dataset_67890",
23  "automation_id": "auto_54321",
24  "status": "completed",
25  "error_message": ""
26}

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.

Was this page helpful?
Previous

List log scores

Next
Built with

Path parameters

log_idstringRequired

Log/span unique ID to manage scores for.

Headers

AuthorizationstringRequired

Bearer token. Use Bearer YOUR_API_KEY for API key auth or Bearer <JWT> for dashboard auth.

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.

Response

Updated existing score for this log/evaluator/scorer.

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

Numeric score value. Use for numerical and percentage evaluators.

string_valuestring or null

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

boolean_valueboolean or null

Boolean score value. Use for boolean evaluators.

categorical_valuelist of strings or null

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

json_valuestring or null

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

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

Human-readable evaluator name, when available.

scorerstring or null

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

log_idstring or null

Associated log/span ID.

prompt_idstring or null
Associated prompt ID, when available.
prompt_version_numberinteger or null
Associated prompt version number, when available.
dataset_idstring or null
Associated dataset ID, when available.
automation_idstring or null
Associated automation ID, when available.
statusstring or null
Evaluation status, when available.
error_messagestring or null
Evaluation error message, when available.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error

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.