# Firecrawl Best Practices

**Last Updated:** 2026-02-26

Guidelines for using Firecrawl API effectively across blog, tools, and templates workflows.

## Extract vs Scrape

| Use Extract when | Use Scrape when |
|------------------|-----------------|
| You need structured data (headings, FAQs, tables) | Extract returns null or insufficient data |
| Competitor has schema-like content | Page is JS-heavy; Extract fails |
| Cost sensitivity (Extract can be cheaper for small schemas) | You need full markdown for parsing |

**Production flow:** Extract first → Scrape fallback. Both are tried automatically when cURL returns sparse content.

## Batch Scrape for Bulk Remediation

When many competitors are sparse:

1. Run `audit-firecrawl-sparse-competitors.php --output-urls=sparse.json`
2. Run `firecrawl-batch-remediate-sparse.php --input=sparse.json`
3. Batch Scrape uses 1 credit per URL; more efficient than sequential Extract+Scrape for large lists

## Map for Site Discovery

Use `firecrawlMapDomain($url, $search, $limit)` when:

- Analyzing key competitor site structure
- Finding content gaps (topics they cover that we don't)
- Filtering by `search` (e.g. "blog", "resources") to get relevant URLs

**Cost:** 1 credit per Map call regardless of URLs returned.

## Geo-Targeting (Germany)

- **Search:** Use `location: "Germany"` or `country: "DE"` for German SERP
- **Map:** Use `location: { country: "DE" }` when available

## maxAge for Faster Scraping

When competitor data freshness is not critical (e.g. batch runs, outline generation):

- Set `max_age_ms: 172800000` (2 days) in firecrawl-api-key.php
- Can speed scrapes by ~500% when cached versions exist
- Default `0` = always fresh

## Credit Monitoring

- Monitor usage via [Firecrawl dashboard](https://firecrawl.dev/app/usage)
- **3k plan:** Enable proactive (`proactive_enabled => true`, `firecrawl_proactive_top_n => 2`) for consistent quality. Pipeline defaults to remediation. Typical: 5–15 credits/post.
- Use `--no-firecrawl-remediate` on pipeline only when credits are tight
- Use `--dry-run` on collect scripts to avoid accidental credit burn

## References

- [FIRECRAWL_INTEGRATION.md](FIRECRAWL_INTEGRATION.md)
- [Firecrawl API docs](https://docs.firecrawl.dev/api-reference/introduction)