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

# User Feedback

> Capture user ratings, comments, and implicit signals on your traces

This guide shows you how to capture user feedback (thumbs up/down, ratings, comments) and associate it with your traces.

<Note>
  **User feedback is evaluation data.** This page covers the *how* - capturing feedback via trace enrichment. To understand *what to do* with this data (building datasets, comparing against automated evals, running experiments), see [Experiments](/v2/evaluation/introduction).
</Note>

## Quick Start

Use `enrich_session()` to add feedback to the entire trace, or `enrich_span()` to add feedback to a specific operation.

### On the Session

Add feedback that applies to the entire user interaction:

```python theme={null}
from honeyhive import HoneyHiveTracer
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

# ... your application logic ...

# Capture feedback on the entire trace
tracer.enrich_session(feedback={
    "rating": True,  # boolean: thumbs up/down
    "comment": "The response was helpful",
    "ground_truth": "Expected answer here",  # optional
})
```

### On a Span

Add feedback to a specific function or operation:

```python theme={null}
from honeyhive import HoneyHiveTracer, trace
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

@trace
def generate_response(query: str, user_id: str):
    # ... your function logic ...
    
    # Capture feedback on this specific span
    tracer.enrich_span(feedback={
        "rating": True,
        "comment": "The model hallucinated the capital",
        "user_id": user_id,
        "ground_truth": "The capital of New York is Albany",
    })
    
    return response
```

<Tip>
  **Distributed systems:** When feedback is submitted from a different service than where the trace originated, pass the `session_id` to link them. See [distributed tracing](/v2/tracing/distributed-tracing) for details.
</Tip>

***

## Concepts

### What is User Feedback?

Any feedback that the end-user provides about their experience. Two types:

1. **Explicit Feedback:** User-provided ratings in your app - thumbs up/down, star ratings (1-5), written comments
2. **Implicit Feedback:** User actions that signal intent - clicking "Copy", "Regenerate", editing the response

<Note>
  **User Feedback vs Human Evaluator:** The `feedback` field tracks feedback from **end-users**. Feedback from domain experts or internal team members should use the `metrics` field instead.
</Note>

### Feedback Schema

The `feedback` object accepts any structure. Common patterns:

```json theme={null}
{
  "rating": true,                    // boolean: thumbs up/down
  "score": 4,                        // number: star rating
  "comment": "Great response",       // string: user comment
  "ground_truth": "Expected answer", // string: for comparison (reserved field)
  "actions": {
    "copied": true,
    "regenerated": false
  }
}
```

### Data Types

| Type    | Available Measurements                    | Use Case             |
| ------- | ----------------------------------------- | -------------------- |
| Boolean | True/False percentage                     | Thumbs up/down       |
| Number  | Sum, Avg, Median, Min, Max, P95, P98, P99 | Star ratings, scores |
| String  | Filters and group by                      | Categories, comments |

### Nested Data

You can drill down into nested fields when charting:

```json theme={null}
{
  "rating": 5,
  "step1": { "retry": true },
  "edits": [{ "value": "New York" }]
}
```

Access as `feedback.step1.retry` (boolean) or `feedback.edits.0.value` (string).

<Note>
  **Nesting limits:** Max 5 levels of nested objects, max 2 levels of nested arrays.
</Note>

### Reserved Fields

| Field          | Purpose                                                       |
| -------------- | ------------------------------------------------------------- |
| `ground_truth` | Expected output for comparison. Rendered specially in the UI. |

***

## Learn More

<CardGroup cols={2}>
  <Card title="Analyzing feedback" icon="chart-line" href="/v2/monitoring/charts">
    Chart and analyze user feedback in dashboards
  </Card>

  <Card title="Enriching Traces" icon="sparkles" href="/v2/tracing/enrich-traces">
    Full guide to trace enrichment
  </Card>
</CardGroup>

## SDK Reference

* [Python SDK Reference](https://honeyhiveai.github.io/python-sdk/) - `enrich_session()`, `enrich_span()`