API / SDK
Developer guides for the Claude API and SDKs — auth, streaming, tool use, cost control, and agent building, with working code and production-ready patterns.
When Stripe's Bill and Your Own Ledger Drift Apart: Field Notes on Metered Billing for Claude API
Usage-based billing for Claude API looks clean until month-end, when Stripe's total and your own usage ledger quietly disagree. Here are the field-tested patterns for idempotent meter events, reconciliation jobs, and pricing-change-proof credits.
My Morning Batch Was Missing the Prompt Cache Every Time — Warming Cadence and the Break-Even Math for the 1-Hour TTL
Jobs that run a few hours apart cold-miss the prompt cache even with a 1-hour TTL. Here is how to back out the right warming interval from the TTL, and how to write the break-even formula that decides whether warming pays off — with numbers from a four-site daily generation pipeline.
When Thinking Is Always On, Prefill Quietly Stops Working — Fixing Streaming and Token Budgets for Fable 5
Fable 5 thinks by default. Prefill no longer applies, the first streamed block isn't text, and max_tokens has to leave room for reasoning. Here is how I fixed those three broken assumptions in my own automated publishing pipeline.
When the Same Model Has a Different Name Everywhere — Designing a Cross-Provider Model Identity Resolver for Claude
Now that Fable 5 is available on the API, Bedrock, and Vertex at once, the same model carries a different identifier on each. Here is how to untangle hardcoded model strings with a small resolver that maps logical names to physical IDs, carries capability flags, and verifies identifiers at startup.
An Unattended Agent That Wakes Up to a Blank Machine Every Time
A scheduled, unattended agent wakes up on a fresh disposable machine every run: paths it cannot write to, a filesystem that has not finished booting, a working directory that has vanished. Here is how to design state recovery into the first thirty seconds, drawn from real operational logs.
When Claude API Prompt Caching Quietly Stops Hitting in Production — Field Notes on TTL and Measured Savings
Prompt caching works beautifully the day you ship it, then quietly stops hitting in production. The five things that break the prefix, how to choose between 5-minute and 1-hour TTL, and how to measure real savings from usage instead of guessing.
Your Claude Files API Storage Is Quietly Filling Up — Dedup With a Content-Hash Ledger and Reap the Orphans
Use the Files API in an automated pipeline and the same file gets uploaded again and again while orphaned files pile up unnoticed. Here is a content-hash dedup ledger plus an orphan GC design, with working code.
Drop Your Static Claude API Keys: Moving CI and Production to Keyless Auth with Workload Identity Federation
Workload Identity Federation is now generally available on the Claude Platform. This guide walks through replacing long-lived sk-ant- keys with short-lived OIDC tokens, including keyless GitHub Actions auth, the migration steps, and token refresh design.
When Your Claude API Cost Math Doesn't Match the Bill: Accounting for the Four Token Buckets
Turn on prompt caching and your homegrown cost tally drifts from the console bill. Here is how to weight the four token buckets the usage object returns and build a ledger you can reconcile.
Claude API Streaming Breaks the "Everything Arrives" Assumption — Field Notes on Recovering from Partial Failure
Once concurrency climbs, Claude API streams disconnect mid-response, replay events, and emit half-finished tool arguments. Treating partial failure as the norm rather than an anomaly, here is how I rebuilt the implementation and monitoring to recover quietly.
Putting a Ceiling on the pause_turn Loop: Running Long Server Tools Safely Unattended
A production design for continuing pause_turn safely in unattended runs, where long server tools like web_search and code execution are involved. Covers branching all four stop_reason values in one loop, capping continuations and wall-clock time, and accumulating usage across paused segments.
Surviving the 90-Second Code Execution Cell Limit with Checkpointed Chunking
Claude's code execution tool now enforces a 90-second per-cell limit. Here is how to keep a long batch from getting cut off there: persist progress to the container filesystem and resume across cells, with working code for timing, idempotent checkpoints, and knowing when to offload.
Connecting Managed Agents to Services You Don't Want to Expose: MCP Tunnel Design
How to connect Claude Managed Agents to an internal MCP server that is never exposed to the public internet. We cover the MCP tunnel, self-hosted sandboxes, authorization boundaries, and graceful degradation when things break.
Don't Carry Search Results Twice: Trimming Consumed Blocks with response_inclusion
When an agent runs dynamic filtering, output tokens balloon because the raw search-result blocks a code execution call already consumed get echoed back into the response. Here is when response_inclusion: excluded is safe to use, when you must keep full, with implementation and a decision table.
Reserving Priority Capacity for User Traffic with service_tier
If you pay for Priority Tier but your user-facing responses still slow down at peak, the culprit is often your own background jobs eating the priority pool. Here is how to read service_tier, prove the contention, and isolate background work.
Routing the effort Parameter Per Stage to Balance Claude's Output Cost and Latency
Claude's effort parameter governs all output tokens — thinking, prose, and tool calls. This guide replaces a blanket high setting with per-stage tiers and a dynamic router, grounded in measurements from a solo developer's automation pipeline.
Running Subagents in Parallel Without One Failure Sinking the Whole Run
A fan-out / fan-in design for running several subagents in parallel, covering token budgeting, a result contract, and partial-failure handling. Includes an implementation where one branch can fail without stopping the rest, plus measured numbers.
Putting Cloudflare AI Gateway in Front of Claude Made the Numbers I Needed Disappear — Field Notes on Instrumentation
After putting Cloudflare AI Gateway in front of Claude API, here is where I actually got stung — cost attribution, semantic-cache false hits, fallback quietly lowering quality, and budgets that don't really stop anything — with the code I used to fix each.
Grounding Claude on Your Own Knowledge Base with search_result Blocks
How to stop your own RAG setup from losing track of which article it cited, using Claude's search_result content block and structured citations — with real numbers from running it across four sites.
When Your Claude × Playwright Browser Agent Fails While Reporting Success — Verifying Actions and Catching UI Drift
A vision-driven Claude + Playwright browser agent fails quietly: it reports success while nothing actually changed. Here is how to stop trusting self-reports, verify each action against the goal, and detect UI drift before it breaks you.
When Your Claude API Response Cache Returns Stale Answers and Near-Miss Wrong Ones — Field Notes on Freshness and False-Hit Suppression
A Claude API response cache improves latency and cost immediately, but the problems that hurt in production are not average hit rate — they are stale hits and semantic false hits. Here is the key design, freshness management, false-hit suppression, and observability that keep a cache honest.
When Claude API Extracts the Wrong Value With Full Confidence — Designing the Verification Layer
When you extract invoices or contracts with Claude API, the scariest failure isn't an exception — it's plausible-but-wrong JSON. Here is how I build a verification layer that catches silent extraction errors with schema checks, arithmetic reconciliation, and dual-extraction agreement, in TypeScript.
Stop Terminology Drift in Localized Apps: A Consistent Localizable.strings Pipeline with the Batch API and a Cached Glossary
Translating UI strings one at a time invites inconsistency. Pair Claude's Message Batches API with a prompt-cached glossary to translate Localizable.strings across 10+ languages consistently, with measured costs and the pitfalls I hit in production.
Making the Numbers Add Up in a Multi-Tenant Claude API SaaS — Field Notes on Isolation and Cost Attribution
The first thing that breaks when you make a Claude API SaaS multi-tenant is the month-end reconciliation. Here are field notes on a single metering chokepoint, atomic counters, reconciling against Anthropic's bill, and proving tenant isolation with adversarial tests — with production TypeScript.
Keep a Decision Rationale Ledger for Autonomous Agents — So You Can Explain 'Why' Later
When an autonomous agent takes hard-to-reverse actions like a production deploy or a bulk delete, capture the chosen option, rejected alternatives, and assumptions in a structured ledger. Includes structured output, an append-only log, and tiering by impact.
Taming Token Bloat in Long-Running Agents with Context Editing and the Memory Tool
For long-running agents whose input tokens balloon as tool results pile up, here is how to pair context editing with the memory tool and measure the savings with count_tokens, including a working backend implementation.
Trusting Claude's Structured Output in Production — Validation Gates and Repair Loops
When Claude's structured output breaks 'occasionally' in production, combine tool-use enforcement, a schema validation gate, a single repair loop, and a graceful degradation fallback to eliminate broken JSON from your operations — with working TypeScript code.
Confirm Your Model Actually Responds Before a Scheduled Run Begins
A model you configured can be gone before your nightly job even wakes up. Tell retirement, withdrawal, and regional restriction apart with a single startup probe, then rewrite the run config to an eligible model — with complete, working TypeScript.
PII Masking for Claude API Lives or Dies on the Ledger — Restore, Encrypt, Measure
The hard part of masking PII before Claude API isn't detection — it's operating the token ledger you restore from. Encrypted storage, multi-instance sharing, and a daily leak-rate loop, with working code.
On the day the billing change took effect, I added per-stage cost metering to my headless runs
The June 15 billing change moved headless runs and agent delegation onto monthly credits. Here is a thin metering layer that records token usage per stage tag from response.usage and emits a daily cost report, with working code.
Centralizing the anthropic-beta Header So a Retired Beta Won't Kill Your Batch
Scattered anthropic-beta headers turn a beta retirement or GA graduation into a 400 that takes down an entire batch. A small capability registry, a startup preflight, and tiered fallback keep your pipeline running across feature generations.
When a Model Disappears Without Warning: A State Machine for Retirement, Withdrawal, and Overload
A model can become unusable in hours for reasons that have nothing to do with a technical outage. This guide models three distinct flavors of 'unavailable'—retirement, withdrawal, and transient overload—as one availability state machine, with a router that keeps automated pipelines running. Working TypeScript and Python included.
Letting Claude Read Live Pages: Implementing web_fetch Without the Footguns
How to pull the actual text of official pages and PDFs straight into Claude's context with the web_fetch tool. Covers the URL-validation rule that trips everyone up, the settings that keep token costs down, and why fetch errors arrive as HTTP 200 — based on what I hit running it in production.
Making Claude Agent SDK Tools Idempotent — Stopping Double Execution with Deterministic Keys and an Outbox
An implementation log for stopping a Claude Agent SDK retry or session resume from processing the same payment twice. Three patterns — deterministic idempotency keys, an outbox, and a lightweight wrapper — with runnable code and production metrics.
Record Which Model Actually Answered — Attestation Logging for Headless Pipelines
Persist the model field and usage from every API response so you can detect when the served model differs from the one you requested, and reconcile per-model cost ahead of the usage credits change.
Wiring Claude's Dreaming Into Memory Hygiene for Long-Running Agents
Managed Agents' Dreaming reviews past sessions and rewrites memory as a self-improvement loop. We unpack the published Harvey and Wisedocs numbers, build a complete self-hosted consolidation loop with the Anthropic SDK, and cover the production pitfalls.
Auditing pinned model IDs before claude-sonnet-4 and claude-opus-4 retire from the API
On June 15, claude-sonnet-4 and claude-opus-4 retire from the API. Here is how to find every pinned model ID before then, measure output parity, and cut over safely with an alias layer and a fallback.
Claude Vision API in Production — Implementation Patterns for Image Analysis, PDF Processing, and OCR
Implementation patterns for taking Claude's vision capabilities to production: choosing between Base64, URL, and the Files API, native PDF processing, schema-enforced extraction with Tool Use, batch cost reduction, and error recovery — all with working code.
Claude API Python Advanced Cookbook: 20 Production Patterns You'll Actually Use
20 battle-tested Python patterns for the Claude API—retry logic, parallel processing, cost optimization, testing, and monitoring. Copy-paste ready code recipes.
Managed Agents Adds Scheduled Deploys, a Vault, and Session Webhooks — Deciding What Leaves My Cron Setup
Scheduled deploys, vault credentials, and session-thread webhooks just landed in Claude Managed Agents. How I triaged my self-hosted cron jobs: what moves, what stays, and why idempotency decides.