# Annotations Overview
Annotations allow you to add human or automated feedback to traces, spans, documents, and sessions. Annotations are essential for evaluation, quality assessment, and building training datasets.
## Annotation Types
Phoenix supports four types of annotations:
| Type | Target | Purpose | Example Use Case |
| ----------------------- | -------------------------------- | ---------------------------------------- | -------------------------------- |
| **Span Annotation** | Individual span | Feedback on a specific operation | "This LLM response was accurate" |
| **Document Annotation** | Document within a RETRIEVER span | Feedback on retrieved document relevance | "This document was not helpful" |
| **Trace Annotation** | Entire trace | Feedback on end-to-end interaction | "User was satisfied with result" |
| **Session Annotation** | User session | Feedback on multi-turn conversation | "Session ended successfully" |
## Annotation Fields
Every annotation has these fields:
### Required Fields
| Field | Type | Description |
| --------- | ------ | ----------------------------------------------------------------------------- |
| Entity ID | String | ID of the target entity (span_id, trace_id, session_id, or document_position) |
| `name` | String | Annotation name/label (e.g., "quality", "relevance", "helpfulness") |
### Result Fields (At Least One Required)
| Field | Type | Description |
| ------------- | ----------------- | ----------------------------------------------------------------- |
| `label` | String (optional) | Categorical value (e.g., "good", "bad", "relevant", "irrelevant") |
| `score` | Float (optional) | Numeric value (typically 0-1, but can be any range) |
| `explanation` | String (optional) | Free-text explanation of the annotation |
**At least one** of `label`, `score`, or `explanation` must be provided.
### Optional Fields
| Field | Type | Description |
| ---------------- | ------ | --------------------------------------------------------------------------------------- |
| `annotator_kind` | String | Who created this annotation: "HUMAN", "LLM", or "CODE" (default: "HUMAN") |
| `identifier` | String | Unique identifier for upsert behavior (updates existing if same name+entity+identifier) |
| `metadata` | Object | Custom metadata as key-value pairs |
## Annotator Kinds
| Kind | Description | Example |
| ------- | ------------------------------ | --------------------------------- |
| `HUMAN` | Manual feedback from a person | User ratings, expert labels |
| `LLM` | Automated feedback from an LLM | GPT-4 evaluating response quality |
| `CODE` | Automated feedback from code | Rule-based checks, heuristics |
## Examples
**Quality Assessment:**
- `quality` - Overall quality (label: good/fair/poor, score: 0-1)
- `correctness` - Factual accuracy (label: correct/incorrect, score: 0-1)
- `helpfulness` - User satisfaction (label: helpful/not_helpful, score: 0-1)
**RAG-Specific:**
- `relevance` - Document relevance to query (label: relevant/irrelevant, score: 0-1)
- `faithfulness` - Answer grounded in context (label: faithful/unfaithful, score: 0-1)
**Safety:**
- `toxicity` - Contains harmful content (score: 0-1)
- `pii_detected` - Contains personally identifiable information (label: yes/no)
