Python SDK
from tavily import TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = tavily_client.feedback(
request_id="8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
agent_score=1,
comment="The top results answered the question directly.",
used_ids=["a3f9c2-04"],
)
print(response)const { tavily } = require("@tavily/core");
const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
const response = await tvly.feedback({
requestId: "8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
agentScore: 1,
comment: "The top results answered the question directly.",
usedIds: ["a3f9c2-04"],
});
console.log(response);curl --request POST \
--url https://api.tavily.com/feedback \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
"session_id": "5874812a-2e9b-43ea-8978-6cc9225b587b",
"agent_score": 1,
"human_score": 1,
"extra_scores": [
{
"label": "freshness",
"value": 0.4
},
{
"label": "authority",
"value": 0.9
}
],
"comment": "Results were authoritative but several were more than a year old.",
"response_delivered": "Lionel Messi is an Argentine footballer born in 1987...",
"used_ids": [
"a3f9c2-04",
"a3f9c2-07"
],
"used_urls": [
"https://www.britannica.com/facts/Lionel-Messi"
],
"used_citations": [
"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability."
],
"urls_scores": [
{
"id": "a3f9c2-04",
"agent_score": 1,
"comment": "Directly answered the question."
},
{
"url": "https://example.com/stale-page",
"agent_score": -1,
"scores": [
{
"label": "freshness",
"value": 0.1
}
]
}
]
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tavily.com/feedback",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'request_id' => '8442d8d0-8b74-4fca-a89e-5b1b6dd33295',
'session_id' => '5874812a-2e9b-43ea-8978-6cc9225b587b',
'agent_score' => 1,
'human_score' => 1,
'extra_scores' => [
[
'label' => 'freshness',
'value' => 0.4
],
[
'label' => 'authority',
'value' => 0.9
]
],
'comment' => 'Results were authoritative but several were more than a year old.',
'response_delivered' => 'Lionel Messi is an Argentine footballer born in 1987...',
'used_ids' => [
'a3f9c2-04',
'a3f9c2-07'
],
'used_urls' => [
'https://www.britannica.com/facts/Lionel-Messi'
],
'used_citations' => [
'Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.'
],
'urls_scores' => [
[
'id' => 'a3f9c2-04',
'agent_score' => 1,
'comment' => 'Directly answered the question.'
],
[
'url' => 'https://example.com/stale-page',
'agent_score' => -1,
'scores' => [
[
'label' => 'freshness',
'value' => 0.1
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tavily.com/feedback"
payload := strings.NewReader("{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tavily.com/feedback")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tavily.com/feedback")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"feedback_id": "f1c0f0a5-0f9b-4a62-9e0e-1b6b2f0a6d31",
"response_time": 0.05
}{
"detail": {
"error": "Either session_id or request_id is required."
}
}{
"detail": {
"error": "Unauthorized: missing or invalid API key."
}
}{
"detail": {
"error": "Request body exceeds 262144 bytes."
}
}{
"detail": {
"error": "Validation error in request body."
}
}{
"detail": {
"error": "Error when processing feedback"
}
}Feedback
Feedback
Submit feedback on how relevant and useful Tavily’s results were for your task.
POST
/
feedback
Python SDK
from tavily import TavilyClient
tavily_client = TavilyClient(api_key="tvly-YOUR_API_KEY")
response = tavily_client.feedback(
request_id="8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
agent_score=1,
comment="The top results answered the question directly.",
used_ids=["a3f9c2-04"],
)
print(response)const { tavily } = require("@tavily/core");
const tvly = tavily({ apiKey: "tvly-YOUR_API_KEY" });
const response = await tvly.feedback({
requestId: "8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
agentScore: 1,
comment: "The top results answered the question directly.",
usedIds: ["a3f9c2-04"],
});
console.log(response);curl --request POST \
--url https://api.tavily.com/feedback \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"request_id": "8442d8d0-8b74-4fca-a89e-5b1b6dd33295",
"session_id": "5874812a-2e9b-43ea-8978-6cc9225b587b",
"agent_score": 1,
"human_score": 1,
"extra_scores": [
{
"label": "freshness",
"value": 0.4
},
{
"label": "authority",
"value": 0.9
}
],
"comment": "Results were authoritative but several were more than a year old.",
"response_delivered": "Lionel Messi is an Argentine footballer born in 1987...",
"used_ids": [
"a3f9c2-04",
"a3f9c2-07"
],
"used_urls": [
"https://www.britannica.com/facts/Lionel-Messi"
],
"used_citations": [
"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability."
],
"urls_scores": [
{
"id": "a3f9c2-04",
"agent_score": 1,
"comment": "Directly answered the question."
},
{
"url": "https://example.com/stale-page",
"agent_score": -1,
"scores": [
{
"label": "freshness",
"value": 0.1
}
]
}
]
}
'<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tavily.com/feedback",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'request_id' => '8442d8d0-8b74-4fca-a89e-5b1b6dd33295',
'session_id' => '5874812a-2e9b-43ea-8978-6cc9225b587b',
'agent_score' => 1,
'human_score' => 1,
'extra_scores' => [
[
'label' => 'freshness',
'value' => 0.4
],
[
'label' => 'authority',
'value' => 0.9
]
],
'comment' => 'Results were authoritative but several were more than a year old.',
'response_delivered' => 'Lionel Messi is an Argentine footballer born in 1987...',
'used_ids' => [
'a3f9c2-04',
'a3f9c2-07'
],
'used_urls' => [
'https://www.britannica.com/facts/Lionel-Messi'
],
'used_citations' => [
'Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.'
],
'urls_scores' => [
[
'id' => 'a3f9c2-04',
'agent_score' => 1,
'comment' => 'Directly answered the question.'
],
[
'url' => 'https://example.com/stale-page',
'agent_score' => -1,
'scores' => [
[
'label' => 'freshness',
'value' => 0.1
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.tavily.com/feedback"
payload := strings.NewReader("{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.tavily.com/feedback")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tavily.com/feedback")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"request_id\": \"8442d8d0-8b74-4fca-a89e-5b1b6dd33295\",\n \"session_id\": \"5874812a-2e9b-43ea-8978-6cc9225b587b\",\n \"agent_score\": 1,\n \"human_score\": 1,\n \"extra_scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.4\n },\n {\n \"label\": \"authority\",\n \"value\": 0.9\n }\n ],\n \"comment\": \"Results were authoritative but several were more than a year old.\",\n \"response_delivered\": \"Lionel Messi is an Argentine footballer born in 1987...\",\n \"used_ids\": [\n \"a3f9c2-04\",\n \"a3f9c2-07\"\n ],\n \"used_urls\": [\n \"https://www.britannica.com/facts/Lionel-Messi\"\n ],\n \"used_citations\": [\n \"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability.\"\n ],\n \"urls_scores\": [\n {\n \"id\": \"a3f9c2-04\",\n \"agent_score\": 1,\n \"comment\": \"Directly answered the question.\"\n },\n {\n \"url\": \"https://example.com/stale-page\",\n \"agent_score\": -1,\n \"scores\": [\n {\n \"label\": \"freshness\",\n \"value\": 0.1\n }\n ]\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"feedback_id": "f1c0f0a5-0f9b-4a62-9e0e-1b6b2f0a6d31",
"response_time": 0.05
}{
"detail": {
"error": "Either session_id or request_id is required."
}
}{
"detail": {
"error": "Unauthorized: missing or invalid API key."
}
}{
"detail": {
"error": "Request body exceeds 262144 bytes."
}
}{
"detail": {
"error": "Validation error in request body."
}
}{
"detail": {
"error": "Error when processing feedback"
}
}Beta. This endpoint is in beta: the request shape may still change, and it may be
temporarily unavailable during maintenance. Submit feedback on a best-effort basis —
send it asynchronously, treat a failure as non-fatal, and never block your agent on the
response.
Zero Data Retention
If your account or organization has Zero Data Retention enabled, the free-text and URL content you send here is not stored.Authorizations
Bearer authentication header in the form Bearer , where is your Tavily API key (e.g., Bearer tvly-YOUR_API_KEY).
Body
application/json
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.
Maximum string length:
200Example:
"8442d8d0-8b74-4fca-a89e-5b1b6dd33295"
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.
Maximum string length:
200Example:
"5874812a-2e9b-43ea-8978-6cc9225b587b"
Overall score for how relevant and useful the results were for your task.
Example:
1
Feedback from your end user, if you collect it.
Example:
1
Additional labeled scores for the dimensions you care about.
Maximum array length:
50Show child attributes
Show child attributes
Example:
[
{ "label": "freshness", "value": 0.4 },
{ "label": "authority", "value": 0.9 }
]
Free-text explanation of the feedback.
Maximum string length:
10000Example:
"Results were authoritative but several were more than a year old."
The final answer you produced using the results.
Maximum string length:
50000Example:
"Lionel Messi is an Argentine footballer born in 1987..."
IDs of the results you actually used in your answer. Alternative to used_urls.
Maximum array length:
100Maximum string length:
200Example:
["a3f9c2-04", "a3f9c2-07"]
URLs of the results you actually used in your answer. Alternative to used_ids.
Maximum array length:
100Maximum string length:
2000Example:
[
"https://www.britannica.com/facts/Lionel-Messi"
]
The specific content snippets you quoted from the results.
Maximum array length:
100Maximum string length:
2000Example:
[
"Messi is known for his exceptional dribbling skills, vision, and goal-scoring ability."
]
Per-result feedback. Identify each result by id or url.
Maximum array length:
100Show child attributes
Show child attributes
Example:
[
{
"id": "a3f9c2-04",
"agent_score": 1,
"comment": "Directly answered the question."
},
{
"url": "https://example.com/stale-page",
"agent_score": -1,
"scores": [{ "label": "freshness", "value": 0.1 }]
}
]