result = client.query(
database="acme_corp",
query="What is our refund policy?",
)
client.feedback.submit(
request_id=result.meta.request_id,
feedback="Returned the 2023 policy - the current one is in the Q3 handbook.",
rating="negative",
source="agent",
database="acme_corp",
metadata={"agent": "support-bot", "conversation": "c-8891"},
)
const result = await client.query({
database: "acme_corp",
query: "What is our refund policy?",
});
// Response fields are optional in the TypeScript types.
const requestId = result.meta?.requestId;
if (!requestId) throw new Error("query response has no request_id");
await client.feedback.submit({
requestId,
feedback: "Returned the 2023 policy - the current one is in the Q3 handbook.",
rating: "negative",
source: "agent",
database: "acme_corp",
metadata: { agent: "support-bot", conversation: "c-8891" },
});
curl -X POST 'https://api.hydradb.com/feedback' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"feedback": "Returned the 2023 policy - the current one is in the Q3 handbook.",
"rating": "negative",
"source": "agent",
"database": "acme_corp",
"metadata": { "agent": "support-bot", "conversation": "c-8891" }
}'
{
"success": true,
"data": {
"feedback_id": "0f5c2e18-7b41-4a92-9d0c-5e1f7a3b6c84",
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"recorded": true,
"created_at": "2026-08-10T09:11:55.593287923Z",
"message": "Feedback recorded. Thank you - it is used to validate and improve retrieval quality."
},
"error": null,
"meta": {
"request_id": "84467490-be20-4640-8693-f604a03227cc",
"api_version": "2.0.1",
"latency_ms": 102.1
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_INPUT",
"message": "request_id \"abc-123\" is not a valid request id: it must be the UUID returned in response.meta.request_id (or the X-Request-ID header) of the query you are giving feedback on"
},
"meta": {
"request_id": "b4340e7c-0082-4c20-829d-5fd53f81a54d",
"api_version": "2.0.1"
}
}
{
"success": false,
"data": null,
"error": {
"code": "RATE_LIMITED",
"message": "feedback per_min rate limit exceeded (limit: 100). Please retry in 37 second(s)."
},
"meta": {
"request_id": "7c1e9a44-0b2d-4f88-a3e1-9d6c2b5f0e73",
"api_version": "2.0.1"
}
}
Query
Submit Feedback
Tell HydraDB how a query performed, so retrieval quality improves.
POST
/
feedback
result = client.query(
database="acme_corp",
query="What is our refund policy?",
)
client.feedback.submit(
request_id=result.meta.request_id,
feedback="Returned the 2023 policy - the current one is in the Q3 handbook.",
rating="negative",
source="agent",
database="acme_corp",
metadata={"agent": "support-bot", "conversation": "c-8891"},
)
const result = await client.query({
database: "acme_corp",
query: "What is our refund policy?",
});
// Response fields are optional in the TypeScript types.
const requestId = result.meta?.requestId;
if (!requestId) throw new Error("query response has no request_id");
await client.feedback.submit({
requestId,
feedback: "Returned the 2023 policy - the current one is in the Q3 handbook.",
rating: "negative",
source: "agent",
database: "acme_corp",
metadata: { agent: "support-bot", conversation: "c-8891" },
});
curl -X POST 'https://api.hydradb.com/feedback' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"feedback": "Returned the 2023 policy - the current one is in the Q3 handbook.",
"rating": "negative",
"source": "agent",
"database": "acme_corp",
"metadata": { "agent": "support-bot", "conversation": "c-8891" }
}'
{
"success": true,
"data": {
"feedback_id": "0f5c2e18-7b41-4a92-9d0c-5e1f7a3b6c84",
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"recorded": true,
"created_at": "2026-08-10T09:11:55.593287923Z",
"message": "Feedback recorded. Thank you - it is used to validate and improve retrieval quality."
},
"error": null,
"meta": {
"request_id": "84467490-be20-4640-8693-f604a03227cc",
"api_version": "2.0.1",
"latency_ms": 102.1
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_INPUT",
"message": "request_id \"abc-123\" is not a valid request id: it must be the UUID returned in response.meta.request_id (or the X-Request-ID header) of the query you are giving feedback on"
},
"meta": {
"request_id": "b4340e7c-0082-4c20-829d-5fd53f81a54d",
"api_version": "2.0.1"
}
}
{
"success": false,
"data": null,
"error": {
"code": "RATE_LIMITED",
"message": "feedback per_min rate limit exceeded (limit: 100). Please retry in 37 second(s)."
},
"meta": {
"request_id": "7c1e9a44-0b2d-4f88-a3e1-9d6c2b5f0e73",
"api_version": "2.0.1"
}
}
Report back on a query that already ran: what was missing, what was wrong, or that it was exactly right. Feedback feeds retrieval-quality work; it does not change the result of the query it refers to. A successful submission returns
Send
This example skips feedback that exceeds the rate limit and continues the evaluation. Other errors stop the run so invalid credentials or malformed requests are visible.
Each submission is its own row, so the worst case of retrying after a
201.
result = client.query(
database="acme_corp",
query="What is our refund policy?",
)
client.feedback.submit(
request_id=result.meta.request_id,
feedback="Returned the 2023 policy - the current one is in the Q3 handbook.",
rating="negative",
source="agent",
database="acme_corp",
metadata={"agent": "support-bot", "conversation": "c-8891"},
)
const result = await client.query({
database: "acme_corp",
query: "What is our refund policy?",
});
// Response fields are optional in the TypeScript types.
const requestId = result.meta?.requestId;
if (!requestId) throw new Error("query response has no request_id");
await client.feedback.submit({
requestId,
feedback: "Returned the 2023 policy - the current one is in the Q3 handbook.",
rating: "negative",
source: "agent",
database: "acme_corp",
metadata: { agent: "support-bot", conversation: "c-8891" },
});
curl -X POST 'https://api.hydradb.com/feedback' \
-H "Authorization: Bearer <your_api_key>" \
-H "API-Version: 2" \
-H "Content-Type: application/json" \
-d '{
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"feedback": "Returned the 2023 policy - the current one is in the Q3 handbook.",
"rating": "negative",
"source": "agent",
"database": "acme_corp",
"metadata": { "agent": "support-bot", "conversation": "c-8891" }
}'
{
"success": true,
"data": {
"feedback_id": "0f5c2e18-7b41-4a92-9d0c-5e1f7a3b6c84",
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"recorded": true,
"created_at": "2026-08-10T09:11:55.593287923Z",
"message": "Feedback recorded. Thank you - it is used to validate and improve retrieval quality."
},
"error": null,
"meta": {
"request_id": "84467490-be20-4640-8693-f604a03227cc",
"api_version": "2.0.1",
"latency_ms": 102.1
}
}
{
"success": false,
"data": null,
"error": {
"code": "INVALID_INPUT",
"message": "request_id \"abc-123\" is not a valid request id: it must be the UUID returned in response.meta.request_id (or the X-Request-ID header) of the query you are giving feedback on"
},
"meta": {
"request_id": "b4340e7c-0082-4c20-829d-5fd53f81a54d",
"api_version": "2.0.1"
}
}
{
"success": false,
"data": null,
"error": {
"code": "RATE_LIMITED",
"message": "feedback per_min rate limit exceeded (limit: 100). Please retry in 37 second(s)."
},
"meta": {
"request_id": "7c1e9a44-0b2d-4f88-a3e1-9d6c2b5f0e73",
"api_version": "2.0.1"
}
}
Link feedback to a query
Every HydraDB response carries arequest_id in meta, and the same value in the X-Request-ID header. Send that ID back so HydraDB can match your feedback to the exact query it is about: the text queried, what came back, and how long it took.
Query response
{
"success": true,
"data": { "chunks": [ /* ... */ ] },
"error": null,
"meta": {
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"api_version": "2.0.1",
"latency_ms": 412.8
}
}
request_id back exactly as you received it. It must be the UUID from meta.request_id (or the X-Request-ID header). Any other value is rejected with 400.
Submit feedback for queries that returned. If the query itself failed, handle the error instead: there is no retrieval to judge, and the fix is in the request, not in the index.
Fields
| Name | Description |
|---|---|
The request_id from the target query’s meta. Must be a UUID. | |
What was right or wrong, in your own words. Up to 8000 characters. Required unless you send ground_truth; every submission needs at least one of the two. | |
| What you already know the right answer to be. See Ground truth. | |
| The response you expected. Up to 8000 characters. | |
| IDs of the sources that actually contain the answer. Up to 100, each up to 256 characters. | |
positive, negative, or neutral. Optional. Leaving it out is not the same as neutral; it records that you sent a comment without a rating. | |
Who is submitting: user (default) or agent. | |
| Optional. Scopes the feedback to a database. Must be one your API key can reach. | |
Optional. Requires database: a collection is scoped to a database, so sending it alone returns 400. | |
| Optional string-to-string map for your own context (agent name, conversation ID, eval run). Up to 20 entries; keys up to 64 characters, values up to 512. |
Ground truth
If you already know the right answer (you are running an evaluation set, or you know which document the user needed), send it. It is a much stronger signal than a comment, because HydraDB can score it without a human reading it."ground_truth": {
"answer": "Refunds are processed within 14 days.",
"source_ids": ["policy_2024", "handbook_q3"]
}
source_ids is the field that grades retrieval: it tells HydraDB whether the query surfaced those sources, and where they ranked.
Send answer or source_ids on its own, or both together. If ground_truth is your only signal, at least one of the two has to carry something; values that are empty or all whitespace are treated as not sent. Duplicate source_ids are collapsed and blank entries dropped, so you do not need to de-duplicate or filter your answer key first. A list that still has one real ID in it is scored on that ID.
Evaluation run
from hydra_db.core.api_error import ApiError
for case in eval_set:
result = client.query(database="acme_corp", query=case.question)
try:
client.feedback.submit(
request_id=result.meta.request_id,
source="agent",
ground_truth={
"answer": case.expected_answer,
"source_ids": case.expected_sources,
},
)
except ApiError as error:
if error.status_code != 429:
raise
Behavior notes
Submitting more than once: Each submission is stored separately: a second comment about the same query does not replace the first. Send several as your understanding of a bad result develops, and submit feedback from more than one user on the same query. Rate limit: 100 submissions per minute per organization. Over that, you get429 with a Retry-After header and a message naming the seconds to wait. It is safe to retry after waiting.
Errors
| Status | When |
|---|---|
400 | request_id missing or not a UUID; no usable signal (feedback blank or absent and ground_truth absent, empty, or blank); feedback too long; unknown rating/source; collection without database; or any other limit in Fields exceeded |
401 | Missing or invalid API key |
404 | database does not exist or is not reachable by this key |
429 | Over the rate limit; see Retry-After |
500 | Feedback could not be recorded. Retrying is safe |
500 is a duplicate report.
Related resources
- Before this: Query: run the query and read
meta.request_id - Related: Error Responses: the error envelope and retry rules
Authorizations
Send your API key as Authorization: Bearer <your_api_key>.
Body
application/json
Send feedback, ground_truth, or both. A request with neither is rejected with 400.
The request_id from meta of the query this feedback is about. Required: it links the feedback to the query that ran.
Example:
"9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
Optional collection scope for this feedback. A collection is scoped to a database, so database must be sent alongside it; sending collection on its own is rejected.
Minimum string length:
1Example:
"team_docs"
Owning database. Formerly tenant_id; the tenant_id alias is still accepted (deprecated).
Minimum string length:
1Example:
"acme_corp"
Free-text comment describing what was right or wrong about the results. Required unless ground_truth is supplied.
Maximum string length:
8000The known right answer: an expected answer, the source_ids that contain it, or both. When sent, feedback becomes optional.
Show child attributes
Show child attributes
Example:
{
"source_ids": ["HydraDoc1234", "HydraDoc4567"]
}
Free-form key-value context stored alongside the feedback (e.g. agent name, conversation or eval-run ID).
Show child attributes
Show child attributes
Example:
{
"agent": "support-bot",
"conversation": "c-8891"
}
Optional overall judgement: positive, negative, or neutral. Omit to send a comment with no rating.
Available options:
positive, negative, neutral Who is submitting: user (default) or agent.
Available options:
user, agent Deprecated: use collection.
Minimum string length:
1Example:
"sub_tenant_4567"
Deprecated: use database.
Minimum string length:
1Example:
"tenant_1234"
Response
Created
Show child attributes
Show child attributes
Example:
{
"created_at": "2026-07-02T10:00:00Z",
"message": "Success",
"recorded": true,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d"
}
Error details on failure, or null on success.
Show child attributes
Show child attributes
Example:
null
Show child attributes
Show child attributes
Example:
{
"collection": "team_docs",
"database": "acme_corp",
"latency_ms": 12.3,
"request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
"source_type": "file",
"sub_tenant_id": "sub_tenant_4567",
"tenant_id": "tenant_1234",
"warnings": [
{
"code": "acl_ignored_by_connector_enforcement",
"message": "This connector enforces ACL, so the request's acl was ignored."
}
]
}
Whether the request succeeded.
Example:
true
Was this page helpful?