Evaluation
Feedback and scores
Where scores come from (people, evaluators, end users, your code), the 0 to 1 scale, and how to send your users' ratings with POST /v1/feedback.
Reference3 min readUpdated 31 October 2026
Every score on a reply is kept as feedback with a key (what it measures, such as correctness or user_score), a score from 0 to 1, an optional value and comment, and its source. Scores show as chips on each reply in Conversations, in the trace's Feedback tab, and on the agent's Overview.
Sources
| Source | Shown as | Where it comes from |
|---|---|---|
| A person | A person | Score under a reply in Conversations, Add a score on a trace, and review queues |
| An evaluator | An evaluator | Live scoring and Run evaluator on a reply |
| Your end user | A user | POST /v1/feedback with the key user_score |
| Your code | Your API | POST /v1/feedback with any other key |
| Thumbs | Thumbs | Thumbs on replies in the Playground and the widget |
The 0 to 1 scale
| Given as | Stored as |
|---|---|
| Thumbs up, a pass | 1 |
| Thumbs down, a fail | 0 |
| 4 on a 1 to 5 rating | 0.75, with the value "4/5" |
| A label | The score you gave the label, with the label as the value |
The same key from the same source on the same reply replaces the earlier score, so a changed vote updates instead of adding up. A score on a whole conversation adds a new one each time.
Send feedback from your app
POST /v1/feedback records how a reply did, with your secret key: your end user's thumbs, or your own code's checks. Use the trace_id from the reply's meta or done event.
POST /v1/feedbackContent-Type: application/jsonX-Api-Key: sk-so-…{"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736", "score": -1, "comment": "Wrong opening hours"}| Field | Meaning | |
|---|---|---|
trace_id, message_id or conversation_id | At least one | The reply (its trace id or message id), or a whole conversation. It must be your account's; when you send two, they must agree |
key | Optional, default user_score | What the score measures: lowercase letters, digits and underscores, starting with a letter, such as resolved or csat. user_score is your end user's rating; any other key is your own code's |
score | 0 to 1 | Thumbs as 1 / 0, or 1 / -1 (-1 is stored as 0). A 1 to 5 rating: send (n − 1) / 4 with "value": "4/5". Can be left out when you send a value or a comment |
value | Optional | A label, up to 200 characters, such as "refund" or "4/5" |
comment | Optional | Up to 4,000 characters |
{ "message_id": "…", "key": "csat", "score": 0.75, "value": "4/5", "comment": "Quick, but didn't mention the returns window"}The answer is {"id": "…"}. A reply is saved a moment after its stream ends; feedback sent straight after the done event still finds it.
curl https://api.sentientone.ai/v1/feedback \ -H "X-Api-Key: $SENTIENTONE_API_KEY" -H "Content-Type: application/json" \ -d '{"trace_id": "TRACE_ID_FROM_THE_DONE_EVENT", "score": 1}'| Answer | Code | Why |
|---|---|---|
| 400 | MISSING_TARGET | No trace_id, message_id or conversation_id |
| 400 | INVALID_TRACE_ID | The trace id isn't 32 hex characters |
| 400 | INVALID_KEY | The key isn't lowercase letters, digits and underscores starting with a letter |
| 400 | INVALID_SCORE, MISSING_SCORE | The score isn't 0 to 1 (or -1), or there's no score, value or comment |
| 401 | MISSING_API_KEY, INVALID_API_KEY | The secret key is missing or wrong |
| 404 | MESSAGE_NOT_FOUND, TRACE_NOT_FOUND, CONVERSATION_NOT_FOUND | It isn't your account's, or the ids don't agree |
| 429 | RATE_LIMIT_EXCEEDED | Over 120 a minute for your account; wait for Retry-After |
Feedback is free: it costs no credits. Error bodies have the usual code, message and request_id; see Errors and error codes.
Still stuck?
Email us with what you tried and any request id. A person replies.