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

# Collect feedback on agent messages

> Submit thumbs up or thumbs down feedback on Agent Studio chat messages with the feedback endpoint.

The Agent Studio feedback endpoint lets you collect binary (thumbs up or thumbs down) feedback on agent messages.
Use this to measure response quality, identify problem areas, and improve your agent over time.

## Before you begin

* You need an Algolia application with the Agent Studio feature enabled.
* You need an API key with the `search` ACL.
* You need the `messageId` (prefixed `alg_msg_`) from a prior chat response.
  For more information about message IDs, see [Conversations](/doc/guides/algolia-ai/agent-studio/how-to/conversations).

## Submit feedback

<Steps>
  <Step title="Send a chat message and extract the message ID">
    Send a completion request to your agent.
    The response contains a message ID (prefixed `alg_msg_`) that identifies the assistant's reply.
    Store this ID so you can attach feedback to it later.

    ```sh Command line icon=square-terminal theme={"system"}
    curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/agents/$AGENT_ID/completions?stream=false&compatibilityMode=ai-sdk-5" \
      -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
      -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "alg_cnv_abc123",
        "messages": [
          {
            "id": "alg_msg_001",
            "role": "user",
            "content": "How do I reset my password?"
          }
        ]
      }'
    ```
  </Step>

  <Step title="Submit feedback on the message">
    Send a `POST` request to the feedback endpoint with the `messageId`, `agentId`, and a `vote` value.
    Use `1` for thumbs up or `0` for thumbs down.

    <CodeGroup>
      ```sh Command line icon=square-terminal theme={"system"}
      curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/feedback" \
        -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
        -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "messageId": "alg_msg_xyz789",
          "agentId": "$AGENT_ID",
          "vote": 1
        }'
      ```

      ```python Python theme={"system"}
      import requests

      app_id = "ALGOLIA_APPLICATION_ID"
      api_key = "ALGOLIA_SEARCH_API_KEY"
      agent_id = "AGENT_ID"

      response = requests.post(
          f"https://{app_id}.algolia.net/agent-studio/1/feedback",
          headers={
              "X-Algolia-Application-Id": app_id,
              "X-Algolia-API-Key": api_key,
              "Content-Type": "application/json",
          },
          json={
              "messageId": "alg_msg_xyz789",
              "agentId": agent_id,
              "vote": 1,
          },
      )
      print(response.status_code, response.json())
      ```

      ```js JavaScript theme={"system"}
      const appID = "ALGOLIA_APPLICATION_ID";
      const apiKey = "ALGOLIA_SEARCH_API_KEY";
      const agentId = "AGENT_ID";

      const response = await fetch(
        `https://${appID}.algolia.net/agent-studio/1/feedback`,
        {
          method: "POST",
          headers: {
            "X-Algolia-Application-Id": appID,
            "X-Algolia-API-Key": apiKey,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            messageId: "alg_msg_xyz789",
            agentId,
            vote: 1,
          }),
        }
      );
      const data = await response.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Add optional tags and notes

You can include `tags` and `notes` to capture more context about why a user gave positive or negative feedback.

<CodeGroup>
  ```sh Command line icon=square-terminal theme={"system"}
  curl -X POST "https://$ALGOLIA_APPLICATION_ID.algolia.net/agent-studio/1/feedback" \
    -H "X-Algolia-Application-Id: $ALGOLIA_APPLICATION_ID" \
    -H "X-Algolia-API-Key: $ALGOLIA_SEARCH_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "messageId": "alg_msg_xyz789",
      "agentId": "$AGENT_ID",
      "vote": 0,
      "tags": ["inaccurate", "incomplete"],
      "notes": "The response did not include the return policy link."
    }'
  ```

  ```js JavaScript theme={"system"}
  const appID = "ALGOLIA_APPLICATION_ID";
  const apiKey = "ALGOLIA_SEARCH_API_KEY";
  const agentId = "AGENT_ID";

  const response = await fetch(
    `https://${appID}.algolia.net/agent-studio/1/feedback`,
    {
      method: "POST",
      headers: {
        "X-Algolia-Application-Id": appID,
        "X-Algolia-API-Key": apiKey,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        messageId: "alg_msg_xyz789",
        agentId,
        vote: 0,
        tags: ["inaccurate", "incomplete"],
        notes: "The response did not include the return policy link.",
      }),
    }
  );
  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Endpoint reference

For full details on the `POST /agent-studio/1/feedback` endpoint, see the [Agent Studio API reference](/doc/rest-api/agent-studio).

## Constraints and error handling

* **One feedback per message**: each application can submit one vote per message.
  If you send a second feedback request for the same message, the endpoint returns a `400` error.
* **Message scope**: the `messageId` must belong to a conversation under the authenticated app. You can't submit feedback for messages from other applications.
* **Authentication**: your API key must have the `search` ACL, and your application must have the Agent Studio feature enabled.
  If either is missing, the endpoint returns a `403` error.

<Tip>
  Design your UI to disable the feedback button after a user votes,
  preventing duplicate submission attempts.
</Tip>

## See also

* [Agent Studio API overview](/doc/rest-api/agent-studio)
* [Conversations](/doc/guides/algolia-ai/agent-studio/how-to/conversations)
* [Analytics](/doc/guides/algolia-ai/agent-studio/how-to/analytics)