Firecrawl Alexandria people API를 사용하면 코딩 에이전트가 하나의 Firecrawl 키로 사람을 찾고 정보를 보강할 수 있습니다. v2/search로 도구를 무료로 탐색하고, Apollo people/search로 0 크레딧에 후보를 나열하고, Apollo people/match로 30 크레딧에 한 명을 공개하거나, 알려진 이메일을 People Data Labs person/enrich로 60 크레딧에 보강할 수 있습니다. 모든 호출은 POST /v2/scrape를 통해 이루어집니다.
아래의 각 단계는 두 번씩 나옵니다. Claude Code(또는 Codex)용 프롬프트와 원시 curl이며, 이를 통해 에이전트 없이도 스크립트를 작성할 수 있습니다.
Firecrawl Alexandria people API란 무엇인가
Alexandria는 Firecrawl의 서드파티 데이터 제공자 라이브러리로, 스크래핑에 이미 사용 중인 API 키로 접근할 수 있습니다. Alexandria 문서에 따르면, 도구를 탐색하고 입력과 가격을 확인한 다음 scrape로 실행합니다. 탐색은 무료이며, 실행에는 도구에 표시된 크레딧이 소요됩니다.
People 카테고리에는 12개의 제공자가 있습니다. 그중 두 곳이 대부분의 잠재고객 발굴 작업을 처리합니다:
| 제공자 | 기능 | 호출당 크레딧 | 보내는 것 | 받는 것 |
|---|---|---|---|---|
| Apollo | people/search |
0 | person_titles, q_keywords, q_organization_domains_list, per_page (최대 100) |
미리보기: 이름, 마스킹된 성, 직함, 회사, has_email, Apollo id |
| Apollo | people/match |
30 | 검색에서 얻은 id, 또는 linkedin_url, email, 또는 name과 domain |
직함, 이력, 연락처 정보가 포함된 확정된 한 명의 인물 |
| People Data Labs | person/enrich |
60 | email, profile, pdl_id 등; 이름만 보내면 400이 반환됨 |
전체 인물 레코드와 likelihood (1~10) |
가격은 2026년 11월 4일 Apollo 페이지와 People Data Labs 페이지의 Run 버튼 옆에 표시된 값입니다. Apollo 페이지에는 people/match가 실패하면 "인물이 반환되지 않고 청구되지 않는다"고도 나와 있습니다.
사람 조회에 드는 비용(달러)
크레딧의 가치는 요금제에 따라 다릅니다. Firecrawl 가격 페이지에 따르면, Hobby는 월 $19에 5,000 크레딧이고 Standard는 월 $99에 100,000 크레딧이며, 둘 다 월 단위로 청구됩니다.
| 호출 | 크레딧 | Hobby ($0.0038/크레딧) | Standard ($0.00099/크레딧) |
|---|---|---|---|
| 탐색 검색 또는 find-tools | 0 | $0 | $0 |
Apollo people/search |
0 | $0 | $0 |
Apollo people/match |
30 | $0.114 | $0.0297 |
PDL person/enrich |
60 | $0.228 | $0.0594 |
계산은 이렇습니다: $19 / 5,000 = 크레딧당 $0.0038, 그리고 $99 / 100,000 = $0.00099. 미리보기 100개를 검색하고 가장 좋은 20명을 공개하면 600 크레딧이 들며, 이는 Free 요금제의 월 1,000 크레딧 안에 들어갑니다. People Data Labs는 또한 조직당 연간 API 호출을 50,000회로 제한하며, 이는 재시도를 포함해 person 및 company 엔드포인트 전체에 공유됩니다.
1단계: Claude Code를 Firecrawl에 연결하기
가장 빠른 방법은 Firecrawl의 에이전트 설치 프로그램입니다. 감지된 모든 코딩 에이전트에 Firecrawl 스킬을 추가하고 브라우저를 통해 로그인시킵니다:
npx -y firecrawl-cli@latest init --all --browser
그 후 에이전트를 재시작하세요. 수동으로 하려면 npm install -g firecrawl-cli와 firecrawl login입니다. Firecrawl CLI 가이드에서 두 가지를 모두 다루며, Firecrawl MCP 워크스루에서는 동일한 루프를 firecrawl_search, firecrawl_find_tools, firecrawl_scrape로 노출하는 MCP 서버를 다룹니다.
아래 curl 예제를 위해 키를 한 번 내보내세요:
export FIRECRAWL_API_KEY="fc-..." # never commit this
2단계: people 도구를 무료로 탐색하기
탐색은 비용이 들지 않으니 먼저 에이전트에게 요청하세요:
Use Firecrawl Alexandria to find tools that search people by job title and
company, and tools that enrich a person from an email. Inspect Apollo and
People Data Labs with find-tools and show me each capability's inputs and
credit price before you run anything.
내부적으로는 sources를 ["alexandria"]로만 설정한 검색입니다. "web"을 빼면 무료로 유지되는데, 웹 결과는 청구되기 때문입니다:
curl https://api.firecrawl.dev/v2/search \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "find people by job title and company", "sources": ["alexandria"], "limit": 5}'
응답에는 순위가 매겨진 tools가 나열되며, 각각 제공자, 기능, 설명이 있습니다. 입력과 가격을 확인하려면 에이전트가 find-tools를 실행합니다:
firecrawl find-tools --options '{"providers":["apollo","people-data-labs"],"level":"tools","expand":["options","response"]}' --include-costs
3단계: 0 크레딧으로 Apollo에서 후보 검색하기
Apollo 페이지는 에이전트에게 항상 여기서 시작하라고 알려줍니다. 무료이며, 비용을 쓰기 전에 누가 존재하는지 보여줍니다.
Run Apollo people/search through Firecrawl Alexandria for "VP of Sales" and
"Head of Revenue" at stripe.com and linear.app, 25 per page. Show name,
title, company and has_email. Don't reveal anyone yet.
원시 호출은 다음과 같습니다:
curl https://api.firecrawl.dev/v2/scrape \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"alexandria": {
"provider": "apollo",
"capability": "people/search",
"options": {
"person_titles": ["VP of Sales", "Head of Revenue"],
"q_organization_domains_list": ["stripe.com", "linear.app"],
"page": 1,
"per_page": 25
}
}
}'
각 미리보기에는 마스킹된 성과 Apollo id가 포함되며, 이것이 다음 단계에 가장 신뢰할 수 있는 입력입니다.
4단계: people/match로 한 명 공개하기
이제 연락할 가치가 있는 사람에게만 비용을 지불하세요. 매치당 30 크레딧입니다:
For the 3 previews with has_email true, run Apollo people/match with their
id. Don't set reveal_personal_emails or reveal_phone_number.
curl https://api.firecrawl.dev/v2/scrape \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alexandria": {"provider": "apollo", "capability": "people/match", "options": {"id": "<apollo_id>"}}}'
필요하지 않다면 두 개의 reveal 플래그를 켜지 마세요. Apollo 페이지에 따르면 개인 이메일은 "추가 청구"되고 전화번호는 "기본 매치보다 상당히 더 비쌉니다."
5단계: People Data Labs로 알려진 이메일 보강하기
예를 들어 인바운드 가입 등으로 이미 이메일을 가지고 있다면, person/enrich는 더 풍부한 프로필을 반환합니다: 업무 이메일, 직함, 회사, LinkedIn URL, 경력, 스킬 등입니다.
Enrich jane@example.com with People Data Labs person/enrich through
Firecrawl Alexandria. Set min_likelihood to 6 so a weak match comes back
as a 404 instead of a wrong record.
curl https://api.firecrawl.dev/v2/scrape \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"alexandria": {"provider": "people-data-labs", "capability": "person/enrich", "options": {"email": "jane@example.com", "min_likelihood": 6}}}'
min_likelihood는 1부터 10까지이며 기본값은 2입니다. 제공자 페이지는 그 트레이드오프를 명확히 설명합니다: 404는 "여기서는 무료이고 잘못된 레코드는 그렇지 않습니다." 목록을 반복 처리하기 전에 이 값을 높이세요.
THIRD_PARTY_DATA_TERMS_REQUIRED 처리하기
제공자에 대한 첫 유료 호출은 THIRD_PARTY_DATA_TERMS_REQUIRED로 실패할 수 있습니다. 문서에 따르면 이 오류는 requiresAction.url을 포함하며, 어떤 호출이든 통과하려면 조직 관리자가 이 URL을 열고 해당 제공자의 약관에 동의해야 합니다.
에이전트가 이를 클릭하게 두지 마세요. 문서에서는 에이전트가 약관에 동의하기 전에 명시적인 사용자 승인이 필요하다고 말합니다. 이 약관은 개인 데이터를 어떻게 사용할 수 있는지를 규정합니다. CLAUDE.md에 한 줄을 추가하세요: "호출이 THIRD_PARTY_DATA_TERMS_REQUIRED를 반환하면 멈추고 requiresAction.url을 보여줘."
alexandria[].data 페이로드 읽기
결과는 alexandria 배열로 반환되며, 도구 호출당 하나의 항목이 있고 제공자의 페이로드는 data 아래에 있습니다. 원시 HTTP는 전체 SDK 결과를 최상위 data로 감싸므로, curl 응답에서 Apollo match는 data.alexandria[0].data.person에 위치합니다:
curl -s https://api.firecrawl.dev/v2/scrape ... | jq '.data.alexandria[0].data.person | {name, title, email, linkedin_url}'
두 가지 확인으로 잘못된 행이 CRM에 들어가는 것을 막을 수 있습니다:
data를 읽기 전에 각 결과의 오류를 확인하세요. 문서에서 이를 명확히 언급합니다. HTTP 요청은 성공했는데 단일 호출은 실패할 수 있습니다.- 플레이스홀더 이메일은 없는 것으로 취급하세요. Apollo는
email_status가 verified라고 해도, 공개되지 않은 이메일이 문자 그대로email_not_unlocked@domain.com으로 반환될 수 있다고 언급합니다.
People Data Labs의 경우, 인물은 결과 내부의 data 아래에 있으며, 엔벨로프의 status와 likelihood 옆에 있습니다.
피드백을 보내고 크레딧 돌려받기
Alexandria는 피드백에 대해 보상합니다. 각 제출은 평점에 관계없이 1 크레딧을 환불하며, UTC 기준 하루에 웹사이트당 10 크레딧, 팀당 100 크레딧으로 제한됩니다. 팀의 최신 Alexandria 호출로부터 20분이 주어지며, 그 이후에는 FEEDBACK_WINDOW_EXPIRED가 발생합니다.
CLI에서는 firecrawl alexandria feedback을 실행하세요(옵션은 --help를 참조). MCP에서는 에이전트가 endpoint: "alexandria"와 함께 firecrawl_feedback을 호출합니다. 프롬프트 한 줄이 효과적입니다: "결과가 잘못되었거나 비어 보이면 이를 설명하는 Alexandria 피드백을 보내줘."
Apidog CLI로 Claude Code가 이 호출들을 보호하게 하기
스크립트가 people/match가 받아들이는 id를 people/search가 반환하는 것에 의존하게 되면, 이름이 바뀐 필드가 조용히 이를 망가뜨립니다. 에이전트는 이 가이드의 호출을 Apidog CLI의 회귀 시나리오로 바꾸고 일정에 따라 실행할 수 있습니다. 프롬프트 하나만 작성하면 됩니다.
CLI와 그 에이전트 스킬을 한 번 설정하세요:
npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
npx -y skills add https://apidog.com # pick Claude Code or Codex when prompted
그런 다음 Claude Code에 다음 프롬프트를 주세요:
Write an OpenAPI 3 file for three Firecrawl calls from this guide:
POST /v2/search with sources ["alexandria"], POST /v2/scrape for apollo
people/search (per_page 1), and POST /v2/scrape for apollo people/match.
All send Authorization: Bearer {{FIRECRAWL_API_KEY}}. Import it into Apidog
project <projectId> and create a "Firecrawl" environment for
https://api.firecrawl.dev. Build a test scenario that runs the three in
order, saves data.alexandria[0].data.people[0].id as personId and passes it
to people/match, and asserts status 200, no result error, and a person
object on the match. Run it and summarize failures.
에이전트는 각 페이로드 스키마를 읽고 검증한 다음, 다음과 같은 명령을 실행합니다:
apidog import --project <projectId> --format openapi --file ./firecrawl-people.json
apidog environment create Firecrawl --project <projectId> --base-url https://api.firecrawl.dev
apidog test-scenario create --project <projectId> --name "Alexandria people" --folder-id <folderId> --priority <priority>
apidog cli-schema get test-scenario-update
apidog cli-schema validate test-scenario-update --file ./people-scenario.json
apidog test-scenario update <scenarioId> --project <projectId> --file ./people-scenario.json
apidog run -t <scenarioId> --project <projectId> -e <envId> \
--env-var "FIRECRAWL_API_KEY=$FIRECRAWL_API_KEY" -r cli,junit
전체 실행마다 match에 30 크레딧이 들므로, 커밋마다가 아니라 매일 예약 실행하세요. apidog run 레퍼런스에는 리포트 및 반복 플래그가 나열되어 있고, Claude Code에서의 Apidog CLI에서는 설정을 더 자세히 보여줍니다. Apidog의 Free 요금제는 최대 4명의 사용자를 지원합니다.
FAQ
Firecrawl Alexandria people API는 무료인가요? 탐색은 무료이며, Apollo people/search는 2026년 11월 4일 기준 0 크레딧으로 표시되었습니다. 사람을 공개하는 데는 크레딧이 듭니다: Apollo people/match는 30, People Data Labs person/enrich는 60입니다. Free 요금제는 카드 없이 월 1,000 크레딧을 포함합니다.
별도의 Apollo 또는 People Data Labs 계정이 필요한가요? 아닙니다. Alexandria는 둘 다 Firecrawl API 키를 통해 실행하고 Firecrawl 크레딧으로 청구합니다. 다만 조직 관리자가 각 제공자의 약관에 한 번 동의해야 하며, 이것이 THIRD_PARTY_DATA_TERMS_REQUIRED가 요구하는 것입니다.
people/match 응답에 email_not_unlocked@domain.com이 표시되는 이유는 무엇인가요? 공개되지 않은 이메일에 대한 Apollo의 플레이스홀더입니다. email_status가 verified라고 해도 사용할 수 없는 것으로 취급하세요.
Claude Code 대신 Codex나 Cursor로 실행할 수 있나요? 예. npx -y firecrawl-cli@latest init --all은 감지된 모든 에이전트를 설정하며, MCP 도구는 모든 MCP 클라이언트에서 작동합니다. curl 호출은 에이전트 없이도 작동합니다.
잘못된 매치에 비용을 지불하지 않으려면 어떻게 해야 하나요? 매치하기 전에 검색하고, 이름이 아니라 Apollo id로 매치하고, People Data Labs에서 min_likelihood를 6 이상으로 설정하세요. Apollo는 실패 건을 청구하지 않고, PDL 404는 무료입니다.