Mastering Firecrawl Search Endpoint: Web Search and Data Extraction in One API Call

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Firecrawl의 /v2/search는 검색과 선택적 본문 추출을 한 번의 API 호출로 결합하며, 결과 유형·분야·기간·지역·도메인 필터와 Alexandria 데이터 도구 검색을 지원한다.

📌 핵심 요약

• Firecrawl은 특정 URL의 단일 페이지를 추출하는 scrape, 시작 URL에서 사이트의 연결된 페이지를 탐색하는 crawl, 검색어로 여러 사이트의 관련 정보를 찾는 search를 제공한다.
• /v2/search는 기본적으로 제목·URL·설명 등의 웹 검색 결과를 반환하며, scrape_options에 markdown 등의 형식을 지정하면 각 결과의 본문도 추출한다.
• sources는 web·news·images·alexandria를, categories는 github·research·pdf를 지정하는 데 사용한다. alexandria를 추가하면 공식 API·라이선스가 있는 퍼블리셔·Firecrawl 자체 인덱스의 데이터 도구가 별도 tools 배열에 반환되며, 도구 발견은 무료다.
• 검색만 수행하면 결과 10개당 2크레딧이며, 원문의 결과 5개 요청 예시도 2크레딧을 사용한다. 본문 추출에는 페이지별 표준 scrape 비용이 추가되고, 무료 요금제에는 월 1,000크레딧이 포함된다.
• REST API·Python 및 Node SDK·MCP 서버·CLI와 여러 연동 도구에서 사용할 수 있다. tbs는 웹 결과에만 적용되며 includeDomains와 excludeDomains는 함께 사용할 수 없고, 검색에는 출처 누락·예상 밖 결과 및 429·400·401 오류 가능성이 있다.

🧩 주요 포인트

1. 알고 있는 URL인지 탐색이 필요한 검색어인지에 따라 엔드포인트의 역할이 달라짐 → search로 출처를 찾고 scrape 또는 crawl로 후속 수집하는 조합이 가능하다.
2. scrape_options가 검색 결과별 본문 추출을 자동 실행함 → 별도 호출과 연결 코드 부담을 줄일 수 있지만, 검색 비용에 페이지별 추출 비용이 더해진다.
3. sources·categories와 기간·지역·도메인 필터가 탐색 범위를 조절함 → 정보 목적에 맞춘 검색이 가능하며, Alexandria는 같은 요청의 탐색 대상을 데이터 도구까지 넓힌다.

🧠 상세 정리

1. 최신 정보 탐색과 본문 확보를 연결하는 검색

글은 유용한 AI 에이전트가 변화하는 현실의 최신 맥락을 확보하려면 웹 검색이 필요하다는 문제의식에서 출발한다. 학습 데이터만 사용하는 에이전트는 정보가 정적이고 오래될 수 있으므로, 먼저 적절한 출처를 찾은 다음 내용을 추출해 활용하는 과정이 중요하다는 주장이다. 일반적인 검색 API가 링크 목록을 반환한 뒤 결과별 별도 스크래핑과 연결 코드를 요구하는 데 비해, Firecrawl은 검색과 본문 추출을 하나의 호출로 결합한다고 설명한다. 다만 본문을 실제로 받으려면 scrape_options를 지정해야 하며, 기본 검색 응답과 본문 추출을 포함한 응답은 구분해야 한다. 원문은 이 기능을 첫 검색부터 연구 에이전트 구축까지 소개한다고 예고하지만, 제공된 본문은 검색 결과의 콘텐츠 추출 예시 도중에 끝난다.

2. scrape·crawl·search의 역할과 조합

scrape는 사용자가 이미 알고 있는 특정 URL에서 깨끗한 콘텐츠를 추출하며, JavaScript 렌더링과 복잡한 HTML의 구조화 처리를 담당하는 방식으로 소개된다. crawl은 시작 URL에서 링크를 따라 연결된 페이지를 발견하고 페이지네이션을 처리하면서, 특정 사이트의 여러 페이지와 구조를 수집하는 데 적합하다. search는 URL 대신 검색어로 시작해 여러 사이트의 관련 페이지를 찾으므로, 필요한 정보가 어느 웹사이트에 있는지 모르는 조사와 발견 작업에 맞는다. 원문은 scrape가 가장 빠르지만 범위가 제한적이고 crawl은 더 오래 걸리며, search는 관련성이 높은 자료를 찾더라도 일부 출처를 놓치거나 예상하지 못한 결과를 반환할 수 있다고 설명한다. 실제 활용에서는 search로 출처를 발견한 뒤 해당 사이트를 crawl하거나 가치가 높은 개별 페이지를 scrape하는 방식으로 이들을 조합할 수 있다.

