How to Use Claude Opus 5.5's 1M-Token Context Window

Feed Claude Opus 5.5 an entire contract binder, a data catalog, or a quarter's worth of incident reports in one call, and it works. The model ships with a 1M-token context window on by default: no waitlist, no beta header, no special pricing tier. That's a real shift for document-heavy work, but "it fits" and "it's the right call" are different questions. This is how to use the Claude Opus 5.5 context window, and when to chunk instead.

Confirm you're not paying a long-context tax

On Claude Opus 5.5 (model ID claude-opus-5-5), the full 1M-token window is the default for every request, priced at the standard $4 per million input tokens and $20 per million output tokens. There's no separate long-context tier and no beta header: you pay the same rate whether the prompt is 2,000 tokens or 900,000. If you're migrating a workflow that needed a long-context beta flag on an older model, drop it. Anthropic's model docs confirm the window applies automatically.

Count tokens before you build the request

Before you load a folder of PDFs into a prompt, check what it actually costs. The token counting endpoint takes the same document blocks the Messages API does and returns an estimate for free.

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d @- <<EOF
{
  "model": "claude-opus-5-5",
  "messages": [{
    "role": "user",
    "content": [
      {
        "type": "document",
        "source": {
          "type": "base64",
          "media_type": "application/pdf",
          "data": "$(base64 -w0 contract.pdf)"
        }
      },
      {"type": "text", "text": "Summarize the termination clauses."}
    ]
  }]
}
EOF

This returns {"input_tokens": 41213} for that one contract. Run it across your whole set first, so you know whether you're using 40% of the window or 140% of it.

Load the document set into one request

For Claude API large documents, each file becomes a document content block, base64-encoded, followed by one text block with your actual question.

import base64, glob, anthropic

client = anthropic.Anthropic()

content = []
for path in sorted(glob.glob("contracts/*.pdf")):
    with open(path, "rb") as f:
        content.append({
            "type": "document",
            "source": {
                "type": "base64",
                "media_type": "application/pdf",
                "data": base64.standard_b64encode(f.read()).decode("utf-8"),
            },
        })

content.append({
    "type": "text",
    "text": "Across these contracts, list every clause with an auto-renewal term shorter than 90 days, and cite the source file for each.",
})

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": content}],
)
print(response.content[0].text)

Two hard limits apply regardless of token count: up to 600 PDF pages per request on a 1M-context model, and a 32MB cap on the whole request payload.

Cache the set for repeat questions

If you're going to ask the same document set several questions, like a data catalog you're querying all afternoon, mark the last document block with cache_control and Claude caches everything up to that point.

docs = content[:-1]
docs[-1]["cache_control"] = {"type": "ephemeral"}

first = docs + [{"type": "text", "text": "List every clause with an auto-renewal term shorter than 90 days."}]
response = client.messages.create(model="claude-opus-5-5", max_tokens=4096,
                                   messages=[{"role": "user", "content": first}])

second = docs + [{"type": "text", "text": "Now list every indemnification clause."}]
response2 = client.messages.create(model="claude-opus-5-5", max_tokens=4096,
                                    messages=[{"role": "user", "content": second}])

The second call reuses the cached prefix at $0.20 per million tokens instead of $4, as long as it lands inside the cache window. The default write is a 5-minute cache at $5/MTok; for a slower back-and-forth, use the 1-hour cache write at $8/MTok instead.

Handle the window when it's actually full

On Claude Opus 5.5, a request that runs out of room mid-generation doesn't error, it stops cleanly with a stop_reason you can check.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": content}],
)

if response.stop_reason == "model_context_window_exceeded":
    print("Trim the document set or split the request: generation hit the window limit mid-answer.")

If the input alone is already over 1M tokens, the API rejects the request outright with a 400 error before generation starts, so the token count from step one is your real gate.

Know when to stop stuffing and start retrieving

A 1M-token window is not a reason to abandon retrieval. Anthropic's own guidance on effective context engineering describes context rot: as token count climbs, recall and accuracy degrade even though the tokens are technically still in scope. A data catalog with 50,000 tables won't fit anyway, and one that barely fits will answer worse than a version narrowed to the 200 tables that matter. Use retrieval to pick the candidate set, then stuff the full text of just those documents into the window instead of summaries or fragments.

Gotchas

• A dense contract page usually runs 1,500 to 3,000 tokens, so a 400-page binder alone can eat half the window before you've even asked a question.
• The Messages and token-counting endpoints both cap requests at 32MB. Base64 inflates a PDF's raw bytes by about a third, so a folder of large scanned contracts can hit that ceiling before it hits the token limit.
• Claude Opus 5.5 uses the tokenizer introduced with Opus 4.7, which counts roughly 30% higher than older models for the same text. Don't reuse token estimates from a Sonnet 4.5 or earlier integration.
• Prompt caching has a 512-token minimum, so a handful of short documents isn't worth caching on its own.
• Cloud platforms cap requests below the direct API: Amazon Bedrock at 20MB and Google Cloud at 30MB, both under the API's 32MB.

For an FDE, that's the real unlock: skip the retrieval pipeline for anything that actually fits, and save it for the corpora that don't.