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. 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.

AI Studio

To create an annotation, head to Optimization > Annotations and press the button. Annotations can also be created directly from an Annotation Queue.

Create annotation form with Key, Title, Description fields and a Type selector showing Categorical, Range, and Text options. — Customizing an Annotation.

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.

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

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 Orq MCP and used to run analysis across reviewed data.

AI Studio
API & SDK
CLI

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.

Trace detail panel for a claude-sonnet chat-completion showing Evaluations section with Defects, Interactions, and Rating feedback options including good/bad thumbs. — The Annotations panel in Traces lets you apply human feedback.

Here are examples on how to use the API to annotate LLM responses.

Add a Quality Rating

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "rating",
        "value": "good"
      }
    ]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {
            "key": "rating",
            "value": "good"
        }
    ]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    {
      key: "rating",
      value: "good"
    }
  ]
});

console.log(result);

Add Multiple Defects

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "defects",
        "value": ["grammatical", "spelling", "ambiguity"]
      }
    ]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {
            "key": "defects",
            "value": ["grammatical", "spelling", "ambiguity"]
        }
    ]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    {
      key: "defects",
      value: ["grammatical", "spelling", "ambiguity"]
    }
  ]
});

console.log(result);

Add a Numeric Score

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "confidence_score",
        "value": 0.95
      }
    ],
    "metadata": {
      "identityId": "user-123"
    }
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {
            "key": "confidence_score",
            "value": 0.95
        }
    ],
    metadata={
        "identityId": "user-123"
    }
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    {
      key: "confidence_score",
      value: 0.95
    }
  ],
  metadata: {
    identityId: "user-123"
  }
});

console.log(result);

Add a Text Correction

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "correction",
        "value": "The correct answer should emphasize scalability and fault tolerance."
      }
    ]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {
            "key": "correction",
            "value": "The correct answer should emphasize scalability and fault tolerance."
        }
    ]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    {
      key: "correction",
      value: "The correct answer should emphasize scalability and fault tolerance."
    }
  ]
});

console.log(result);

Correct an Evaluator Result

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "parent_annotation_id": "<evaluator_annotation_id>",
        "value": false,
        "explanation": "The response omitted a required disclaimer."
      }
    ]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {
            "parent_annotation_id": "<evaluator_annotation_id>",
            "value": False,
            "explanation": "The response omitted a required disclaimer."
        }
    ]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    {
      parentAnnotationId: "<evaluator_annotation_id>",
      value: false,
      explanation: "The response omitted a required disclaimer."
    }
  ]
});

console.log(result);

A correction uses parent_annotation_id in place of key: it’s the id of the Evaluator annotation being corrected. The corrected value must match that Evaluator’s own output type. See Correct an Evaluator Result on the Traces page for the UI equivalent.

Batch Add Multiple Annotations

curl -X POST "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "annotations": [
      {
        "key": "rating",
        "value": "good"
      },
      {
        "key": "confidence_score",
        "value": 0.92
      },
      {
        "key": "categories",
        "value": ["helpful", "accurate", "concise"]
      }
    ]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.create(
    trace_id="<trace_id>",
    span_id="<span_id>",
    annotations=[
        {"key": "rating", "value": "good"},
        {"key": "confidence_score", "value": 0.92},
        {"key": "categories", "value": ["helpful", "accurate", "concise"]}
    ]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.create({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  annotations: [
    { key: "rating", value: "good" },
    { key: "confidence_score", value: 0.92 },
    { key: "categories", value: ["helpful", "accurate", "concise"] }
  ]
});

console.log(result);

Remove Annotations

curl -X DELETE "https://api.orq.ai/v2/traces/{trace_id}/spans/{span_id}/annotation" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": ["rating", "defects"]
  }'

from orq_ai_sdk import Orq
import os

orq = Orq(api_key=os.getenv("ORQ_API_KEY"))

result = orq.annotations.delete(
    trace_id="<trace_id>",
    span_id="<span_id>",
    keys=["rating", "defects"]
)

print(result)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const result = await orq.annotations.delete({
  traceId: "<trace_id>",
  spanId: "<span_id>",
  keys: ["rating", "defects"]
});

console.log(result);

API Error Handling

Status Code	Error	Example Message	Solution
404	Annotation Not Found	`The annotation with key "rating" for workspace abc123 was not found.`	Create an Annotation with the specified key before annotating.
404	Span Not Found	`Span with id xyz789 for workspace abc123 was not found.`	Verify the `trace_id` and `span_id` are correct and belong to the workspace.
400	Invalid Value	`Invalid value: poor. Valid options are: good, bad.`	Ensure the value matches the options defined in the Annotation.
400	Value Out of Range	`Value 15 is out of range [0, 10].`	Provide a number within the defined min/max range for the Annotation.
400	String Too Long	`String value exceeds maximum length of 200 characters.`	Shorten the string annotation to 200 characters or less.

See a complete feedback loop implemented from scratch. Read our cookbook Capturing User Feedback.

Constraints

Batch Limits: up to 10 annotations per create request, up to 10 keys per delete request
String Length: string values are limited to 200 characters maximum
Deployment Span Propagation: when annotating a deployment span, the associated log is automatically annotated with the same values
Metadata Fields: optional metadata object supports identityId, source, and reviewerId for tracking and attribution

Annotate and remove annotations from a span using orq traces create and orq traces delete. The orq traces group manages annotations on existing traces and spans; there is no separate orq annotations group.

Add a Quality Rating

orq traces create <trace_id> <span_id> \
  --annotations '[{"key": "rating", "value": "good"}]'

Add Multiple Defects

orq traces create <trace_id> <span_id> \
  --annotations '[{"key": "defects", "value": ["grammatical", "spelling", "ambiguity"]}]'

Add a Numeric Score

orq traces create <trace_id> <span_id> \
  --annotations '[{"key": "confidence_score", "value": 0.95}]' \
  --metadata '{"identityId": "user-123"}'

Add a Text Correction

orq traces create <trace_id> <span_id> \
  --annotations '[{"key": "correction", "value": "The correct answer should emphasize scalability and fault tolerance."}]'

Batch Add Multiple Annotations

orq traces create <trace_id> <span_id> \
  --annotations '[{"key": "rating", "value": "good"}, {"key": "confidence_score", "value": 0.92}, {"key": "categories", "value": ["helpful", "accurate", "concise"]}]'

Remove Annotations

--keys takes a comma-separated list, not a JSON array like the API.

orq traces delete <trace_id> <span_id> \
  --keys rating,defects

Batch limits: up to 10 annotations per create call, up to 10 keys per delete call. String values are capped at 200 characters.

See install and setup to get started with the CLI. Run orq traces create --help or orq traces delete --help for the full flag reference.

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.

Experiment review screen showing Response 1 of 20 for product-orchestrator-A, a left panel with Inputs, Expected, and Metrics, a center panel with the System instructions, User input, and Assistant output including function calls, and a right panel with an Annotations comment field and good/bad rating above an Evaluators section listing a json_check evaluator marked No. — The Annotations panel in the experiment review screen, with annotations shown above the Evaluator scores.

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

Overview

Analytics & Monitoring

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