# Scores and feedback

> Score a request or a run from your code, and collect thumbs up or down from the people reading your answers with a signed token, no API key in the browser.

Source: https://infro.io/docs/observability/scores

A score is one judgement of one request or one [run](https://infro.io/docs/observability/runs): a number, true or false, or a category name, with a name you choose and an optional comment. Scores come from four places, recorded as `source`: your code (`api`), the people reading your answers (`end_user`), [decision eval monitors](https://infro.io/docs/features/decisions) (`eval`, named after the policy) and members in the console (`console`). They appear on the request, on the run and on a [prompt version](https://infro.io/docs/features/prompts)'s figures. Scores and feedback are not gateway requests: they do not count against your plan's request allowance.

## Send scores

```bash
curl https://api.infro.io/v1/scores \
  -H "Authorization: Bearer $INFRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scores": [
      { "request_id": "req_9f27c1d0a4b84e6f", "name": "groundedness", "value": 0.82 },
      { "trace_id": "run_42", "name": "resolved", "value": true, "comment": "Customer closed the ticket." }
    ]
  }'
```

- `request_id / trace_id` (string, required) — Exactly one: the request's id (`req_…`, the response's `id` and `X-INFRO-Request-Id`), or the run's trace id.
- `name` (string, required) — 1 to 64 characters of `a-z 0-9 _ . -`, for example `groundedness` or `user.resolved`.
- `value` (number | boolean | string, required) — A finite number (`kind: numeric`), `true` or `false` (`kind: boolean`), or a category name of 1 to 64 characters (`kind: category`).
- `comment` (string) — Up to 2,000 characters. Kept only while your organization stores request content; see below.

Send one score as the body, or up to 100 in `scores`. Any gateway key of the organization may score; a key bound to a project scores only that project's requests and runs. The target must be inside your plan's request history. A batch is all or nothing: one target the key may not score refuses the whole call with `404` `request_not_found`, the same answer as an id that never existed. The `201` answer lists each score's `id`, `kind` and `source`, and `comments_stored`, which is `false` when a comment was sent and not kept.

## Read scores

`GET /v1/scores` filters by `request_id`, `trace_id`, `name`, `source`, `from` and `to`, newest first, 1 to 100 a page (`limit`, default 50; `after` = the previous `next_cursor`). It needs history access on the key, as `GET /v1/requests` does, and returns `comment` only to a key with payload access. Each score carries `end_user_id`, copied from the scored request's `metadata.user_id`.

## Feedback from the people reading your answers

Every successful response to a gateway key carries `X-INFRO-Feedback-Token` — chat completions, `/v1/messages`, `/v1/responses`, embeddings, images, audio, video, rerank, decisions and System One. The token is signed by INFRO and names one request. Hand it to the page that shows the answer; when the person clicks thumbs up or down, the page posts it to `POST /v1/feedback`. That endpoint needs no API key and accepts any origin, so your key never reaches the browser: the token is the only authority, and it can score its own request and nothing else, for seven days.

```typescript
// The answer came back with X-INFRO-Feedback-Token. Read it from INFRO's
// response, or from your own API's response if your server relays the header.
const res = await fetch("/api/answer", { method: "POST", body: JSON.stringify({ question }) });
const answer = await res.json();
const feedbackToken = res.headers.get("X-INFRO-Feedback-Token");

// Later, when the person clicks the thumbs-up button:
async function thumbsUp() {
  if (!feedbackToken) return; // no token: nothing to rate
  await fetch("https://api.infro.io/v1/feedback", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ token: feedbackToken, value: true }),
  });
}
```

When your server calls INFRO and the browser calls your server, relay the header with the answer. The header is also exposed to browsers that call INFRO directly.

```typescript
// Your server, with the OpenAI SDK pointed at INFRO: pass the token on.
const { data, response } = await client.chat.completions
  .create({ model: "anthropic/claude-sonnet-5", messages })
  .withResponse();
res.setHeader("X-INFRO-Feedback-Token", response.headers.get("X-INFRO-Feedback-Token") ?? "");
res.json(data);
```

- `token` (string, required) — The `X-INFRO-Feedback-Token` value, unchanged. It may instead be sent as that header.
- `value` (boolean | number, required) — `true` for thumbs up, `false` for thumbs down, or a number such as a 1-5 rating.
- `name` (string) — Default `feedback`. Use another name for a second question, such as `helpful`.
- `comment` (string) — Up to 2,000 characters, kept under the same rule as any score comment.

The answer is `201` with the score's `id` and `comment_stored`. One response accepts at most 10 feedback entries; the eleventh is `429` `feedback_limit_reached`. Feedback is also limited to 10 a minute per token and 120 a minute per address, answered with `429` `too_many_attempts` and `Retry-After`. A token INFRO did not sign is `401` `feedback_token_invalid`, one older than seven days `401` `feedback_token_expired`.

## Comments and retention

A score is kept for your plan's request history window, like the request it scores. A comment is content, often written by your own end users, so it follows your organization's [request logging](https://infro.io/docs/privacy) switch: it is stored only while logging is on and only for a request whose content was recorded (a request sent with `logging: false` keeps no comment; a run counts when one of its requests was recorded), and deleted when your logging retention ends, earlier than the score itself. With logging off, the score is kept and its comment is not. A comment sent within a moment of the response can be dropped although the request is recorded, because the record is written just after the answer. A comment is returned only to readers allowed to read request content.

## In the console

Scores show on a request and on a run. A member who can read analytics can add a score with a comment there (`source: console`).
