docs: add "Verifying Freshness and Liveness" usage guide - #1145
Merged
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Add a dedicated, discoverable usage guide distinguishing freshness (controlled by maxAge) from liveness (a domain decision no scrape can assert). Covers the maxAge tradeoff, a freshness-sensitive action checklist, and a worked job-posting classification example in Node and Python showing that a scrape alone yields active/removed/unknown but never upgrades to "active" on its own. Registers the page under the Usage Guides nav subgroup and cross-links to /features/scrape and /features/fast-scraping. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
hmishra2250
force-pushed
the
docs/freshness-liveness-usage-guide
branch
from
July 20, 2026 09:59
b0e4fda to
e4cacb7
Compare
This was referenced Jul 20, 2026
hmishra2250
marked this pull request as ready for review
July 20, 2026 10:01
Contributor
|
Verified every claim in the guide against the scrape pipeline and both SDKs, and corrected the ones that did not hold: - Document where maxAge actually applies. It is honored on /scrape and in scrapeOptions for /crawl and /batch/scrape. /search applies its own freshness window to the pages it scrapes, and /parse always processes the file you supply and never serves or stores cached content, so the parameter has no effect on either. The guide previously implied it worked everywhere. - Use "cache" consistently instead of "index reuse", matching the wording already used in Faster Scraping and the Scrape reference. - Note the response-side freshness signals that exist: metadata cacheState and cachedAt. - Rewrite the comparison table row that conflated controlling freshness with proving it. - Fix the Node sample to the import form used across the v2 snippets (named Firecrawl export from "firecrawl"). - Add a cURL sample and order the CodeGroup Python/Node/cURL, matching the neighbouring usage guide and the Scrape reference. - Add section rules to match the Usage Guides page structure. The sourceURL/url distinction is confirmed correct: sourceURL is the URL you requested, url is the URL the engine reports for the response. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Faster Scraping already states that cached results still cost 1 credit per page, so describing the cache as cutting cost contradicted it. Also note that cacheState is absent from a maxAge: 0 response, since that request skips the cache and the field would otherwise look missing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Users need to understand two separate concerns:
What changed
maxAge: 0to bypass Firecrawl index reuse;This is documentation only. It does not change caching defaults, scrape behavior, response metadata, or the public cache contract.
Related: firecrawl/skills#5, firecrawl/firecrawl-mcp-server#321, firecrawl/firecrawl#4082.
Validation
docs.jsonparses successfully and contains the new nav entry.git diff --checkpasses.