Files API & Token Counting — Citations & Files API

Pre-Flight Token Counting & The Files API

Anthropic pairs two core context primitives: the Files API (POST /v1/files), which lets you upload heavy PDFs, spreadsheets, or images once to receive a reusable file_id referenced across requests and sandboxed code execution containers, and /v1/messages/count_tokens, which calculates exact token consumption (including system instructions, messages, tools, images, and PDFs) before dispatching inference at zero cost.

Why Token Counting is Critical for Production

• Context Overflow Prevention: Validates that multi-turn dialogs plus RAG documents fit strictly inside the 1M-token context ceiling before runtime execution.
• Cost Forecasting & Tier Checks: Calculates exact input token counts ahead of batch jobs or tiered thresholds (such as Haiku 5.5's 100K-token pricing boundary).
• Prompt Caching Validation: Verifies whether a static prefix satisfies the 512-token minimum caching threshold across Claude 5.x models (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5) prior to applying cache_control breakpoints.

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

const anthropic = new Anthropic();

// Pre-flight check including tools and system instructions
const tokenEstimate = await anthropic.messages.countTokens({
  model: "claude-sonnet-5-5",
  system: "You are an expert security compliance auditor operating under SOC 2 Type II rules.",
  tools: [
    {
      name: "run_vulnerability_scan",
      description: "Trigger static code analysis scanner",
      input_schema: {
        type: "object",
        properties: { repo: { type: "string" }, branch: { type: "string" } },
        required: ["repo"]
      }
    }
  ],
  messages: [
    { role: "user", content: "Review our microservice authentication headers." }
  ]
});

console.log("Calculated Pre-Flight Tokens:", tokenEstimate.input_tokens);
if (tokenEstimate.input_tokens >= 512) {
  console.log("Eligible for Claude 5.x Prompt Caching prefix!");
}