> ## Documentation Index > Fetch the complete documentation index at: https://firecrawl-max-document-keyless-feedback.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Feedback > Submit feedback for a Firecrawl job. 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 ```bash theme={null} 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 ```bash theme={null} 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: ```json theme={null} { "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. ## OpenAPI ````yaml api-reference/v2-openapi.json POST /feedback openapi: 3.0.0 info: title: Firecrawl API version: v2 description: >- API for interacting with Firecrawl services to perform web scraping and crawling tasks. contact: name: Firecrawl Support url: https://firecrawl.dev/support email: support@firecrawl.dev servers: - url: https://api.firecrawl.dev/v2 security: - bearerAuth: [] paths: /feedback: post: tags: - Feedback summary: Submit feedback for a v2 job description: >- Submit feedback for a job. Keyless feedback supports Search, Scrape, and Parse. operationId: submitEndpointFeedback requestBody: required: true content: application/json: schema: anyOf: - title: Authenticated allOf: - $ref: '#/components/schemas/EndpointFeedbackRequest' - $ref: '#/components/schemas/KeylessFeedbackRequest' responses: '200': description: Feedback recorded content: application/json: schema: $ref: '#/components/schemas/FeedbackResponse' '400': description: Invalid request body content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '401': description: Authentication failed or keyless access is unavailable content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '403': description: Feedback is not available for this caller content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '404': description: Job not found for this caller content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '409': description: Feedback cannot be recorded for this job content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '429': description: Too many feedback requests content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' '503': description: Feedback is temporarily unavailable content: application/json: schema: $ref: '#/components/schemas/FeedbackErrorResponse' security: - {} - bearerAuth: [] components: schemas: EndpointFeedbackRequest: allOf: - $ref: '#/components/schemas/SearchFeedbackRequest' - type: object description: >- Submit feedback for a v2 job. Include at least one substantive signal such as issues, note, valuableSources, missingContent, querySuggestions, url, or pageNumbers. properties: endpoint: type: string enum: - search - scrape - parse - map jobId: type: string format: uuid issues: type: array maxItems: 20 items: type: string pattern: ^[a-z0-9][a-z0-9_-]*$ maxLength: 80 tags: type: array maxItems: 20 items: type: string pattern: ^[a-z0-9][a-z0-9_-]*$ maxLength: 80 note: type: string maxLength: 4000 url: type: string format: uri pageNumbers: type: array maxItems: 100 items: type: integer minimum: 1 metadata: type: object additionalProperties: true description: >- Small endpoint-specific metadata object. Must be 8KB or smaller; do not include full endpoint results. missingContent: type: array maxItems: 50 items: type: object properties: topic: type: string maxLength: 200 minLength: 1 description: type: string maxLength: 2000 required: - topic required: - endpoint - jobId KeylessFeedbackRequest: anyOf: - type: object properties: endpoint: type: string enum: - search jobId: type: string format: uuid description: Job ID returned by /search. rating: type: string enum: - good - partial - bad description: Overall quality of the result. task: type: string description: What you were trying to accomplish. minLength: 10 maxLength: 2000 assessment: type: string description: How well the result met your needs. minLength: 10 maxLength: 2000 observations: type: array description: >- Specific observations about the result. Text limits exclude leading and trailing whitespace. Unmentioned results are unassessed; a full ranking is not required. minItems: 1 maxItems: 20 items: anyOf: - type: object properties: kind: type: string enum: - useful source: type: string enum: - web - images - news description: >- Delivered group the position refers to. Required for multi-source jobs. Omission defaults to `web`, so images-only and news-only jobs must explicitly name their source. position: type: integer minimum: 1 description: Position in the returned result group, starting at 1. example: 1 vertical: type: string enum: - web_general - social - business - research - developer - news - government - finance - other description: Subject area you were looking for. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - position additionalProperties: false title: useful not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - irrelevant source: type: string enum: - web - images - news description: >- Delivered group the position refers to. Required for multi-source jobs. Omission defaults to `web`, so images-only and news-only jobs must explicitly name their source. position: type: integer minimum: 1 description: Position in the returned result group, starting at 1. example: 1 vertical: type: string enum: - web_general - social - business - research - developer - news - government - finance - other description: Subject area you were looking for. reason: type: string enum: - aggregator_over_official - off_topic - stale - wrong_content_type - snippet_misleading - blocked_or_paywalled description: >- - `aggregator_over_official`: An intermediary was returned where the task needed an available official or primary source. - `off_topic`: The result addresses a different topic from the task. - `stale`: The content is outdated for the time or version the task requires. - `wrong_content_type`: The destination has the wrong content type for the task, such as a discussion instead of a reference. - `snippet_misleading`: The returned description misrepresents source content already inspected. - `blocked_or_paywalled`: Access to the destination was observed to be blocked or require a subscription; do not infer this from its URL or snippet. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' knownSources: type: array description: >- Known sources that should have ranked instead of this result. maxItems: 20 items: type: string format: uri pattern: ^https?:// required: - kind - detail - basis - position - reason additionalProperties: false title: irrelevant not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - missing vertical: type: string enum: - web_general - social - business - research - developer - news - government - finance - other description: Subject area you were looking for. topic: type: string description: Information missing from the results. minLength: 1 maxLength: 200 knownSources: type: array description: Known sources that were missing from the results. maxItems: 20 items: type: string format: uri pattern: ^https?:// detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - vertical additionalProperties: false title: missing not: properties: basis: enum: - source_comparison not: required: - comparison - type: object title: failure description: >- An explicitly reported failure of this job. Accepted only when the saved job failed. No result position or output format is required. properties: kind: type: string enum: - failure reason: type: string enum: - timeout - transport_error - proxy_error - other description: >- - `timeout`: The operation explicitly reported a timeout. - `transport_error`: The operation explicitly reported a network, connection, or TLS failure. - `proxy_error`: The operation explicitly reported a proxy failure. - `other`: Another operation failure was reported; describe the returned error without guessing its cause. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - reason - detail - basis additionalProperties: false not: properties: basis: enum: - source_comparison not: required: - comparison origin: type: string description: Client submitting the feedback. maxLength: 100 default: api integration: type: string description: Integration submitting the feedback. maxLength: 100 nullable: true required: - endpoint - jobId - rating - task - assessment - observations additionalProperties: false title: Search - type: object properties: endpoint: type: string enum: - scrape jobId: type: string format: uuid description: Job ID returned by /scrape. rating: type: string enum: - good - partial - bad description: Overall quality of the result. task: type: string description: What you were trying to accomplish. minLength: 10 maxLength: 2000 assessment: type: string description: How well the result met your needs. minLength: 10 maxLength: 2000 observations: type: array description: >- Specific observations about the result. Text limits exclude leading and trailing whitespace. minItems: 1 maxItems: 20 items: anyOf: - type: object properties: kind: type: string enum: - correct format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 location: type: string description: Location of the content in the page or output. minLength: 1 maxLength: 200 detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis additionalProperties: false title: correct not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - wrong_success format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 location: type: string description: Location of the content in the page or output. minLength: 1 maxLength: 200 reason: type: string enum: - blocked_shell - login_required - paywall - empty - wrong_page - stale - wrong_locale description: >- - `blocked_shell`: The successful response contains a bot challenge or access-blocking shell instead of the requested content. - `login_required`: The successful response contains a login requirement instead of the requested content. - `paywall`: The successful response contains a subscription barrier instead of the requested content. - `empty`: The successful response contains no meaningful requested content. - `wrong_page`: The successful response contains a different page or resource. - `stale`: The content is outdated for the time or version the task requires. - `wrong_locale`: The response uses the wrong language or region for the task. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: wrong_success not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - incomplete description: >- Prefer `source_comparison` when the source is already available, and provide the correct content in `comparison.detail`. format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 location: type: string description: Location of the content in the page or output. minLength: 1 maxLength: 200 reason: type: string enum: - partial_content - dynamic_content - pagination - main_content_stripped - format_lost description: >- - `partial_content`: Only part of the expected content was returned, without a more specific known cause. - `dynamic_content`: Content loaded by client-side rendering or interaction is missing. - `pagination`: Expected content on additional pages is missing. - `main_content_stripped`: Content filtering removed requested primary content. - `format_lost`: Text is present, but meaningful structure such as headings, lists, or code formatting was lost. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: incomplete not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - incorrect description: >- Prefer `source_comparison` when the source is already available, and provide the correct content in `comparison.detail`. format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 location: type: string description: Location of the content in the page or output. minLength: 1 maxLength: 200 reason: type: string enum: - wrong - hallucinated - missing_fields description: >- - `wrong`: Returned facts or values conflict with the inspected source. - `hallucinated`: The output asserts content unsupported by the inspected source. - `missing_fields`: Requested fields are absent from the structured output. `hallucinated` applies only to `json`, `deterministicJson`, `summary`, `question`, `highlights`, and `changeTracking` in `json` mode. `missing_fields` applies only to `json` and `deterministicJson`. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: incorrect not: properties: basis: enum: - source_comparison not: required: - comparison - type: object title: failure description: >- An explicitly reported failure of this job. Accepted only when the saved job failed. No result position or output format is required. properties: kind: type: string enum: - failure reason: type: string enum: - timeout - transport_error - proxy_error - other description: >- - `timeout`: The operation explicitly reported a timeout. - `transport_error`: The operation explicitly reported a network, connection, or TLS failure. - `proxy_error`: The operation explicitly reported a proxy failure. - `other`: Another operation failure was reported; describe the returned error without guessing its cause. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - reason - detail - basis additionalProperties: false not: properties: basis: enum: - source_comparison not: required: - comparison origin: type: string description: Client submitting the feedback. maxLength: 100 default: api integration: type: string description: Integration submitting the feedback. maxLength: 100 nullable: true required: - endpoint - jobId - rating - task - assessment - observations additionalProperties: false title: Scrape - type: object properties: endpoint: type: string enum: - parse jobId: type: string format: uuid description: Job ID returned by /parse. rating: type: string enum: - good - partial - bad description: Overall quality of the result. task: type: string description: What you were trying to accomplish. minLength: 10 maxLength: 2000 assessment: type: string description: How well the result met your needs. minLength: 10 maxLength: 2000 docClass: type: string enum: - born_digital - scanned - mixed - unknown description: >- Type of document. Use `unknown` if you cannot determine the type. observations: type: array description: >- Specific observations about the result. Text limits exclude leading and trailing whitespace. minItems: 1 maxItems: 20 items: anyOf: - type: object properties: kind: type: string enum: - correct - formula - chart_figure - reading_order - headers_footers - headings_formatting - images_dropped format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 page: type: integer minimum: 1 description: Page number, starting at 1. example: 1 detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis additionalProperties: false title: Other not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - text_ocr format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 page: type: integer minimum: 1 description: Page number, starting at 1. example: 1 reason: type: string enum: - misread_chars - garbled - missing_text description: >- - `misread_chars`: Characters were recognized incorrectly. - `garbled`: Extracted text is corrupted or unreadable. - `missing_text`: Visible source text was omitted. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: text_ocr not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - table format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 page: type: integer minimum: 1 description: Page number, starting at 1. example: 1 reason: type: string enum: - structure - cells_glued - digits description: >- - `structure`: Table rows, columns, or header relationships were reconstructed incorrectly. - `cells_glued`: Distinct table cells were merged. - `digits`: Numeric table values were recognized incorrectly. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: table not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - completeness format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 page: type: integer minimum: 1 description: Page number, starting at 1. example: 1 reason: type: string enum: - pages_missing - truncated_at_max_pages - sections_dropped description: >- - `pages_missing`: Source pages are absent from the output. - `truncated_at_max_pages`: Extraction ended at the configured page limit; this does not by itself imply a parser error. - `sections_dropped`: Sections within processed pages were omitted. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: completeness not: properties: basis: enum: - source_comparison not: required: - comparison - type: object properties: kind: type: string enum: - incorrect description: Incorrect `json` or `summary` output. format: type: string description: >- Requested output format this observation refers to. Required when the job requested multiple formats and `basis` is `output` or `source_comparison`. minLength: 1 page: type: integer minimum: 1 description: Page number, starting at 1. example: 1 reason: type: string enum: - wrong - hallucinated - missing_fields description: >- - `wrong`: Returned facts or values conflict with the inspected source. - `hallucinated`: The output asserts content unsupported by the inspected source. - `missing_fields`: Requested fields are absent from the structured output. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - detail - basis - reason additionalProperties: false title: incorrect not: properties: basis: enum: - source_comparison not: required: - comparison - type: object title: failure description: >- An explicitly reported failure of this job. Accepted only when the saved job failed. No result position or output format is required. properties: kind: type: string enum: - failure reason: type: string enum: - timeout - transport_error - proxy_error - other description: >- - `timeout`: The operation explicitly reported a timeout. - `transport_error`: The operation explicitly reported a network, connection, or TLS failure. - `proxy_error`: The operation explicitly reported a proxy failure. - `other`: Another operation failure was reported; describe the returned error without guessing its cause. detail: $ref: '#/components/schemas/FeedbackDetail' basis: $ref: '#/components/schemas/FeedbackBasis' comparison: $ref: '#/components/schemas/FeedbackComparison' required: - kind - reason - detail - basis additionalProperties: false not: properties: basis: enum: - source_comparison not: required: - comparison origin: type: string description: Client submitting the feedback. maxLength: 100 default: api integration: type: string description: Integration submitting the feedback. maxLength: 100 nullable: true required: - endpoint - jobId - rating - task - assessment - observations - docClass additionalProperties: false title: Parse description: >- Feedback for keyless jobs within 24 hours, submitted from the same caller IP. The serialized stored metadata, including server defaults and verification flags, must fit within 8 KiB (8192 UTF-8 bytes). The daily allowance defaults to one accepted submission per caller IP across Search, Scrape, Parse, and all clients; deployments may configure a different allowance. Submission attempts are limited to 30 per minute, including rejected requests. Duplicate submissions return the original record without using another daily slot. FeedbackResponse: type: object properties: success: type: boolean example: true feedbackId: type: string format: uuid creditsRefunded: type: number alreadySubmitted: type: boolean dailyCapReached: type: boolean creditsRefundedToday: type: number dailyRefundCap: type: number warning: type: string required: - success - feedbackId - creditsRefunded FeedbackErrorResponse: type: object properties: success: type: boolean example: false error: type: string feedbackErrorCode: type: string details: type: array items: type: object required: - success - error SearchFeedbackRequest: type: object description: >- For 'good', include valuableSources. For 'partial', include valuableSources or missingContent. For 'bad', include missingContent or querySuggestions. properties: rating: type: string enum: - good - partial - bad valuableSources: type: array maxItems: 50 items: type: object properties: url: type: string format: uri reason: type: string maxLength: 1000 required: - url missingContent: type: array maxItems: 20 items: type: object properties: topic: type: string maxLength: 200 minLength: 1 description: type: string maxLength: 2000 required: - topic querySuggestions: type: string maxLength: 2000 origin: type: string default: api integration: type: string nullable: true required: - rating FeedbackDetail: type: string description: Describe what you observed. minLength: 10 maxLength: 2000 FeedbackBasis: type: string enum: - output - source_comparison - expectation description: >- What supports the observation. Use `output` for returned content, `source_comparison` for a source you already inspected, or `expectation` for an unmet need. Include `comparison` when using `source_comparison`. FeedbackComparison: type: object properties: reference: type: string description: URL or location of the source you compared. minLength: 1 maxLength: 2048 detail: type: string description: >- The correct content from the inspected source, including correct text or cell values when known. minLength: 10 maxLength: 2000 required: - reference - detail additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer ````