firecrawl_search_feedback
Improve search quality and earn a credit refund by submitting structured feedback on results, including rating, valuable sources, and missing content.
Instructions
Send structured feedback on a previous firecrawl_search result. Call this immediately after a search where you used the results so we can improve search quality and refund 1 credit (search costs 2).
Pass the searchId returned by firecrawl_search (the id field on the response) and tell us:
rating — overall result quality:
good,partial, orbad.valuableSources — which result URLs were actually useful, and a short reason why.
missingContent — the most important field. An ARRAY of specific pieces of content you expected to find but didn't. One entry per missing piece, each with a short
topicand an optional longerdescription. Examples:{"topic":"enterprise pricing","description":"no pricing tier table for the Enterprise plan was returned"},{"topic":"API rate limits"},{"topic":"comparison vs competitors"}. Be specific — these aggregate across teams and tell us what to index next. Do not pack multiple topics into one entry.querySuggestions — how the query or response shape could be improved (e.g. "would have liked official docs first", "should boost github.com").
Substantive-feedback requirement (zero-effort feedback is rejected with HTTP 400):
good— must include at least onevaluableSourcesentrypartial— must includevaluableSourcesor at least onemissingContententrybad— must include at least onemissingContententry orquerySuggestions
Time window: Feedback must be submitted within ~2 minutes of the search. Beyond that, the call returns HTTP 409 with feedbackErrorCode: "FEEDBACK_WINDOW_EXPIRED" — do not retry, just move on. Same goes for any 4xx response: do not retry-loop.
Behaviors:
Idempotent per
searchId. Re-submitting for the same id returnsalreadySubmitted: truewithcreditsRefunded: 0.Refund only applies to billable searches; preview teams are blocked.
Failed searches cannot receive feedback (the search itself already returned an error you can act on).
Daily refund cap (per team, per UTC day, default 100 credits). Once a team's
creditsRefundedTodayreachesdailyRefundCap, the response returnsdailyCapReached: truewithcreditsRefunded: 0. The feedback is still recorded for search-quality improvement — only the credit refund is gated. Stop calling this tool for the rest of the UTC day when you seedailyCapReached: true.
When to call: Right after processing a search result. If the result didn't help, send rating bad with a clear missingContent — that is just as valuable as a good rating.
Usage Example (good rating with valuable sources + missing content):
{
"name": "firecrawl_search_feedback",
"arguments": {
"searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
"rating": "good",
"valuableSources": [
{ "url": "https://docs.firecrawl.dev/features/search", "reason": "Most up-to-date description of /search." }
],
"missingContent": [
{ "topic": "Pricing for the search endpoint", "description": "No pricing tier table for /search specifically." },
{ "topic": "Rate limits", "description": "Per-team RPS for /search not documented." }
],
"querySuggestions": "Boost docs.firecrawl.dev for queries that mention 'firecrawl'"
}
}Usage Example (bad rating, what was missing):
{
"name": "firecrawl_search_feedback",
"arguments": {
"searchId": "0193f6c5-1234-7890-abcd-1234567890ab",
"rating": "bad",
"missingContent": [
{ "topic": "Recent benchmarks", "description": "All results were >12 months old." },
{ "topic": "Comparison vs Algolia" }
]
}
}Returns: { success, feedbackId, creditsRefunded, creditsRefundedToday, dailyRefundCap, dailyCapReached?, alreadySubmitted?, warning? } JSON.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rating | Yes | ||
| searchId | Yes | ||
| missingContent | No | ||
| valuableSources | No | ||
| querySuggestions | No |