Feedback

Submit feedback for a v2 job

curl --request POST \
  --url https://api.firecrawl.dev/v2/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "valuableSources": [
    {
      "url": "<string>",
      "reason": "<string>"
    }
  ],
  "missingContent": [
    {
      "topic": "<string>",
      "description": "<string>"
    }
  ],
  "querySuggestions": "<string>",
  "origin": "api",
  "integration": "<string>",
  "issues": [
    "<string>"
  ],
  "tags": [
    "<string>"
  ],
  "note": "<string>",
  "url": "<string>",
  "pageNumbers": [
    2
  ],
  "metadata": {}
}
'

import requests

url = "https://api.firecrawl.dev/v2/feedback"

payload = {
    "jobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "valuableSources": [
        {
            "url": "<string>",
            "reason": "<string>"
        }
    ],
    "missingContent": [
        {
            "topic": "<string>",
            "description": "<string>"
        }
    ],
    "querySuggestions": "<string>",
    "origin": "api",
    "integration": "<string>",
    "issues": ["<string>"],
    "tags": ["<string>"],
    "note": "<string>",
    "url": "<string>",
    "pageNumbers": [2],
    "metadata": {}
}
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({
    jobId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    valuableSources: [{url: '<string>', reason: '<string>'}],
    missingContent: [{topic: '<string>', description: '<string>'}],
    querySuggestions: '<string>',
    origin: 'api',
    integration: '<string>',
    issues: ['<string>'],
    tags: ['<string>'],
    note: '<string>',
    url: '<string>',
    pageNumbers: [2],
    metadata: {}
  })
};

fetch('https://api.firecrawl.dev/v2/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/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([
    'jobId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'valuableSources' => [
        [
                'url' => '<string>',
                'reason' => '<string>'
        ]
    ],
    'missingContent' => [
        [
                'topic' => '<string>',
                'description' => '<string>'
        ]
    ],
    'querySuggestions' => '<string>',
    'origin' => 'api',
    'integration' => '<string>',
    'issues' => [
        '<string>'
    ],
    'tags' => [
        '<string>'
    ],
    'note' => '<string>',
    'url' => '<string>',
    'pageNumbers' => [
        2
    ],
    'metadata' => [
        
    ]
  ]),
  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/feedback"

	payload := strings.NewReader("{\n  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\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/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/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  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\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": [
    {}
  ]
}

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

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

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

POST

feedback

Submit feedback for a v2 job

curl --request POST \
  --url https://api.firecrawl.dev/v2/feedback \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "jobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "valuableSources": [
    {
      "url": "<string>",
      "reason": "<string>"
    }
  ],
  "missingContent": [
    {
      "topic": "<string>",
      "description": "<string>"
    }
  ],
  "querySuggestions": "<string>",
  "origin": "api",
  "integration": "<string>",
  "issues": [
    "<string>"
  ],
  "tags": [
    "<string>"
  ],
  "note": "<string>",
  "url": "<string>",
  "pageNumbers": [
    2
  ],
  "metadata": {}
}
'

import requests

url = "https://api.firecrawl.dev/v2/feedback"

payload = {
    "jobId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "valuableSources": [
        {
            "url": "<string>",
            "reason": "<string>"
        }
    ],
    "missingContent": [
        {
            "topic": "<string>",
            "description": "<string>"
        }
    ],
    "querySuggestions": "<string>",
    "origin": "api",
    "integration": "<string>",
    "issues": ["<string>"],
    "tags": ["<string>"],
    "note": "<string>",
    "url": "<string>",
    "pageNumbers": [2],
    "metadata": {}
}
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({
    jobId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    valuableSources: [{url: '<string>', reason: '<string>'}],
    missingContent: [{topic: '<string>', description: '<string>'}],
    querySuggestions: '<string>',
    origin: 'api',
    integration: '<string>',
    issues: ['<string>'],
    tags: ['<string>'],
    note: '<string>',
    url: '<string>',
    pageNumbers: [2],
    metadata: {}
  })
};

