Firecrawl Alexandria 人员 API 让编码智能体通过一个 Firecrawl 密钥查找并补全人员资料。你可以使用 v2/search 免费发现工具,以 0 积分调用 Apollo people/search 列出候选人,再花 30 积分调用 Apollo people/match 查看一人的资料;如果已知邮箱,也可以花 60 积分调用 People Data Labs person/enrich 补全资料。具体工具调用通过 POST /v2/scrape 完成。
下文每一步都提供供 Claude Code(或 Codex)使用的提示词,以及原始 curl 命令,便于在没有智能体的情况下编写脚本。
AI Coding 交流群
如果你也在用 AI 写代码,或者正在研究 Cursor、Claude Code 这些工具,欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流,还有各种新工具和新玩法。
Firecrawl Alexandria 人员 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/积分) |
|---|---|---|---|
| 发现工具:search 或 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 积分,在免费套餐每月 1,000 积分的额度内。People Data Labs 还规定,每个组织每年最多调用 50,000 次 API,人员和公司端点共用额度,重试也计入其中。

第 1 步:将 Claude Code 连接到 Firecrawl
最快的方法是使用 Firecrawl 的智能体安装器。它会为检测到的编码智能体添加 Firecrawl 技能,并通过浏览器完成登录:
npx -y firecrawl-cli@latest init --all --browser
之后重启智能体。手动方式是执行 npm install -g firecrawl-cli 和 firecrawl login。Firecrawl MCP 服务器提供同一流程所需的 firecrawl_search、firecrawl_find_tools 和 firecrawl_scrape 工具。
要执行下文的 curl 示例,先设置密钥:
export FIRECRAWL_API_KEY="fc-..." # never commit this
第 2 步:免费发现人员工具
可以先询问智能体,因为发现工具无需付费:
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 网址、经历和技能。
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;组织管理员必须打开该地址,接受该提供商的条款,后续调用才能继续。
不要让智能体自行接受。文档要求智能体在接受条款前获得用户明确授权,因为条款规定了个人数据的使用方式。可以在 CLAUDE.md 中添加一句:“If a call returns THIRD_PARTY_DATA_TERMS_REQUIRED, stop and show me requiresAction.url.”
读取 alexandria[].data 载荷
结果放在 alexandria 数组中,每次工具调用对应一项,提供商返回的载荷位于 data。原始 HTTP 响应还会用顶层 data 包裹整个 SDK 结果,所以在 curl 响应里,Apollo 的匹配结果位于 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_not_unlocked@domain.com返回,即使email_status显示 verified 也是如此。
对于 People Data Labs,人员资料位于结果内部的 data,与结果外层的 status、likelihood 并列。
提交反馈并获得积分返还
Alexandria 会为反馈返还积分。每次提交无论评分如何,都返还 1 积分;按 UTC 日期计算,每个网站最多返还 10 积分,每个团队最多返还 100 积分。反馈窗口从团队最近一次 Alexandria 调用开始计算,持续 20 分钟,超时会返回 FEEDBACK_WINDOW_EXPIRED。
在 CLI 中可运行 firecrawl alexandria feedback(参数见 --help);通过 MCP,智能体可调用 firecrawl_feedback 并设置 endpoint: "alexandria"。提示词可以写:“If a result looks wrong or empty, send Alexandria feedback describing it.”
用测试场景守护这些 API 调用
当脚本依赖 people/search 返回可用于 people/match 的 id 时,字段改名可能悄悄破坏流程。可以使用 Apifox CLI 将上述调用组织成定时运行的回归测试场景。
先安装 CLI 及其智能体技能:
npm install -g apifox-cli@latest
apifox auth login --with-token <YOUR_APIFOX_TOKEN>
apifox skill install
然后向 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 Apifox
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.
原文设想智能体读取各载荷 schema、完成验证,再执行类似命令:
apifox import --project <projectId> --format openapi --file ./firecrawl-people.json
apifox environment create Firecrawl --project <projectId> --base-url https://api.firecrawl.dev
apifox test-scenario create --project <projectId> --name "Alexandria people" --folder-id <folderId> --priority <priority>
apifox cli-schema get test-scenario-update
apifox cli-schema validate test-scenario-update --file ./people-scenario.json
apifox test-scenario update <scenarioId> --project <projectId> --file ./people-scenario.json
apifox run -t <scenarioId> --project <projectId> -e <envId> \
--env-var "FIRECRAWL_API_KEY=$FIRECRAWL_API_KEY" -r cli,junit

每次完整运行都需要为 match 支付 30 积分,因此可以按天运行,而非每次提交都运行。
常见问题
Firecrawl Alexandria 人员 API 免费吗? 发现工具免费;截至 2026 年 11 月 4 日,Apollo people/search 显示为 0 积分。查看完整人员资料需要积分:Apollo people/match 为 30,People Data Labs person/enrich 为 60。免费套餐每月含 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,也应视为不可用。
Codex 或 Cursor 能代替 Claude Code 吗? 可以。npx -y firecrawl-cli@latest init --all 会配置检测到的智能体;MCP 工具可在任何 MCP 客户端使用。不使用智能体也可以直接运行 curl 命令。
如何避免为错误匹配付费? 先搜索,再通过 Apollo id 而非姓名进行匹配,并将 People Data Labs 的 min_likelihood 设为 6 或更高。Apollo 未匹配到人时不收费,PDL 的 404 也免费。