Feedback and scores

Feedback is a user judgement on one stored assistant message. A score is a named numeric, boolean, or categorical value on a message, thread, or run. Assistant Cloud records who authored each value, so feedback from an end user, a dashboard user, an API integration, and an evaluator can be distinguished.

Message feedback

When an assistant-ui runtime has cloud set, the thumbs in its message components submit positive or negative feedback for the stored message. The feedback adapter resolves the cloud thread and message ids before it submits the request. You can submit the same feedback yourself through the client:

await cloud.threads.messages.feedback(threadId, messageId, {
  type: "positive",
});

Feedback is a boolean score named feedback. A positive rating stores 1 and a negative rating stores 0. There is one feedback score for each user and message, so submitting feedback again updates that score and can flip its value.

The client sends the following request. Both path ids accept 1 to 255 characters, and the strict body requires type to be "positive" or "negative".

POST /v1/threads/{thread_id}/messages/{message_id}/feedback
Content-Type: application/json

{ "type": "positive" }

When a feedback click is skipped

The runtime submits feedback without throwing into the interface. It warns and returns before making a request in these two cases.

If the request itself is rejected, the adapter logs [assistant-ui] Cloud feedback submission failed:.

Write a score

Use cloud.scores.create to attach a score from your application. The client sends POST /v1/scores.

const score = await cloud.scores.create({
  name: "answer_relevance",
  data_type: "numeric",
  value: 0.82,
  comment: "Evaluated after the response completed",
  run_id: runId,
});

The request body is strict. Unknown fields are refused.

Every score targets exactly one thing.

With no target, the request is refused with "a score must target a message, run, or thread". With an invalid combination, it is refused with "a score must target exactly one message, run, or thread".

Source, author, and replacement

The API does not accept a caller supplied source. It records the source and author from the writing path.

An API key can score any thread in its project. A JWT score write first checks that the user owns the thread. For every path, a write with the same target, name, and author replaces the earlier value and updates its timestamp. The dashboard's manual score procedure records human, uses the viewer as author, and upserts on the most specific target.

Read scores

The project read API is API key only. GET /v1/projects/scores returns scores newest first by created_at and id.

GET /v1/projects/scores?thread_id={thread_id}&name=answer_relevance&limit=50

curl "https://backend.assistant-api.com/v1/projects/scores?thread_id=thread_0qzof3jPoDwr7K3agyJN3D4U&name=answer_relevance&limit=50" \
  -H "Authorization: Bearer $ASSISTANT_API_KEY" \
  -H "Aui-User-Id: user_123" \
  -H "Aui-Workspace-Id: workspace_acme"

import os

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ASSISTANT_API_KEY']}",
    "Aui-User-Id": "user_123",
    "Aui-Workspace-Id": "workspace_acme",
}
limit = 50
after = None
while True:
    params = {"name": "answer_relevance", "limit": limit}
    if after:
        params["after"] = after
    response = requests.get(
        "https://backend.assistant-api.com/v1/projects/scores",
        headers=headers,
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    scores = response.json()["scores"]
    for score in scores:
        print(score)
    if len(scores) < limit:
        break
    after = scores[-1]["id"]

Each returned score includes its id, target ids, name, data type, numeric and string values, source, author id, comment, and timestamps. This route does not accept a source filter and does not return next_cursor.

The API key only MCP server exposes the same project through list_scores. Its result is { scores, next_cursor }.

Scores in the dashboard

The run page has a Scores section with Recorded and Sources, alongside run details, usage, attributes, and the trace waterfall. The thread page reads scores for its thread together with the conversation, turns, satisfaction, and interactions.

The Intelligence page includes Evaluator verdicts. It shows Not judged yet until the next analysis run for sections that do not have a judgement.

Troubleshooting