---
title: "Submit feedback on a search request or session"
method: POST
path: "/feedback"
---

# Submit feedback on a search request or session

`POST /feedback`

## Request

- Base URL: `https://api.tavily.com`
- URL: `https://api.tavily.com/feedback`
- Auth: HTTP bearer

Submit feedback on how relevant and useful Tavily's results were for your task.

## Request body

- object
  - `request_id` string: The search request to give feedback on, as returned in the `request_id` field of the search response. When provided, the feedback applies to this request.
  - `session_id` string: The session to give feedback on — the value you sent in the `X-Session-Id` header. When `request_id` is omitted, the feedback applies to the whole session. Optional if `request_id` is provided.
  - `agent_score` union: Overall score for how relevant and useful the results were for your task.
    - number
    - string
  - `human_score` union: Feedback from your end user, if you collect it.
    - number
    - string
  - `extra_scores` object[]: Additional labeled scores for the dimensions you care about.
    - `label` string, required: Name of the dimension being scored.
    - `value` union, required: A numeric score, or a short string label (max 64 characters).
      - number
      - string
  - `comment` string: Free-text explanation of the feedback.
  - `response_delivered` string: The final answer you produced using the results.
  - `used_ids` string[]: IDs of the results you actually used in your answer. Alternative to `used_urls`.
  - `used_urls` string[]: URLs of the results you actually used in your answer. Alternative to `used_ids`.
  - `used_citations` string[]: The specific content snippets you quoted from the results.
  - `urls_scores` object[]: Per-result feedback. Identify each result by `id` or `url`.
    - `id` string: The `id` of the result, as returned in the search response.
    - `url` string: The URL of the result. Use instead of `id` when you don't have the result ID.
    - `agent_score` union: Score for this specific result.
      - number
      - string
    - `scores` object[]: Additional labeled scores for this result.
      - `label` string, required: Name of the dimension being scored.
      - `value` union, required: A numeric score, or a short string label (max 64 characters).
        - number
        - string
    - `comment` string: Free-text explanation of the feedback on this result.

## Response `200`

Feedback accepted

- object
  - `success` boolean: Whether the feedback was accepted.
  - `feedback_id` string: Unique identifier of this feedback submission.
  - `response_time` number: Response time of this feedback request in seconds.

## Other responses

- `400`: Bad Request — neither `session_id` nor `request_id` was provided, or a `urls_scores` item is missing both `id` and `url`.
- `401`: Unauthorized - Your API key is wrong or missing.
- `413`: Payload Too Large — the request body exceeds 256 KB.
- `422`: Unprocessable Entity — a field failed validation (e.g. a list or string exceeds its maximum length).
- `500`: Internal Server Error

## Changes

- **2026-11-03** `c97103b0bfa3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/changes/feedback/post.md)

---

[API](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api.md) - [All operations](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/llms.txt) - [OpenAPI document](https://skmtc.dev/tavily/apis/tavily-search-and-extract-api/revisions/c97103b0bfa3?raw)