Back to Blog

Claude Web Fetch API: Check Freshness and Missing Text

Tutorials and Guides6166
Claude Web Fetch API: Check Freshness and Missing Text

An assistant reads a vendor's release page and reports that an integration is supported. The answer contains a source link and sounds precise. A reviewer opens the page and finds an exception near the bottom: support excludes the deployment the customer actually uses. Was the assistant reading an older revision, a shortened page, or the correct text without understanding the exception?

Those are three different failures. A useful Claude web fetch API acceptance test makes them distinguishable before the answer reaches a customer. This article builds that test around a page your team controls, an explicit freshness requirement, and a small Python evidence gate. The example is synthetic; it reports no live gateway measurements and makes no claim that a particular route passes the test.

The goal is narrower than checking whether Claude can browse. You want to know whether the source evidence needed for a particular answer arrived, whether its revision satisfies your requirement, and whether your application notices when it does not.

What would count as evidence of the current page?

Start by defining “current” for the application. A daily product digest may accept yesterday's page. An answer about a change released this morning may require the newly published revision. Those requirements should produce different acceptance rules. A general promise of real-time information is too vague to test and too easy for a polished answer to appear to satisfy.

Use an application-owned fixture page with an explicit revision label. Place a normal statement near the top, a limiting condition deeper in the body, and a distinctive closing marker at the end. For example, revision r2 could say that a connector supports a protocol while the later exception excludes archived workspaces. Keep the expected revision and required evidence markers in the evaluator, separate from Claude's answer text.

Publish revision r1, run the initial evaluation, replace the page with r2, and then run the freshness cases. Record when your origin began serving the new revision. If a content delivery network is involved, independently verify the page exposed to a public client. Otherwise a stale result could come from your own publication path, and the experiment would unfairly attribute it to the model service.

A marker is a diagnostic instrument, not a universal completeness certificate. Finding the closing marker proves that particular text survived; it does not prove every intervening paragraph survived. Use several markers around the passages relevant to the task. For real documents without controlled markers, the corresponding evidence must come from reviewed passages, document revisions, or another source-specific verification method.

The Claude web-search source-control guide covers choosing acceptable sources. Here, assume the page is already approved. A trusted domain can still serve a stale version, an abbreviated view, or a page whose necessary exception did not reach the model.

Three settings that answer different questions

Anthropic's web fetch documentation documents use_cache: false for web_fetch_20260309 and later. It bypasses the fetch cache; the default allows caching. The same guide describes max_content_tokens as an approximate cap on text included in context, with truncation when the text exceeds it. That cap does not apply to binary PDF content. Fetch citations are optional and disabled by default.

Treat freshness, content volume, and citations as separate experiment variables. A larger content allowance cannot prove that a newer source revision was retrieved. Cache bypass cannot prove that a long exception section survived a content cap. A citation attached to the opening paragraph cannot establish that the conclusion considered a contradictory paragraph elsewhere in the document.

Prompt caching is also a separate mechanism. The official prompt caching guide describes reusing prompt prefixes. Its cache counters do not serve as a web-page revision detector. If your team already uses the gateway prompt-cache acceptance test, keep those measurements in a different column from source freshness. Similar names should not become shared success criteria.

Use a request fragment like this after checking that your selected model and route expose the tool version. Replace the URL with your controlled public fixture and supply the model through validated deployment configuration. This fragment deliberately contains no credential and does not execute a request.

python
def fetch_probe(model, url, fresh, content_limit):
    return {
        "model": model,
        "max_tokens": 800,
        "tools": [{
            "type": "web_fetch_20260309",
            "name": "web_fetch",
            "max_uses": 1,
            "use_cache": not fresh,
            "max_content_tokens": content_limit,
            "citations": {"enabled": True},
        }],
        "messages": [{
            "role": "user",
            "content": (
                f"Read {url}. Identify its release revision and explain "
                "whether the connector supports archived workspaces. "
                "Cite the relevant exception. Say when evidence is missing."
            ),
        }],
    }

probe = fetch_probe("MODEL_FROM_VERIFIED_CONFIG", "https://example.com/probe", True, 8000)
assert probe["tools"][0]["use_cache"] is False
assert probe["tools"][0]["max_content_tokens"] == 8000

Do not infer a universal optimum from the illustrative allowance of 8,000 tokens. Select the normal allowance from the document family you actually process, then include a deliberately constrained case to exercise missing-evidence handling. The smaller case is useful even if it fails: you are verifying that your service recognizes an inadequate source rather than silently accepting an answer.

