# Scores
URL: /docs/cloud/api/scores

Record numeric, categorical and boolean scores against a thread, message or run.

> For AI agents: a documentation index is available at [llms.txt](/llms.txt). Use `.md` for canonical markdown pages; `.mdx` is kept as a backwards-compatible alias on supported URL paths.

A score records one named value against a thread, a message or a run. A browser sends scores with an authenticated token on the project's frontend host, and a server sends them to `https://backend.assistant-api.com` with an API key and the `Aui-User-Id` and `Aui-Workspace-Id` headers; see [Conventions](/docs/cloud/api) for hosts, credentials and shared errors.

## The score object

| Field          | Type           | Meaning                                                             |
| -------------- | -------------- | ------------------------------------------------------------------- |
| `score_id`     | string         | The identifier of the stored score.                                 |
| `name`         | string         | The score name.                                                     |
| `data_type`    | enum           | `numeric`, `categorical` or `boolean`.                              |
| `value`        | number or null | The numeric value, or `1` or `0` for a boolean score.               |
| `string_value` | string or null | The categorical value. It is `null` for numeric and boolean scores. |

## Create a score

```
POST /v1/scores
```

| Field          | Type              | Required    | Rules                                                                                                                                                                           |
| -------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string            | yes         | 1 to 64 characters and matches `/^[A-Za-z0-9_.-]+$/`.                                                                                                                           |
| `data_type`    | enum              | yes         | One of `numeric`, `categorical` or `boolean`.                                                                                                                                   |
| `value`        | number or boolean | conditional | Required and must be a number for `numeric`. For `boolean`, only `true`, `false`, `1` or `0` is accepted. Forbidden for `categorical`. Boolean values are stored as `1` or `0`. |
| `string_value` | string            | conditional | Required for `categorical`, 1 to 255 characters. Forbidden for `numeric` and `boolean`.                                                                                         |
| `comment`      | string            | no          | 1 to 2,000 characters when present.                                                                                                                                             |
| `thread_id`    | string            | conditional | 1 to 48 characters. Required for a thread target or a message target.                                                                                                           |
| `message_id`   | string            | conditional | 1 to 48 characters. Required for a message target.                                                                                                                              |
| `run_id`       | string            | conditional | 1 to 48 characters. Required for a run target.                                                                                                                                  |

Exactly one target is required. A message target has both `message_id` and `thread_id` and no `run_id`; a run target has `run_id` alone; a thread target has `thread_id` alone. With no target, validation reports `a score must target a message, run, or thread`. With any other target combination, validation reports `a score must target exactly one message, run, or thread`.

The type validation messages are `value is required for numeric scores`, `boolean scores require value to be true, false, 1, or 0`, `string_value is required for categorical scores`, `categorical scores cannot include value` and `only categorical scores can include string_value`.

```
curl https://backend.assistant-api.com/v1/scores \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "answer_quality",
    "data_type": "numeric",
    "value": 1,
    "comment": "Resolved the request",
    "thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U"
  }'
```

```
{
  "name": "answer_quality",
  "data_type": "numeric",
  "value": 1,
  "comment": "Resolved the request",
  "thread_id": "thread_0qzof3jPoDwr7K3agyJN3D4U"
}
```

```
{
  "score_id": "score_0qzof3jPoDwr7K3agyJN3D4U",
  "name": "answer_quality",
  "data_type": "numeric",
  "value": 1,
  "string_value": null
}
```

| Status | Body                                                 | When                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `201`  | `{ score_id, name, data_type, value, string_value }` | The score was stored.                                                                                                                                                                                                                                                                                                                                                                                               |
| `400`  | `{ "success": false, "error": … }`                   | A field failed validation. The messages include `value is required for numeric scores`, `boolean scores require value to be true, false, 1, or 0`, `string_value is required for categorical scores`, `categorical scores cannot include value`, `only categorical scores can include string_value`, `a score must target a message, run, or thread` and `a score must target exactly one message, run, or thread`. |
| `400`  | `{ "error": "message_id must belong to thread_id" }` | The message is not in the supplied thread.                                                                                                                                                                                                                                                                                                                                                                          |
| `404`  | `{ "error": "Thread not found" }`                    | The target thread is not visible in the caller's scope.                                                                                                                                                                                                                                                                                                                                                             |
| `404`  | `{ "error": "Run not found" }`                       | The target run is not visible in the caller's scope.                                                                                                                                                                                                                                                                                                                                                                |

The score source is `api` for an API key and `end_user` for a JWT. Scores are upserted per target and author. Message scores conflict on `(message_id, name, author_id)`, run scores on `(run_id, name, author_id)`, and thread scores on `(thread_id, name, author_id)`; a conflict updates the existing row and its `updated_at`. Read scores back from the [project API](/docs/cloud/api/project).

## Message feedback

The thumbs in the assistant-ui components call [message feedback](/docs/cloud/api/messages#submit-message-feedback), which writes one boolean score named `feedback` per message and user. Read it back like any other score.