The Firecrawl Alexandria people API lets your coding agent find and enrich people through one Firecrawl key. You discover tools for free with v2/search, list candidates with Apollo people/search at 0 credits, reveal one with Apollo people/match at 30 credits, or enrich a known email with People Data Labs person/enrich at 60 credits. Every call goes through POST /v2/scrape.
Each step below comes twice: a prompt for Claude Code (or Codex) and the raw curl, so you can script it without an agent.
Qu'est-ce que l'API people de Firecrawl Alexandria
Alexandria est la bibliothèque de fournisseurs de données tierces de Firecrawl, accessible avec la clé API que vous utilisez déjà pour le scraping. Selon la documentation Alexandria, vous découvrez un outil, inspectez ses entrées et son prix, puis l'exécutez avec scrape. La découverte est gratuite ; l'exécution coûte les crédits indiqués sur l'outil.
La catégorie People contient 12 fournisseurs. Deux d'entre eux couvrent l'essentiel du travail de prospection :
| Fournisseur | Capacité | Crédits par appel | Ce que vous envoyez | Ce que vous recevez |
|---|---|---|---|---|
| Apollo | people/search |
0 | person_titles, q_keywords, q_organization_domains_list, per_page (max 100) |
Aperçus : prénom, nom masqué, poste, entreprise, has_email, id Apollo |
| Apollo | people/match |
30 | id issu de la recherche, ou linkedin_url, email, ou name plus domain |
Une personne résolue avec poste, historique et coordonnées |
| People Data Labs | person/enrich |
60 | email, profile, pdl_id et autres ; un simple nom renvoie une erreur 400 |
Un dossier de personne complet plus likelihood (1 à 10) |
Les prix sont ceux affichés à côté du bouton Run sur la page Apollo et la page People Data Labs le 4 novembre 2026. La page d'Apollo précise aussi qu'un échec de people/match « ne renvoie aucune personne et n'est pas facturé ».
Combien coûte une recherche de personne en dollars
La valeur d'un crédit dépend de votre forfait. Selon la page tarifaire de Firecrawl, Hobby coûte 19 $ par mois pour 5 000 crédits et Standard 99 $ par mois pour 100 000 crédits, tous deux facturés mensuellement.
| Appel | Crédits | Hobby (0,0038 $/crédit) | Standard (0,00099 $/crédit) |
|---|---|---|---|
| Recherche de découverte ou 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 $ |
Le calcul : 19 $ / 5 000 = 0,0038 $ par crédit, et 99 $ / 100 000 = 0,00099 $. Rechercher 100 aperçus et révéler les 20 meilleurs coûte 600 crédits, ce qui tient dans les 1 000 crédits mensuels du forfait Free. People Data Labs vous limite également à 50 000 appels API par an et par organisation, partagés entre les endpoints person et company, nouvelles tentatives incluses.
Étape 1 : connecter Claude Code à Firecrawl
La voie la plus rapide est l'installeur d'agent de Firecrawl. Il ajoute les compétences Firecrawl à chaque agent de codage qu'il détecte et vous connecte via le navigateur :
npx -y firecrawl-cli@latest init --all --browser
Redémarrez votre agent ensuite. Manuellement, c'est npm install -g firecrawl-cli et firecrawl login. Notre guide de la CLI Firecrawl couvre les deux, et le tutoriel Firecrawl MCP couvre le serveur MCP, qui expose la même boucle sous forme de firecrawl_search, firecrawl_find_tools et firecrawl_scrape.
Pour les exemples curl ci-dessous, exportez votre clé une fois :
export FIRECRAWL_API_KEY="fc-..." # never commit this
Étape 2 : découvrir gratuitement les outils people
Demandez d'abord à votre agent, puisque la découverte ne coûte rien :
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.
Sous le capot, c'est une recherche avec sources défini sur ["alexandria"] uniquement. Omettre "web" la garde gratuite, car les résultats web sont facturés :
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}'
La réponse liste des tools classés, chacun avec un fournisseur, une capacité et une description. Pour lire les entrées et les prix, l'agent exécute find-tools :
firecrawl find-tools --options '{"providers":["apollo","people-data-labs"],"level":"tools","expand":["options","response"]}' --include-costs
Étape 3 : rechercher des candidats dans Apollo à 0 crédit
La page d'Apollo conseille aux agents de toujours commencer ici : c'est gratuit et cela montre qui existe avant de dépenser quoi que ce soit.
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.
L'appel brut :
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
}
}
}'
Chaque aperçu porte un nom masqué et un id Apollo, l'entrée la plus fiable pour l'étape suivante.
Étape 4 : révéler une personne avec people/match
Ne payez maintenant que pour les personnes qui valent la peine d'être contactées, à 30 crédits par match :
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>"}}}'
Laissez les deux options de révélation désactivées sauf si vous en avez besoin. La page d'Apollo indique qu'un email personnel « est facturé en supplément » et qu'un numéro de téléphone est « bien plus cher que le match de base ».
Étape 5 : enrichir un email connu avec People Data Labs
Quand vous avez déjà un email, par exemple issu d'une inscription entrante, person/enrich renvoie un profil plus complet : email professionnel, poste, entreprise, URL LinkedIn, expérience et compétences.
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 va de 1 à 10 avec une valeur par défaut de 2. La page du fournisseur expose clairement le compromis : une 404 « est gratuite ici, alors qu'un mauvais enregistrement ne l'est pas ». Augmentez-la avant de boucler sur une liste.
Gérer THIRD_PARTY_DATA_TERMS_REQUIRED
Votre premier appel payant à un fournisseur peut échouer avec THIRD_PARTY_DATA_TERMS_REQUIRED. Selon la documentation, l'erreur contient un requiresAction.url, et un administrateur de l'organisation doit l'ouvrir et accepter les conditions de ce fournisseur avant qu'un appel passe.
Ne laissez pas l'agent cliquer dessus. La documentation précise que les agents ont besoin d'une autorisation explicite de l'utilisateur avant d'accepter des conditions, qui régissent la manière dont vous pouvez utiliser les données personnelles. Ajoutez une ligne à votre CLAUDE.md : « If a call returns THIRD_PARTY_DATA_TERMS_REQUIRED, stop and show me requiresAction.url. »
Lire la charge utile alexandria[].data
Les résultats reviennent dans un tableau alexandria, une entrée par appel d'outil, avec la charge utile du fournisseur sous data. En HTTP brut, tout le résultat du SDK est enveloppé dans un data de premier niveau, donc dans une réponse curl le match Apollo se trouve à data.alexandria[0].data.person :
curl -s https://api.firecrawl.dev/v2/scrape ... | jq '.data.alexandria[0].data.person | {name, title, email, linkedin_url}'
Deux vérifications empêchent les mauvaises lignes d'entrer dans votre CRM :
- Vérifiez chaque résultat pour des erreurs avant de lire
data. La documentation le dit explicitement ; un appel peut échouer alors que la requête HTTP réussit. - Traitez les emails fictifs comme manquants. Apollo note qu'un email non révélé peut revenir sous la forme littérale
email_not_unlocked@domain.com, même quandemail_statusindique verified.
Pour People Data Labs, la personne se trouve sous data à l'intérieur du résultat, à côté du status et du likelihood de l'enveloppe.
Envoyer un retour et récupérer un crédit
Alexandria vous paie pour vos retours. Chaque soumission rembourse 1 crédit quel que soit le vote, plafonné par jour UTC à 10 crédits par site web et 100 par équipe. Vous avez 20 minutes à partir du dernier appel Alexandria de votre équipe ; passé ce délai, vous obtenez FEEDBACK_WINDOW_EXPIRED.
Depuis la CLI, exécutez firecrawl alexandria feedback (voir --help pour les options). Via MCP, l'agent appelle firecrawl_feedback avec endpoint: "alexandria". Une ligne de prompt fonctionne bien : « If a result looks wrong or empty, send Alexandria feedback describing it. »
Laissez Claude Code surveiller ces appels avec Apidog CLI
Une fois qu'un script dépend du fait que people/search renvoie un id que people/match accepte, un champ renommé le casse en silence. Votre agent peut transformer les appels de ce guide en un scénario de non-régression dans Apidog CLI et le lancer selon un planning. Vous écrivez un seul prompt.
Configurez la CLI et sa compétence d'agent une fois :
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
Donnez ensuite ce prompt à 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.
L'agent lit chaque schéma de charge utile, le valide, puis exécute des commandes comme celles-ci :
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
Chaque exécution complète coûte 30 crédits pour le match, alors planifiez-la quotidiennement plutôt qu'à chaque commit. La référence apidog run liste les options de rapport et d'itération, et Apidog CLI dans Claude Code montre la configuration plus en détail. Le forfait Free d'Apidog couvre jusqu'à 4 utilisateurs.
FAQ
L'API people de Firecrawl Alexandria est-elle gratuite ? La découverte est gratuite, et Apollo people/search affichait 0 crédit le 4 novembre 2026. Révéler une personne coûte des crédits : 30 pour Apollo people/match et 60 pour People Data Labs person/enrich. Le forfait Free inclut 1 000 crédits par mois sans carte bancaire.
Ai-je besoin de comptes Apollo ou People Data Labs séparés ? Non. Alexandria exécute les deux via votre clé API Firecrawl et facture en crédits Firecrawl. Un administrateur de l'organisation doit toutefois accepter une fois les conditions de chaque fournisseur, ce que demande THIRD_PARTY_DATA_TERMS_REQUIRED.
Pourquoi ma réponse people/match affiche-t-elle email_not_unlocked@domain.com ? C'est le texte fictif d'Apollo pour un email qui n'a pas été révélé. Traitez-le comme indisponible, même si email_status indique verified.
Codex ou Cursor peuvent-ils exécuter ceci à la place de Claude Code ? Oui. npx -y firecrawl-cli@latest init --all configure chaque agent détecté, et les outils MCP fonctionnent dans n'importe quel client MCP. Les appels curl fonctionnent sans aucun agent.
Comment éviter de payer pour de mauvais matchs ? Recherchez avant de matcher, matchez par id Apollo plutôt que par nom, et réglez min_likelihood à 6 ou plus sur People Data Labs. Apollo ne facture pas un échec, et une 404 PDL est gratuite.