Labsco
firecrawl logo

firecrawl-search

✓ Official★ 7

by firecrawl · part of firecrawl/firecrawl-cursor-plugin

Web search with full page content extraction. Use this skill whenever the user asks to search the web, find articles, research a topic, look something up, find recent news, discover sources, or says "search for", "find me", "look up", "what are people saying about", or "find articles about". Returns real search results with optional full-page markdown — not just snippets. Provides capabilities beyond Claude's built-in WebSearch.

🧩 One of 7 skills in the firecrawl/firecrawl-cursor-plugin package — works on its own, and pairs well with its siblings.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

firecrawl search

Search naturally using the user’s actual question. In the Alexandria beta, default search returns web results plus relevant Alexandria tools, with optional web content scraping.

The beta defaults to web,alexandria with domain-tool matching on. Preserve the user's location, marketplace, and constraints in the query; do not turn normal research into an artificial tool-discovery query. Inspect data.web and data.tools from the same response.

A tool match is not executed data. If it fits the task, read its inputs, coverage, creditsCost/perRecord, and access requirements in the JSON. Execute it with firecrawl scrape --alexandria <provider/capability> --options '<input JSON>'. All provider execution goes through Scrape; search --scrape only fetches web result content, not provider tools.

Use find-tools only for an explicitly requested tool set or a missing contract. It runs the firecrawl/find-tools meta tool through Scrape and never executes the tools it discovers. It accepts URLs or catalogue selectors; for “tools that can do X,” first use search "X" --sources alexandria, then narrow the returned providers with find-tools --options '{"providers":["<returned-provider>"],"level":"tools","limit":100}'.

If no returned tool covers the country/market/segment or required inputs, continue with ordinary web results. Do not exhaust the catalogue or pay for adjacent tools just to probe coverage. --sources web explicitly opts out of Alexandria; --sources web --domain-tools retains domain matches only.

Tips

  • --highlights on by default: results are query-relevant excerpts, not full-page snippets. Use --no-highlights for the original snippets.
  • --scrape fetches full content — reuse that content instead of re-scraping result URLs. This saves credits and avoids redundant fetches.
  • Always write results to .firecrawl/ with -o to avoid context window bloat.
  • Use jq to extract URLs or titles: jq -r '.data.web[].url' .firecrawl/search.json
  • Naming convention: .firecrawl/search-{query}.json or .firecrawl/search-{query}-scraped.json

Send feedback after every search (refunds 1 credit)

Search costs 2 credits. After you've actually used the results (or decided they were useless), send structured feedback with firecrawl search-feedback <id>. The first feedback per search refunds 1 credit and helps us improve search quality. Do this once per search, in the background, after you finish processing the results — it does not block your main task.

Opt out: if FIRECRAWL_NO_SEARCH_FEEDBACK=1 (or FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1) is set, the CLI silently skips the call and never sends anything. Respect that — do not try to work around it. (Team admins can also disable this server-side; the API will return feedbackErrorCode: "TEAM_OPTED_OUT" and the CLI will exit 0 silently.)

Rules to know before you call this:

  • Time window: must be sent within ~2 minutes of the search. Late feedback is rejected.
  • --missing-content is the most important field. It's a list of specific pieces of content you expected but did not find. One topic per entry, each in its own string. These aggregate across teams and tell us what to index next.
  • Substantive content required (zero-effort feedback is rejected with HTTP 400):
    • good → must include at least one --valuable-sources entry.
    • partial → must include --valuable-sources or --missing-content.
    • bad → must include --missing-content or --query-suggestions.
  • Daily refund cap (per team, per UTC day, default 100 credits). Once your team has been refunded 100 credits today, further submissions still record feedback but no longer refund credits. The response includes creditsRefundedToday / dailyRefundCap / dailyCapReached. When dailyCapReached: true, stop calling search-feedback for the rest of the UTC day — it won't refund anything and you're wasting bandwidth.
  • Idempotent: re-submitting for the same search id returns success but no extra refund.
  • --silent & is the right pattern — exit code 0 even on failure, so a rejected/expired call never crashes your pipeline.

Verify the search returned results before reading its id. Zero-result searches write no output file, so the file may be missing — or left over from an earlier search. The guard below skips feedback when the file is missing or has zero results; call search-feedback only inside it:

# Send once per search. Rate honestly and replace the placeholder with the
# rating that matches what actually happened. The two fields shown
# satisfy the substantive-content rule for every rating.
if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then
  firecrawl search-feedback "$SEARCH_ID" \
    --rating "<good|partial|bad>" \
    --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \
    --missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]' \
    --silent &
fi

--missing-content accepts:

  • JSON array of {topic, description?} objects (richest, preferred)
  • "topic: description" strings (shorthand)
  • Plain "topic1, topic2, topic3" (when you only have topic names)
  • Repeated --missing-content flags

--silent suppresses output and & runs it in the background so feedback never blocks you.

See also