Search Feedback

Submit feedback for a search job

curl --request POST \
  --url https://api.firecrawl.dev/v2/search/{jobId}/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "valuableSources": [
    {
      "url": "<string>",
      "reason": "<string>"
    }
  ],
  "valuableResults": [
    {
      "position": 50,
      "reason": "<string>"
    }
  ],
  "missingContent": [
    {
      "topic": "<string>",
      "description": "<string>"
    }
  ],
  "querySuggestions": "<string>",
  "origin": "api",
  "integration": "<string>"
}
'

import requests

url = "https://api.firecrawl.dev/v2/search/{jobId}/feedback"

payload = {
    "valuableSources": [
        {
            "url": "<string>",
            "reason": "<string>"
        }
    ],
    "valuableResults": [
        {
            "position": 50,
            "reason": "<string>"
        }
    ],
    "missingContent": [
        {
            "topic": "<string>",
            "description": "<string>"
        }
    ],
    "querySuggestions": "<string>",
    "origin": "api",
    "integration": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    valuableSources: [{url: '<string>', reason: '<string>'}],
    valuableResults: [{position: 50, reason: '<string>'}],
    missingContent: [{topic: '<string>', description: '<string>'}],
    querySuggestions: '<string>',
    origin: 'api',
    integration: '<string>'
  })
};

fetch('https://api.firecrawl.dev/v2/search/{jobId}/feedback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/search/{jobId}/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([
    'valuableSources' => [
        [
                'url' => '<string>',
                'reason' => '<string>'
        ]
    ],
    'valuableResults' => [
        [
                'position' => 50,
                'reason' => '<string>'
        ]
    ],
    'missingContent' => [
        [
                'topic' => '<string>',
                'description' => '<string>'
        ]
    ],
    'querySuggestions' => '<string>',
    'origin' => 'api',
    'integration' => '<string>'
  ]),
  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.firecrawl.dev/v2/search/{jobId}/feedback"

	payload := strings.NewReader("{\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\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.firecrawl.dev/v2/search/{jobId}/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/search/{jobId}/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  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "feedbackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "creditsRefunded": 123,
  "alreadySubmitted": true,
  "dailyCapReached": true,
  "creditsRefundedToday": 123,
  "dailyRefundCap": 123,
  "warning": "<string>"
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

POST

{jobId}

feedback

Submit feedback for a search job

curl --request POST \
  --url https://api.firecrawl.dev/v2/search/{jobId}/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "valuableSources": [
    {
      "url": "<string>",
      "reason": "<string>"
    }
  ],
  "valuableResults": [
    {
      "position": 50,
      "reason": "<string>"
    }
  ],
  "missingContent": [
    {
      "topic": "<string>",
      "description": "<string>"
    }
  ],
  "querySuggestions": "<string>",
  "origin": "api",
  "integration": "<string>"
}
'

import requests

url = "https://api.firecrawl.dev/v2/search/{jobId}/feedback"

payload = {
    "valuableSources": [
        {
            "url": "<string>",
            "reason": "<string>"
        }
    ],
    "valuableResults": [
        {
            "position": 50,
            "reason": "<string>"
        }
    ],
    "missingContent": [
        {
            "topic": "<string>",
            "description": "<string>"
        }
    ],
    "querySuggestions": "<string>",
    "origin": "api",
    "integration": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    valuableSources: [{url: '<string>', reason: '<string>'}],
    valuableResults: [{position: 50, reason: '<string>'}],
    missingContent: [{topic: '<string>', description: '<string>'}],
    querySuggestions: '<string>',
    origin: 'api',
    integration: '<string>'
  })
};

fetch('https://api.firecrawl.dev/v2/search/{jobId}/feedback', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.firecrawl.dev/v2/search/{jobId}/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([
    'valuableSources' => [
        [
                'url' => '<string>',
                'reason' => '<string>'
        ]
    ],
    'valuableResults' => [
        [
                'position' => 50,
                'reason' => '<string>'
        ]
    ],
    'missingContent' => [
        [
                'topic' => '<string>',
                'description' => '<string>'
        ]
    ],
    'querySuggestions' => '<string>',
    'origin' => 'api',
    'integration' => '<string>'
  ]),
  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.firecrawl.dev/v2/search/{jobId}/feedback"

	payload := strings.NewReader("{\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\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.firecrawl.dev/v2/search/{jobId}/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/search/{jobId}/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  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"valuableResults\": [\n    {\n      \"position\": 50,\n      \"reason\": \"<string>\"\n    }\n  ],\n  \"missingContent\": [\n    {\n      \"topic\": \"<string>\",\n      \"description\": \"<string>\"\n    }\n  ],\n  \"querySuggestions\": \"<string>\",\n  \"origin\": \"api\",\n  \"integration\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "feedbackId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "creditsRefunded": 123,
  "alreadySubmitted": true,
  "dailyCapReached": true,
  "creditsRefundedToday": 123,
  "dailyRefundCap": 123,
  "warning": "<string>"
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

{
  "success": false,
  "error": "<string>",
  "feedbackErrorCode": "<string>",
  "details": [
    {}
  ]
}

Use search feedback after a search result is used or fails to help. Feedback improves result quality and can refund 1 credit for the first feedback submission on a search job, subject to team limits. Use valuableResults to mark useful results by where they appeared in the response. Each entry names the source group (web, images, or news) and the result’s 1-indexed position within that group, because each group is numbered from 1 independently. List every useful result: unlisted results are treated as not useful, and positions beyond what a group returned are ignored. This works for news and image results that have no url. Use valuableSources for useful URLs, including ones that were not among the returned results.

Example Request

curl -X POST "https://api.firecrawl.dev/v2/search/550e8400-e29b-41d4-a716-446655440000/feedback" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rating": "good",
    "valuableSources": [
      {
        "url": "https://docs.firecrawl.dev/features/search",
        "reason": "Most up-to-date description of /search."
      }
    ],
    "valuableResults": [
      {
        "source": "web",
        "position": 1,
        "reason": "Answered the question directly."
      },
      {
        "source": "news",
        "position": 2
      }
    ],
    "missingContent": [
      {
        "topic": "Pricing for the search endpoint",
        "description": "No pricing tier table for /search specifically."
      }
    ],
    "querySuggestions": "Boost docs.firecrawl.dev for queries that mention Firecrawl"
  }'

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

jobId

string<uuid>

required

Search job id returned by /search.

Body

application/json

For 'good', include valuableSources or valuableResults. For 'partial', include valuableSources, valuableResults, or missingContent. For 'bad', include missingContent or querySuggestions.

rating

enum<string>

required

Available options:

good,

partial,

bad

valuableSources

object[]

Maximum array length: 50

Show child attributes

valuableResults

object[]

Results that were useful, each addressed by the data group it appears in and its 1-indexed position within that group. Results are returned grouped (data.web, data.images, data.news) and each group is numbered from 1 independently, so source is required. List every useful result; unlisted results are treated as not useful. Positions beyond what the group actually returned are ignored.

Maximum array length: 50

Show child attributes

missingContent

object[]

Maximum array length: 20

Show child attributes

querySuggestions

string

Maximum string length: 2000

origin

string

default:api

integration

string | null

Response

Feedback recorded

success

boolean

required

Example:

true

feedbackId

string<uuid>

required

creditsRefunded

number

required

alreadySubmitted

boolean

dailyCapReached

boolean

creditsRefundedToday

number

dailyRefundCap

number

warning

string

Using the API

Search Endpoints

Scrape Endpoints

Interact / Browser Sandbox Endpoints

Research Index Endpoints

Developer Index Endpoints

Government Index Endpoints

Map Endpoints

Parse Endpoints

Crawl Endpoints

Monitor Endpoints

Agent Endpoints

Feedback Endpoints

Agentic Debugging Endpoints

Account Endpoints

Webhook Payloads

Firecrawl for Platforms

Example Request

Authorizations

Path Parameters

Body

Response

​Example Request

Authorizations

Path Parameters

Body

Response

Example Request