Anthropic Files API Guide 2026: Upload-Once vs Pasting — Which Bill Is Cheaper?

After Anthropic shipped the Files API, the natural assumption was that uploading a document once and referencing it by ID would save tokens — no more stuffing the doc into every request. The measured data says otherwise: the uploaded file's contents are still processed into every request at roughly 3,050 input tokens per question, and referencing the file adds about 25 tokens of overhead on top. Across five requests, upload-once cost 125 more input tokens than pasting. The Files API saves you time, not money. This post walks through the controlled experiment with full data.

1. Experiment Design: One Document, Three Approaches

To find out whether upload-once actually saves money, I wrote a fake API reference of about 1,200 words (the Ledgerline invoicing API) covering authentication, rate limits, idempotency, webhooks, bulk endpoints, and a sandbox. Then I designed five developer questions, each with a unique correct answer in the document — including details that are easy to miss: token scopes can't be edited after creation, the bulk endpoint has a separate rate limit, signature comparison runs in constant time, and there is a five-minute replay window. These are exactly the details a support bot must get right and a quick skim would miss. Three arms ran the same five questions with identical instructions on claude-sonnet-5: paste the doc into every request, upload once via the Files API, and a third prompt-caching arm that emerged from the results. The API reports token usage on every response, so each arm produced its own exact count.

// The experiment setup: a 1,200-word fake API reference
// (Ledgerline invoicing API) and five developer questions.
// Every question has a specific correct answer in the doc,
// including details that are easy to miss.

const questions = [
  "Can token scopes be edited after creation?",
  "What is the rate limit for the bulk endpoint?",
  "How does the webhook signature comparison work?",
  "What happens to idempotent retries after 5 minutes?",
  "Which sandbox endpoints allow test payments?",
];

// Three arms, identical instructions, claude-sonnet-5:
// Arm 1: paste the doc into every request
// Arm 2: upload the doc once via Files API, reference by ID
// Arm 3: prompt caching on the stable prefix

2. Two Early Pitfalls: Deprecated Temperature and a Crashy Thinking Block

Two things broke before the first run. The scripts originally set temperature to zero for reproducibility, and the API rejected it — temperature is deprecated on claude-sonnet-5. That is a quiet breaking change: any script written for older models with temperature=0 will fail at runtime instead of degrading gracefully, so pin your client version and read the deprecation notes before upgrading. Second, one response led with a thinking block instead of text, which crashed the printing code. Both fixes were one-liners, but they're a reminder: new APIs change defaults, and you shouldn't assume legacy parameters still work. If you are building tooling on top of these APIs, treat the response schema as versioned and validate the message shape before you access content fields.

3. The Upload Itself: Boringly Smooth

The upload was uneventful: one call, one file ID back, and the ID worked in every following request. The interesting part is the token accounting. The marketing doesn't say this, but the uploaded file's contents are still processed into every request at roughly 3,050 input tokens per question either way — referencing the file just adds about 25 tokens of metadata overhead per request. In other words, the file reference is a pointer that the server dereferences server-side, and the dereferenced content joins the context window every single time. There is no volume at which upload-once wins on tokens, because the file contents get resent every time; the only thing the upload saves is your client-side plumbing and the risk of transcription errors when pasting large documents.

// Arm 2: Anthropic Files API — upload once, reference by ID.
// One call, one file ID back, and the ID works in every
// following request.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const file = await client.files.create({
  file: fs.createReadStream("ledgerline-api-reference.md"),
  mimeType: "text/markdown",
});

console.log(file.id); // file_01ABC...

// Then use it in any conversation:
const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      { type: "file", file_id: file.id, title: "Ledgerline API Reference" },
      { type: "text", text: "Can token scopes be edited after creation?" },
    ],
  }],
});

4. The Measured Bill: Upload-Once Is Actually More Expensive

Across five requests, the paste arm totaled roughly 15,250 input tokens; the Files API arm totaled about 15,375 — 125 more, purely from the file-reference overhead. The real winner is prompt caching: mark the document as a stable cached prefix, and every follow-up request pays only the cache-read fee instead of re-tokenizing the whole document — an order-of-magnitude cost reduction on the document portion. The cache warms on the first request and then every subsequent turn in the same conversation reads from it. The practical guidance: if your document is stable across many requests, prompt caching is the clear economic choice; if it changes often or you only ask a handful of questions, the difference is negligible and convenience wins.

// Arm 1: paste the document into every request.
// Simple, no upload step — but the full doc is tokenized
// into every single request.

const doc = fs.readFileSync("ledgerline-api-reference.md", "utf8");
// ~3,050 input tokens per question either way — the file
// contents are still processed into every request.

for (const q of questions) {
  const msg = await client.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: doc + "\n\n" + q }],
  });
  console.log(msg.usage.input_tokens);
}

// Arm 3: prompt caching on the stable prefix — the approach
// that came out of the results. Cache the document prefix once,
// then every follow-up pays only the cache-read fee.

const msg = await client.messages.create({
  model: "claude-sonnet-5",
  max_tokens: 1024,
  messages: [{
    role: "user",
    content: [
      {
        type: "text",
        text: doc, // <-- stable prefix, gets cached
        cache_control: { type: "ephemeral" },
      },
      { type: "text", text: q },
    ],
  }],
});

// First request: full input tokens + cache write.
// Subsequent requests: small cache-read cost instead of
// re-tokenizing the whole document.

5. Accuracy: 15/15 in All Three Arms

The most counterintuitive result is accuracy: all fifteen answers were correct across all three arms. Uneditable token scopes, the separate bulk rate limit, constant-time signature comparison, the five-minute replay window — every subtle detail was caught everywhere. So the choice is purely about whether you value time or money: Files API for convenience, prompt caching for the bill. This also tells you something useful about model capability in 2026: given the right document, mid-tier models can answer fine-grained reference questions reliably; the bottleneck is context delivery and cost, not comprehension. That reframes the whole debate — you are optimizing plumbing, not intelligence.

// The measured truth (5 requests, claude-sonnet-5):
// Arm 1 (paste):     ~3,050 input tokens per question
// Arm 2 (files):     ~3,050 + ~25 tokens overhead per request
//                    -> upload-once cost 125 MORE input tokens
// Arm 3 (cache):     cheapest after the first warm-up call
//
// All 15 answers were correct in every arm — accuracy did
// not move. What changed was the bill.

const results = {
  arm1_paste: { correct: 5, inputTokens: 15250 },
  arm2_files: { correct: 5, inputTokens: 15375 },
  arm3_cache: { correct: 5, inputTokens: 5100 }, // after warm-up
};

// Verdict: Files API saves you TIME, not MONEY. For pure
// token economics, prompt caching is the real winner.

6. Practical Decision Guidance

If your document changes often and you need to reference it across requests long-term, the Files API's convenience is worth the token overhead. If the document is stable and you're running lots of requests, prompt caching wins overwhelmingly. If you're just asking a few questions, pasting is simplest and costs roughly the same. Measure your request volume and document churn first, then pick your approach — and re-measure after a few weeks, because both pricing and model behavior shift quickly in 2026. One more practical tip: whatever arm you choose, log the usage object on every response. The data will tell you when your assumptions about the API have quietly stopped being true.