> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Scores API

> Query quality scores recorded against traces and generations.

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

```text theme={null}
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

```json theme={null}
{
  "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

```text theme={null}
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

```json theme={null}
{
  "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

```bash theme={null}
squasher scores list --project $PROJECT_ID --name helpfulness --source eval
squasher scores summary --project $PROJECT_ID --trace-id trace-1
```