Annotations

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.

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

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.

Compliance and QA review

Flag responses with specific defects (hallucination, off-topic, inappropriate content) using structured annotation keys shared across the team.

Dataset curation

Annotate Traces with corrections and quality labels, then export curated subsets as training datasets for future experiments.

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

Define annotation schemas: keys, value types, and validation rules. Available on chat completion and responses spans once created.

Annotation Queues

Organize annotation review workflows. Filter and present relevant Traces for review in bulk.

Annotations API

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.

AI Studio

To create an annotation, head to Optimization > Annotations in AI Studio, or Settings > Annotations in AI Gateway, and press the button. Annotations can also be created directly from an Annotation Queue.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

Once created, an annotation is available on all chat completion spans and responses spans in the project. No additional configuration or filtering required.

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.

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

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.

Rating

Rate the overall quality of AI responses:

Rating	Description
good	The response was helpful and accurate.
bad	The response was unhelpful or inaccurate.

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

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 or Logs view and use the Annotations panel.
In an Annotation Queue: review a curated set of Traces in bulk. Fill a queue with Trace Automations 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: apply annotations while reviewing experiment outputs.

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.

AI Studio
API & SDK

The annotation capabilities differ between Logs and Traces. Logs support human feedback and text corrections to the AI response. Traces support human feedback and correcting an evaluator result.

Traces
Logs

Navigate to the Traces view and select a single trace. The Annotations panel will be displayed, allowing you to apply human feedback to the AI response.

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.

Add Multiple Defects

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"]
      }
    ]
  }'

Add a Numeric Score

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"
    }
  }'

Add a Text Correction

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."
      }
    ]
  }'

For error handling, batch limits, and constraints, see Annotations API.

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.

Correcting an Evaluator result is not available in the experiment review screen. Annotations and Evaluator scores still display as described above.

Overview

Instrument your app

Explore

Monitor

Export

Review

Data privacy & security

Framework integrations

Annotations

Annotations

Annotation Queues

Annotations API

Create Annotations

Common Annotations Legacy

Use Annotations

Annotations in Experiments

Annotations

Annotation Queues

Annotations API

​Create Annotations

​Common Annotations Legacy

​Use Annotations

​Annotations in Experiments

Create Annotations

Common Annotations Legacy

Use Annotations

Annotations in Experiments