3. 호출 경로와 기존 도구의 연동

Firecrawl Search는 REST API, Python 및 Node SDK, CLI, MCP 서버를 통해 사용할 수 있으며, 본문은 REST 요청과 Python 호출, CLI 명령을 예시로 보여준다. MCP 서버를 추가하면 Claude Desktop, Claude Code, Cursor, Windsurf, VS Code처럼 Model Context Protocol을 지원하는 도구에서 모델이 firecrawl_search를 직접 호출할 수 있다고 설명한다. OpenRouter에서는 openrouter:web_search 도구의 engine 값을 firecrawl로 지정해 다섯 검색 엔진 중 하나로 선택할 수 있고, n8n에서는 시각적 워크플로 편집기의 독립적인 검색 작업으로 제공된다. OpenClaw는 CLI 스킬 설치 후 Firecrawl을 기본 검색 제공자로 사용한다고 소개되며, 이후 튜토리얼은 예제를 설명하기 편한 Python SDK를 중심으로 진행한다. 이러한 연동 설명은 같은 검색 기능에 접근하는 경로를 보여주는 것이며, 제공된 본문에 각 환경의 상세 설치 절차가 모두 포함된 것은 아니다.

4. 첫 검색의 설정과 크레딧 비용

원문은 API 키 없이도 Firecrawl 엔드포인트를 시험할 수 있고, 더 높은 요청 한도와 추가 크레딧이 필요하면 가입해 API 키를 발급받을 수 있다고 안내한다. 무료 요금제에는 월 1,000크레딧이 포함되며, Python 예시는 API 키를 .env 파일에 저장하고 load_dotenv를 실행한 뒤 Firecrawl 객체를 생성하는 흐름을 제시한다. 첫 검색은 프로젝트 관리 도구를 찾는 검색어와 limit 값 5를 전달해 상위 5개 결과를 받는 구성이다. 본문을 추출하지 않는 검색의 요금은 검색 결과 10개당 2크레딧으로 설명되며, 원문은 이 5개 결과 요청 역시 총 2크레딧을 사용한다고 명시한다. 검색에 본문 추출을 추가하면 페이지마다 표준 scrape 비용이 더해지므로, 단순 검색의 비용과 본문까지 확보하는 요청의 비용을 구별해야 한다.

5. 검색 응답의 구조와 실패 처리

기본 응답에는 웹 검색 결과가 포함되며, Python 예시는 results.web에서 결과 수를 확인하고 개별 항목의 title, url, description, category를 읽는 방법을 보여준다. 프로젝트 관리 도구 검색 결과에는 전문 매체의 추천 글, Reddit 게시물, ICAgile의 리뷰, Asana와 Microsoft의 제품 페이지처럼 성격이 서로 다른 출처가 함께 등장한다. 첫 결과의 category가 None으로 출력되는 예시는 모든 응답 항목에 특정 분야 분류값이 반드시 채워지는 것은 아님을 보여준다. 오류 처리 예시는 검색 결과가 존재하는 경우와 빈 경우를 나누고, 예외가 발생하면 실패 메시지를 출력하도록 구성된다. 원문이 제시하는 대표 오류는 요청 한도에 따른 429, 잘못된 검색어에 따른 400, 인증 문제에 따른 401이며, 대부분의 오류에는 문제 파악을 돕는 설명 메시지가 포함된다고 안내한다.

6. 결과 유형·전문 분야와 Alexandria 도구 발견

sources는 일반 페이지인 web, 최근 기사인 news, 시각 콘텐츠인 images처럼 원하는 결과 유형을 선택하는 매개변수이고, categories는 github, research, pdf와 같은 전문 범주로 결과를 좁히는 데 사용된다. 두 매개변수는 각각 결과 유형과 전문 범주를 담당하므로, 동일한 의미의 필터로 취급하지 않는 것이 원문의 설명에 부합한다. sources에 alexandria를 추가하면 동일한 요청에서 Firecrawl Alexandria의 순위가 매겨진 데이터 도구도 검색하며, 해당 항목은 별도의 tools 배열로 반환된다. 도구의 출처는 공식 API, 라이선스가 있는 퍼블리셔, Firecrawl 자체 인덱스로 소개되고, 도구 발견 자체는 무료라고 명시된다. 다만 제공된 본문에는 Alexandria 도구를 발견한 이후 실제로 호출하는 구체적인 과정이나 비용 설명이 없으므로, 무료라는 표현을 이후의 모든 이용 단계로 확대할 근거는 없다.

