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

# Annotations

> Define annotation schemas and apply structured human feedback to LLM traces and spans in AI Studio, through the API and SDK, or from the CLI.

After observing an application in production, the next step is annotating and curating that data to build evaluation datasets. This process turns raw production logs into high-quality test cases that drive systematic improvement.

> [!NOTE]
>
> **The Feedback API is deprecated.** Existing Feedback API integrations continue to work. Use Annotations to capture user ratings, comments, and corrections on completed requests.

**Use Cases**

> [accordion] Collecting quality feedback
>
> Capture thumbs up/down ratings, custom scores, or categorical labels on AI responses. Build a feedback loop that surfaces low-quality generations for review.

> [accordion] Compliance and QA review
>
> Flag responses with specific defects (hallucination, off-topic, inappropriate content) using structured annotation keys shared across the team.

> [accordion] Dataset curation
>
> Annotate Traces with corrections and quality labels, then export curated subsets as training datasets for future experiments.

> [accordion] Human-in-the-loop workflows
>
> Route Traces to Annotation Queues for systematic expert review. Combine with Trace Automations to automatically surface Traces that meet specific criteria.

**Concepts**

Three concepts work together to form the annotations system:

* **Annotations**: the feedback categories configured for a project, such as a quality rating or a defect tag
* **Annotation Queues**: organized workflows for reviewing Traces in bulk via **AI Studio**
* **Annotations API**: the API and SDK for applying feedback values to a Trace or span programmatically

