Record a score

POST 
/api/v1/evals/record-score

Records a tenant-side reviewer/operator score.

Resolving the rated turn

Section ID: DOC-IS-evaluation-api-recordScore#resolving-the-rated-turn

Turn addressing is trace-only. A bare conversation ID is qualified with trusted tenant context. Messages without the required historical addressing metadata can be rejected; use an independently verified trace ID in that case.

The API assigns human-source classification and derives rater context from trusted credentials, not the body. A machine key does not identify a human reviewer. A deterministic per-rater/target/name score ID supports replacing a rating, but the current delete operation does not enforce author ownership.

Supported ratings

Section ID: DOC-IS-evaluation-api-recordScore#supported-ratings

Use a trace target with numeric or boolean values. The current API maps the resolved target into traceId; categorical/text values and observation/session/dataset-run targets in the schema are not faithfully supported. Use the supported trace/value combinations shown here.

Examples

Section ID: DOC-IS-evaluation-api-recordScore#examples

The request examples below show a numeric score of 0.9 for a trace target and a configured helpfulness rating with an explanatory comment. Use your verified trace target and applicable score configuration; the example identifiers are illustrative.

Re-rating and withdrawing

Section ID: DOC-IS-evaluation-api-recordScore#re-rating-and-withdrawing

A stable per-rater/target/name score ID does not alone guarantee one current record across dates. The current API omits the original creation timestamp needed for cross-day replacement. Verify read-back after retries or re-rating. Withdrawal must check creator and scope; delete-score currently lacks that creator check and must remain restricted to trusted operators.

The following access conditions are preserved as declared intent and are not implemented by generated code: Authorized scoped domain action.

Use this in a guide: Review and score turns · Feedback and score attribution

Request

Responses

200

OK

Score an existing trace as an authenticated rater; this numeric example records 0.9.

Section ID: DOC-IS-evaluation-api-recordScore#example-evals-recordScore-request

Request example

{
  "targetType": "EVAL_TARGET_TYPE_TRACE",
  "targetId": "trace_123",
  "name": "answer-quality",
  "dataType": "SCORE_DATA_TYPE_NUMERIC",
  "numericValue": 0.9
}

Guide request for 3. Record the rating. Replace example resource identifiers with your own authorized values.

Section ID: DOC-IS-evaluation-api-recordScore#example-cookbook-insights-evaluation-review-05-request

Request example

{
  "targetType": "EVAL_TARGET_TYPE_TRACE",
  "targetId": "…",
  "name": "helpfulness",
  "dataType": "SCORE_DATA_TYPE_NUMERIC",
  "numericValue": 4,
  "configId": "cfg_helpfulness",
  "comment": "Accurate, but buried the answer in three paragraphs."
}

Illustrative response shape; omitted default fields and actual outcomes depend on the operation.

Section ID: DOC-IS-evaluation-api-recordScore#example-evals-recordScore-response

Response example

{
  "scoreId": "example_123",
  "targetId": "example_123",
  "targetType": "EVAL_TARGET_TYPE_TRACE"
}

Document ID: DOC-IS-evaluation-api-recordScore. Section identities and revisions.

Section	Stable reference
Record a score	DOC-IS-evaluation-api-recordScore#overview
Request	DOC-IS-evaluation-api-recordScore#request
Responses	DOC-IS-evaluation-api-recordScore#responses