7. 기간·지역·도메인으로 검색 범위 조절

tbs는 qdr:d, qdr:w, qdr:m 같은 Google 코드를 사용하는 시간 필터이며, 원문은 이 설정이 웹 검색 결과에만 적용된다는 제약을 명시한다. location은 Germany 같은 지역값으로 현지화된 결과를 요청하고, includeDomains는 특정 도메인으로 결과를 제한하며 excludeDomains는 지정한 도메인을 검색 결과에서 제외한다. includeDomains와 excludeDomains는 상호 배타적이므로 하나의 요청에서 함께 사용하는 설정은 지원되지 않는 것으로 설명된다. 고급 검색 예시는 2025년 머신러닝 프레임워크를 검색하면서 limit을 3, sources를 web과 news, timeout을 30000밀리초로 지정한다. 원문은 이러한 검색을 특정 웹사이트를 모르는 상태에서 최근 정보를 찾거나 여러 출처에 걸쳐 경쟁사와 시장 동향을 조사하는 데 활용할 수 있다고 설명한다.

8. scrape_options로 검색 결과의 전체 콘텐츠 추출

검색과 콘텐츠 추출을 결합하려면 search 호출에 scrape_options를 추가하며, Firecrawl은 검색어와 관련된 페이지를 찾은 뒤 각 결과에 scrape 엔드포인트를 자동으로 실행한다. 본문 예시는 웹 스크래핑 모범 사례를 검색하면서 결과 수를 2개로 제한하고, formats에 markdown과 links를 지정해 페이지 본문과 링크를 함께 받는다. 이 응답을 처리하는 코드는 제목과 URL을 result.metadata에서 읽고, result.markdown의 문자 수와 result.links의 항목 수를 출력한다. 첫 결과인 ZenRows의 문서는 본문 길이 25,234자와 링크 51개를 반환한 것으로 제시되어, 제목과 설명만 있는 기본 응답보다 많은 내용을 확보하는 모습을 보여준다. 두 번째 결과는 제목과 URL 일부까지만 제공되어 전체 추출 결과를 확인할 수 없으며, 이 예시만으로 모든 페이지에서 동일한 분량이나 완전성이 보장된다고 판단할 수는 없다.

🧾 핵심 주장 / 시사점

• 한 번의 API 호출은 사용자 측의 검색과 추출 연결 작업을 줄이지만, 내부적으로는 검색 결과별 scrape가 실행되므로 비용까지 단일 검색 요금으로 합쳐지는 것은 아니다.
• 검색어로 출처를 발견하는 단계와 특정 페이지 또는 사이트를 수집하는 단계가 구분되어 있어, 작업의 시작점과 필요한 범위에 따라 엔드포인트를 조합하는 방식이 적합하다.
• Alexandria는 탐색 대상을 웹페이지에서 데이터 도구로 확장하지만, 제공된 원문이 명시한 무료 범위는 도구 발견이며 후속 이용까지 설명하지는 않는다.

✅ 액션 아이템

• 대상 URL의 사전 파악 여부와 수집 범위에 따라 search·scrape·crawl의 사용 또는 조합을 결정한다.
• scrape_options의 본문 추출 필요성을 판단하고, 결과 10개당 2크레딧과 페이지별 추가 scrape 비용을 함께 검토한다.
• sources·categories와 기간·지역·도메인 필터를 검색 목적에 맞게 선택하고, tbs의 웹 결과 한정 및 includeDomains·excludeDomains의 동시 사용 불가 제약을 반영한다.

❓ 열린 질문

• 필요한 정보의 URL을 이미 알고 있는가, 아니면 search로 출처를 발견한 뒤 scrape 또는 crawl로 수집해야 하는가?
• 제목·URL·설명만으로 충분한가, 아니면 페이지별 추가 scrape 비용을 감수하고 scrape_options로 본문을 추출해야 하는가?
• sources에서 web·news·images만 선택하면 되는가, 아니면 Alexandria의 데이터 도구 탐색도 필요한가?