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

# Evaluation

> Score and evaluate your queries

## Overview

The evaluation API allows you to score and evaluate your queries and highlights. Providing scores for results improves the quality of the results over time and makes them more relevant to your users.

## Usage

Every query returned through the [search](/api-reference/memories/query-memories) method contains a `query_id` field. Similarly, each highlight returned contains a `highlight_id`. You can use these IDs to score and evaluate the results:

```json theme={null}
{
  "query_id": "<string>",
  "score": <number>,
  "documents": [
    {
      ...
      "highlights": [
        {
          "highlight_id": "<string>",
          "score": <number>,
          "comments": ["<string>", "<string>", ...]
        }
      ]
    }
  ]
}
```

The `score` field is the average score of the query based on all evaluations sent. The `comments` field is a list of comments given for a particular highlight using the methods described below.

You can also use the `query_id` to [retrieve an existing query](/api-reference/evaluation/get-query-result) at a later point in time.

## Scoring queries

You can score a queries with the [Evaluation API](/api-reference/evaluation/score-a-query-result):

<CodeGroup>
  ```python Python theme={null}
  client.evaluate.score_query(
      query_id="<string>",
      score=1.0
  )
  ```

  ```typescript TypeScript theme={null}
  await client.evaluate.scoreQuery({
      query_id: "<string>",
      score: 1.0
  });

  ```
</CodeGroup>

The score must be between -1 and 1. The higher the score, the more relevant the query results will be. If you are receiving user feedback as a simple thumbs-down or thumbs-up, you should interpred this as a score of -1 or 1 respectively.

## Scoring highlights

Similarly,you can score individual highlights with the [Evaluation API](/api-reference/evaluation/score-a-highlight). This also lets you provide a comment for the evaluation.

<CodeGroup>
  ```python Python theme={null}
  client.evaluate.score_highlight(
      highlight_id="<string>",
      score=-1.0,
      comment="This needs to be improved"
  )
  ```

  ```typescript TypeScript theme={null}
  await client.evaluate.scoreHighlight({
      highlight_id: "<string>",
      score: -1.0,
      comment: "This needs to be improved"
  });
  ```
</CodeGroup>

As above, the score must be between -1 and 1. The `comment` field is a free-form text field that you can use to provide additional context for the evaluation. If you only want to provide a comment, you may omit the `score` field.