Inspect the returned document before judging the prose

The Messages API reference defines a fetched result with its URL, document content, and a nullable retrieved_at timestamp. It also defines error results. Your adapter should preserve those native distinctions. A response reduced immediately to one string loses the material needed to investigate whether the failure happened during fetching or answering.

Record the application run ID, requested tool version, cache setting, text allowance, returned URL, reported retrieval time, and evaluator outcome. Keep a protected copy or permitted digest of the source evidence used by the evaluation. Store answer text separately. A log entry saying “HTTP success” cannot explain why the final answer overlooked a passage that was never available.

The timestamp is evidence about reported retrieval time, not a publisher-signed revision identifier. A recent timestamp and an old revision can coexist if an upstream source still serves old content. Conversely, a missing timestamp does not prove staleness. It means the proposed strict freshness gate cannot establish the condition and must return an unresolved outcome. The application's response should reflect that distinction.

Here is a conservative gate for the controlled text fixture. It requires one matching fetched result, a recent timezone-aware timestamp, the expected revision marker, and required evidence spans. All acceptance rules are application design choices. They are not Anthropic guarantees about webpage freshness or completeness.

python
from copy import deepcopy
from datetime import datetime, timezone

def source_gate(message, url, revision_marker, required_markers,
                now, max_age_seconds=300):
    results, errors = [], []
    for block in message.get("content", []):
        if block.get("type") != "web_fetch_tool_result":
            continue
        result = block.get("content", {})
        if result.get("type") == "web_fetch_tool_result_error":
            errors.append(result.get("error_code", "unknown"))
        elif result.get("type") == "web_fetch_result" and result.get("url") == url:
            results.append(result)
    if errors:
        return "fetch_error:" + ",".join(errors)
    if len(results) != 1:
        return "missing_or_ambiguous_source"
    result = results[0]
    try:
        retrieved = datetime.fromisoformat(result["retrieved_at"].replace("Z", "+00:00"))
        if retrieved.tzinfo is None:
            return "unverified_time"
        age = (now - retrieved).total_seconds()
    except (KeyError, AttributeError, TypeError, ValueError):
        return "unverified_time"
    if age < 0:
        return "clock_review"
    if age > max_age_seconds:
        return "older_than_policy"
    source = result.get("content", {}).get("source", {})
    if source.get("type") != "text":
        return "requires_document_review"
    text = source.get("data")
    if not isinstance(text, str):
        return "missing_text"
    if revision_marker not in text:
        return "revision_unverified"
    if any(marker not in text for marker in required_markers):
        return "required_evidence_missing"
    return "source_checks_passed"

url = "https://example.com/probe"
now = datetime(2026, 11, 16, 12, 0, tzinfo=timezone.utc)
fixture = {"content": [{
    "type": "web_fetch_tool_result", "tool_use_id": "synthetic-fetch-1",
    "content": {
        "type": "web_fetch_result", "url": url,
        "retrieved_at": "2026-11-16T11:59:00Z",
        "content": {"type": "document", "source": {
            "type": "text", "media_type": "text/plain",
            "data": "revision:r2\nEXCEPTION: archived workspaces excluded\nEND:r2",
        }},
    },
}]}
def check(message):
    return source_gate(message, url, "revision:r2",
                       ["EXCEPTION: archived workspaces excluded", "END:r2"], now)

assert check(fixture) == "source_checks_passed"
missing = deepcopy(fixture)
missing["content"][0]["content"]["content"]["source"]["data"] = "revision:r2"
assert check(missing) == "required_evidence_missing"
old = deepcopy(fixture)
old["content"][0]["content"]["retrieved_at"] = "2026-11-16T10:00:00Z"
assert check(old) == "older_than_policy"
wrong_revision = deepcopy(fixture)
wrong_revision["content"][0]["content"]["content"]["source"]["data"] = "revision:r1"
assert check(wrong_revision) == "revision_unverified"
pdf = deepcopy(fixture)
pdf["content"][0]["content"]["content"]["source"]["type"] = "base64"
assert check(pdf) == "requires_document_review"
assert check({"content": []}) == "missing_or_ambiguous_source"
no_time = deepcopy(fixture)
no_time["content"][0]["content"]["retrieved_at"] = None
assert check(no_time) == "unverified_time"
future = deepcopy(fixture)
future["content"][0]["content"]["retrieved_at"] = "2026-11-16T12:01:00Z"
assert check(future) == "clock_review"
error = {"content": [{"type": "web_fetch_tool_result", "content": {
    "type": "web_fetch_tool_result_error", "error_code": "url_not_accessible"}}]}
