Agent Scores API

Cost and latency tell you a model is cheaper and faster. Only a score tells you whether it is as good — which is the question a model swap actually turns on. A score is bound to the trace it judges, and optionally to the single observation within it. Record automated evaluations with captureScore() and editable human feedback with captureFeedback() from the agent SDK, or emit a span carrying the OpenTelemetry gen_ai.evaluation.* attributes. captureFeedback() requires a stable feedbackId; captureScore() accepts the equivalent scoreId. Later writes with the same id replace the earlier value in list and summary results; deleted: true writes a tombstone.

List agent scores

GET https://api.squasher.ai/v1/projects/{project_id}/agent-scores

Query parameters

Parameter	Type	Default	Description
`from`	datetime	-	Start of time range
`to`	datetime	-	End of time range
`trace_id`	string	-	Filter to one trace
`observation_id`	string	-	Filter to the scores on one generation
`session_id`	string	-	Filter to one session
`user_id`	string	-	Filter to one user
`name`	string	-	Filter by score name, e.g. `helpfulness`
`source`	string	-	`api`, `eval`, or `annotation`
`data_type`	string	-	`numeric`, `categorical`, or `boolean`
`limit`	integer	`50`	Results per page (max 100)
`offset`	integer	`0`	Pagination offset

source is a first-class field rather than metadata: a human annotation, an automated judge, and an offline eval carry very different weight, and a rollout decision that mixes them without knowing which is which is not a decision.

Response

{
  "data": [
    {
      "score_id": "score-span-1",
      "trace_id": "trace-1",
      "observation_id": "gen-span-1",
      "span_id": "score-span-1",
      "session_id": "session-1",
      "user_id": "user-1",
      "name": "helpfulness",
      "value": 0.8,
      "string_value": "",
      "data_type": "numeric",
      "source": "eval",
      "comment": "cited every claim",
      "author": "",
      "model": "gpt-5.4",
      "environment": "production",
      "release": "9f2c1a4",
      "started_at": "2026-04-24T07:59:00.000Z",
      "received_at": "2026-04-24T08:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

A categorical score carries its label in string_value and leaves value at 0; a boolean score uses 1 / 0. Scores are never flattened into a single numeric column, because refused and correct do not average.

Summarize agent scores

GET https://api.squasher.ai/v1/projects/{project_id}/agent-scores/summary

Rolls scores up by name and data type. Categorical scores produce one row per label instead of a fake numeric average. This is the shape a model comparison needs — a list of individual judgements is not one. Accepts the same filters as the list endpoint minus limit and offset.

Response

{
  "data": [
    {
      "name": "helpfulness",
      "data_type": "numeric",
      "string_value": "",
      "count": 412,
      "avg_value": 0.83,
      "min_value": 0.1,
      "max_value": 1
    }
  ]
}

For categorical scores, string_value contains the label and avg_value, min_value, and max_value are null.

CLI

squasher scores list --project $PROJECT_ID --name helpfulness --source eval
squasher scores summary --project $PROJECT_ID --trace-id trace-1

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

List agent scores

Query parameters

Response

Summarize agent scores

Response

CLI

​List agent scores

​Query parameters

​Response

​Summarize agent scores

​Response

​CLI

List agent scores

Query parameters

Response

Summarize agent scores

Response

CLI