fetch('https://api.firecrawl.dev/v2/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/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([
    'jobId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'valuableSources' => [
        [
                'url' => '<string>',
                'reason' => '<string>'
        ]
    ],
    'missingContent' => [
        [
                'topic' => '<string>',
                'description' => '<string>'
        ]
    ],
    'querySuggestions' => '<string>',
    'origin' => 'api',
    'integration' => '<string>',
    'issues' => [
        '<string>'
    ],
    'tags' => [
        '<string>'
    ],
    'note' => '<string>',
    'url' => '<string>',
    'pageNumbers' => [
        2
    ],
    'metadata' => [
        
    ]
  ]),
  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/feedback"

	payload := strings.NewReader("{\n  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\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/feedback")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.firecrawl.dev/v2/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  \"jobId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"valuableSources\": [\n    {\n      \"url\": \"<string>\",\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  \"issues\": [\n    \"<string>\"\n  ],\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"note\": \"<string>\",\n  \"url\": \"<string>\",\n  \"pageNumbers\": [\n    2\n  ],\n  \"metadata\": {}\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": [
    {}
  ]
}

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

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

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

Submit feedback on the quality of a job’s output, including useful results, missing content, or incorrect data. For jobs created with an API key, include your key and use the Authenticated request format. For keyless jobs, omit Authorization and use the Search, Scrape, or Parse request format. Keyless Parse feedback does not automatically retain the document, extracted output, page images, or layout blocks. Submitted observations and corrections are retained.

Authenticated example

curl -X POST "https://api.firecrawl.dev/v2/feedback" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "scrape",
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "rating": "partial",
    "issues": ["missing_markdown"],
    "note": "The pricing table was missing from the markdown output.",
    "url": "https://example.com/pricing"
  }'

Keyless example

curl -X POST "https://api.firecrawl.dev/v2/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "search",
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "rating": "good",
    "task": "Find the documented retry behavior",
    "assessment": "The API reference answered the retry question.",
    "observations": [
      {
        "kind": "useful",
        "source": "web",
        "position": 1,
        "detail": "The reference specifies the retry intervals.",
        "basis": "output"
      }
    ]
  }'

Keyless limits and failures

Every eligible keyless Search, Scrape, or Parse response includes a feedback pointer and this documentation link. Use the returned job ID from the same caller IP within 24 hours. The default allowance is one accepted submission per caller IP per UTC day across all three endpoints and clients; the invitation states the deployment allowance. There are 30 submission attempts per minute, including rejected requests. Retrying a recorded submission returns its original feedback ID without using another daily slot. The serialized stored keyless metadata must fit within 8 KiB (8192 UTF-8 bytes), including server defaults and verification flags. Keep observations concise and omit raw outputs. For Search, positions refer to the ordered results in the delivered web, images, or news group. Specify source for multi-source jobs and for images-only or news-only jobs; omission defaults to web. If the saved Search response is unavailable, otherwise valid feedback is accepted with an internal metadata.unverified: true marker because positions could not be checked. Ownership and requested sources are still checked. Invalid positions in available results are rejected. An explicitly failed job can receive a failure observation. Use the reported error, without diagnosing an unobserved cause. For example, replace the observation in your submission with:

{
  "kind": "failure",
  "reason": "timeout",
  "basis": "output",
  "detail": "The operation returned a timeout before producing a result."
}

A failure observation has no position, source, format, location, or page. Parse still requires a top-level docClass, which may be unknown. The API accepts this observation only for a saved failed job. Requests rejected before execution, such as invalid input or exhausted operation quota, are not feedback jobs.

Authorizations

Authorization

string

header

required

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

Body

application/json

Authenticated
Search
Scrape
Parse

Submit feedback for a v2 job. Include at least one substantive signal such as issues, note, valuableSources, missingContent, querySuggestions, url, or pageNumbers.

rating

enum<string>

required

Available options:

good,

partial,

bad

endpoint

enum<string>

required

Available options:

search,

scrape,

parse,

map

jobId

string<uuid>

required

valuableSources

object[]

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

issues

string[]

Maximum array length: 20

Maximum string length: 80

Pattern: ^[a-z0-9][a-z0-9_-]*$

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

Map Endpoints

Parse Endpoints

Crawl Endpoints

Monitor Endpoints

Agent Endpoints

Feedback Endpoints

Agentic Debugging Endpoints

Account Endpoints

Webhook Payloads

Partner Integration

Authenticated example

Keyless example

Keyless limits and failures

Authorizations

Body

Response

​Authenticated example

​Keyless example

​Keyless limits and failures

Authorizations

Body

Response

Authenticated example

Keyless example

Keyless limits and failures