assert check(error) == "fetch_error:url_not_accessible"
print("source gate fixtures passed")

The evaluator rejects ambiguity instead of selecting the last result by accident. That is intentionally strict for a one-page experiment. A production research workflow needs a per-source ledger and a policy for acceptable retries or multiple revisions. Preserve every attempt so a later successful fetch does not erase the reason an earlier answer was blocked.

The code also sends binary sources to a separate review path. It does not search base64 strings for text markers or pretend that a text-only validator can assess a PDF. The examples were designed for offline fixture execution; their assertions check application behavior, not remote availability or model accuracy.

Why the PDF experiment needs a different boundary

The official PDF support guide documents request-level size and page constraints, including interaction with other request content. For a PDF experiment, inspect the applicable limits for the selected platform and request. Do not treat a text allowance as a guarantee that a binary document fits or that every page was understood.

Build a separate PDF fixture with page labels and the relevant exception on a known page. Record which revision produced the PDF bytes. Evaluate whether the answer cites and correctly interprets the required material, while preserving any returned document evidence available to your integration. If you need an immutable document version across repeated questions, the Claude Files document-reuse guide covers the related lifecycle problem.

That distinction helps diagnose a common operational mistake: replacing the URL with an uploaded file may improve version control, but it changes the workflow being tested. Label that as a different document-delivery path. Do not present its success as proof that live web fetching retrieved the current page correctly.

A citation is the start of review, not its conclusion

Anthropic's citations documentation describes source locations associated with generated text. Use those locations to inspect whether the cited passage supports the claim being displayed. In this experiment, acceptance requires the answer to account for the exclusion affecting archived workspaces. A citation to a general support statement is insufficient even when that statement is copied accurately.

Separate source acceptance from answer acceptance. The fixture gate can establish that expected evidence arrived, yet Claude can still misinterpret it. Conversely, a plausible correct answer does not excuse missing source evidence when the product promises a verifiable current-source answer. Report those outcomes independently so engineering knows whether to fix transport, document preparation, prompting, or evaluation.

For unattended monitoring, assign one evidence record per page revision and question. Reprocess only the items whose failure warrants another attempt. The batch recovery guide explains the related distinction between an API result and application acceptance. Applying that distinction here prevents a collection of completed requests from being mistaken for a collection of trustworthy updates.

What to require from a gateway evaluation

Ask for the exact Claude operation, tool version, retained response blocks, and supported settings. Test the smallest useful matrix: baseline revision with normal caching, changed revision with normal caching, changed revision with bypass, and changed revision with a constrained content allowance. Record observed outcomes without assuming the normal-cache case must be stale or the bypass case must satisfy your entire evidence policy.

If failover is enabled, include the route identity in each record. A fallback that returns ordinary text but omits the required fetched-document evidence cannot satisfy this acceptance contract. The routing architecture guide gives wider context for defining those boundaries. Here, keep the product outcome explicit: the application either has reviewable source evidence or says that verification remains incomplete.

For a 4SAPI evaluation, start with the integration overview, then check the current API documentation for this specific web-fetch operation. If it is available to the intended account, use a development token with the controlled fixture before expanding the workflow. The useful purchasing evidence is a preserved response and an explained acceptance decision, not simply a fluent answer with a link.

FAQ

Does use_cache: false prove the page is the publisher's latest revision?

No. It requests fetch-cache bypass on a supporting tool version. Verify the revision against the application's freshness requirement and the content actually served by the source.

Can max_content_tokens safely limit a large PDF?

It is a text-content control. Evaluate binary PDFs against the applicable document and request limits, and use a separate evidence review.

Should every missing marker trigger a retry with a larger limit?

No. First determine whether the page changed, the source was wrong, or the expected passage is absent. A larger request cannot recover evidence that the source no longer contains.

What did the offline code establish?

It checked deterministic acceptance and rejection behavior on synthetic response shapes. Live tool support, upstream freshness, and answer quality still require the controlled route evaluation.

Official references

  1. Anthropic: web fetch tool
  2. Anthropic: Messages API reference
  3. Anthropic: PDF support
  4. Anthropic: citations
  5. Anthropic: prompt caching
Tags:Claude web fetch API stale contentClaude web fetch use_cache falseClaude max_content_tokens truncationClaude fetched source freshnessClaude web fetch PDF limits

Recommended reading

Explore more frontier insights and industry know-how.