Scores

Record numeric and categorical scores on a run or a single span while it is still open.

On this page

A score is a judgement about a run: a confidence number your model reported, a pass/fail from a validator, a rating an evaluator produced. People add their own from the trace view — see Feedback, comments and sharing. This page is the code path.

#Recording a score

On the run and on one spanTypeScript

import { trace, span, score } from "@tracehatch/sdk"

await trace("answer question", async (run) => {
  await span("check answer", "custom", async (step) => {
    score({ name: "correctness", value: "pass", spanId: step.id })
  })

  run.score({ name: "confidence", value: 0.95, comment: "Evidence matched" })
})

score({ name, value, comment?, spanId? }) uses the current run. run.score(…) works on a manual startTrace handle too. Without a spanId the score belongs to the run; with one it belongs to that span.

Field	Type	Notes
`name`	`string`	Redacted and bounded to 128 characters.
`value`	`number \| string`	Numeric must be finite; categorical must be nonempty.
`comment`	`string`	Optional. Redacted and bounded to 2,048 characters.
`spanId`	`string`	An existing span handle's id. Omit to score the run.

Categorical values are bounded to 256 characters.

#When it is too late

Call score() before run.end(), or before the trace callback returns. Calls outside a recording run, after the run ended, or with invalid values are ignored rather than throwing — telemetry must not break the work it is measuring.

#Duplicates and retries

There are at most 100 SDK scores per run. Each gets a stable scr_ id, so a retried batch cannot create duplicates.

A score aimed at a span is held by the worker until that span arrives and its project, environment and run all match. Recording the score before the span it describes is therefore safe.

#Where they show up

On the run and the span in the trace view, beside human ratings.
In the private score feed for the trace.
In the Prompts comparison, as the average score per prompt.

Scores are private project data, available through the trace scores API. Public share links omit them.

#Human feedback

Project members can rate a run or a span from the trace view — thumbs up or down, with an optional comment — on every plan, and edit or remove their own rating afterwards. Viewers read but do not rate. Human ratings and SDK scores live side by side; the source is recorded with each.

Score analytics beyond the per-prompt average are not built yet.