> [card] [Annotations](#create-annotations)
>
> Define annotation schemas: keys, value types, and validation rules. Available on chat completion and responses spans once created.

> [card] [Annotation Queues](/docs/ai-studio/observability/annotation-queues.md#use-annotation-queues)
>
> Organize annotation review workflows. Filter and present relevant Traces for review in bulk.

> [card] [Annotations API](/docs/ai-studio/observability/annotations-api.md)
>
> Apply structured human feedback to Traces and spans programmatically via the API and SDK.

## Create Annotations

Each annotation must be defined in the project before it can be used. The definition sets the key, title, and value type; applying an annotation to a Trace requires matching one of these definitions. The workspace-provided keys `rating` and `correction` are shared across projects, and each project defines them before their values appear on its pages.

> [tab] AI Studio
>
> To create an annotation, head to **Optimization > Annotations** in **AI Studio**, or **Settings > Annotations** in **AI Gateway**, and press the <kbd /> button. Annotations can also be created directly from an [Annotation Queue](/docs/ai-studio/observability/annotation-queues.md#use-annotation-queues).
>
> Each annotation uses one of three value types:
>
> * **Categorical**: button options with custom labels, such as good/bad or saved/deleted
>
> * **Range**: a custom scoring slider, for example a scale from 0 to 100
>
> * **Open field**: free-form text input for detailed comments
>
> > [!NOTE]
> >
> > Once created, an annotation is available on all chat completion spans and responses spans in the project. No additional configuration or filtering required.
>
> > [!TIP]
> >
> > Select the project before creating a definition. An annotation created inside a project belongs to that project, which keeps each project's annotation set focused on its own review needs. Definitions created at workspace level remain available across every project.
>
> > [!NOTE]
> >
> > Deleting an annotation removes it from any Annotation Queues and Experiments that use it, so it no longer appears as a review option there. Annotations already recorded on a Trace are preserved: every annotated data point remains stored and queryable.

### Common Annotations   Legacy

> [!NOTE]
>
> The `rating` and `correction` keys are shared across the workspace. A value written under either appears on a project's pages only after that project defines the same annotation.

> [accordion] Rating
>
> Rate the overall quality of AI responses:
>
> | Rating | Description |
> | - | - |
> | **good** | The response was helpful and accurate. |
> | **bad** | The response was unhelpful or inaccurate. |

> [accordion] Defects
>
> Identify specific issues with AI responses:
>
> | Defect | Description |
> | - | - |
> | **grammatical** | Responses that contain grammatical errors |
> | **spelling** | Responses that contain spelling errors |
> | **hallucination** | Responses that contain hallucinations or factual inaccuracies |
> | **repetition** | Responses that contain unnecessary repetition |
> | **inappropriate** | Responses that are deemed inappropriate or offensive |
> | **off\_topic** | Responses that do not address the user's query |
> | **incompleteness** | Responses that are incomplete or partially address the query |
> | **ambiguity** | Responses that are vague or unclear |
>
> > [!NOTE]
> >
> > Multiple defects can be selected for one response using an annotation configured with an array value.

## Use Annotations

Annotations can be applied wherever a Trace or span is reviewed:

* **Directly on a Trace or Log**: open a single Trace or Log in the [Traces](/docs/ai-studio/observability/traces.md) or Logs view and use the **Annotations** panel.
* **In an [Annotation Queue](/docs/ai-studio/observability/annotation-queues.md#use-annotation-queues)**: review a curated set of Traces in bulk. Fill a queue with [Trace Automations](/docs/ai-studio/observability/automations.md) or by manually adding individual Traces or Logs.
* **Programmatically**: apply feedback through the API and SDK using the **API & SDK** tab below.
* **In an [Experiment](#annotations-in-experiments)**: apply annotations while reviewing experiment outputs.

> [!NOTE]
>
> Every annotation applied in an Annotation Queue is written back to its originating Trace. Because the values live on the Trace, they can be queried with the **Toqan Router MCP** and used to run analysis across reviewed data.

> [tab] AI Studio
>
> The annotation capabilities differ between Logs and [Traces](/docs/ai-studio/observability/traces.md). Logs support human feedback and text corrections to the AI response. Traces support human feedback and [correcting an evaluator result](/docs/ai-studio/observability/traces.md#correct-an-evaluator-result).
>
> > [tab] Traces
> >
> > Navigate to the [Traces](/docs/ai-studio/observability/traces.md) view and select a single trace. The **Annotations** panel will be displayed, allowing you to apply human feedback to the AI response.
>
> > [tab] Logs
> >
> > Navigate to the Logs view and select a single log. The **Annotations** panel will be displayed, allowing you to apply human feedback and provide corrections to the AI response.
> >
> > To make a correction, use the **Add correction** button below the AI-generated response:
> >
> > Click to add a correction, which opens an editor for manually revising the model's response. Select **Save** to store the correction.
> >
> > > [!NOTE]
> > >
> > > Corrections are valuable for building curated datasets. Learn more in Creating a Curated Dataset.

> [tab] API & SDK
>
> Quick examples for annotating LLM responses. For the full usage guide (request fields, annotation values, corrections, batch and remove semantics, and error handling), see [Annotations API](/docs/ai-studio/observability/annotations-api.md).
>
> > [accordion] Add Multiple Defects
> >
> > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
> >   -H "Authorization: Bearer $TOQAN_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{
> >     "annotations": [
> >       {
> >         "key": "defects",
> >         "value": ["grammatical", "spelling", "ambiguity"]
> >       }
> >     ]
> >   }'
> > ```
>
> > [accordion] Add a Numeric Score
> >
> > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
> >   -H "Authorization: Bearer $TOQAN_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{
> >     "annotations": [
> >       {
> >         "key": "star-rating",
> >         "value": 4
> >       }
> >     ],
> >     "metadata": {
> >       "identity_id": "user-123"
> >     }
> >   }'
> > ```
>
> > [accordion] Add a Text Correction
> >
> > ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
> > curl -X POST "https://router.toqan.ai/eu/v2/traces/{trace_id}/spans/{span_id}/annotation" \
> >   -H "Authorization: Bearer $TOQAN_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{
> >     "annotations": [
> >       {
> >         "key": "correction",
> >         "value": "The correct answer should emphasize scalability and fault tolerance."
> >       }
> >     ]
> >   }'
> > ```
>
> > [!NOTE]
> >
> > For error handling, batch limits, and constraints, see [Annotations API](/docs/ai-studio/observability/annotations-api.md#error-handling).

## Annotations in Experiments

Annotations can also be applied outside of Annotation Queues, while reviewing the outputs of an Experiment. In the experiment review screen, the annotations defined for the project appear alongside Evaluator scores, so outputs can be annotated manually as part of an evaluation run.

> [!NOTE]
>
> [Correcting an Evaluator result](/docs/ai-studio/observability/traces.md#correct-an-evaluator-result) is not available in the experiment review screen. Annotations and Evaluator scores still display as described above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.