Handing Monthly Revenue CSVs to the Claude API Code Execution Tool — Files API Wiring, Container Reuse, and Billing Traps

Start Minimal — Learn the Response Blocks First

The first step worth taking is a file-free request, purely to understand the response shape. Skipping this and jumping straight to Files API integration is how people end up lost in response parsing, because the response of a code-execution request looks unlike anything the standard tool-use loop has taught you to expect.

import anthropic
 
client = anthropic.Anthropic()  # ANTHROPIC_API_KEY comes from the environment
 
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Calculate the mean and standard deviation of monthly revenue [412000, 389000, 455000, 401000, 478000] JPY",
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)
 
# The response is a sequence of content blocks
for block in response.content:
    if block.type == "server_tool_use":
        # The command or code Claude ran in the sandbox
        print("Executed:", block.input)
    elif block.type == "bash_code_execution_tool_result":
        result = block.content
        print("stdout:", result.stdout)
        print("return_code:", result.return_code)
    elif block.type == "text":
        print("Claude's explanation:", block.text)

Run it and you will see the anatomy clearly: a server_tool_use block holding the code Claude wrote, a bash_code_execution_tool_result block whose stdout contains the mean of 427,000 JPY along with the standard deviation, and a closing text block where Claude explains the result in plain language.

The point to internalize is that execution completes entirely server-side. Unlike client tools, you never assemble a tool_result yourself and there is no second round trip; the server_tool_use and *_tool_result pairs simply appear, already resolved, inside a single response. In the current version those result blocks come in two families. Shell runs come back as bash_code_execution_tool_result carrying stdout, stderr, and return_code. File operations come back as text_editor_code_execution_tool_result, whose shape varies by operation — a view returns the file content with line counts, a create reports whether it overwrote an existing file, and a str_replace edit returns a small diff. Your parser should expect both families. And make a habit of checking stderr and return_code on every result: it is the difference between catching a silently failed aggregation and shipping it to your accounting folder.

Sending Revenue CSVs Into the Container via the Files API

With the response shape understood, the real work starts. Upload the monthly reports through the Files API, then reference them in the message with container_upload blocks — one per file. The files are placed into the container before the model starts working, so Claude can list, inspect, and read them with ordinary Python.

import anthropic
from pathlib import Path
 
client = anthropic.Anthropic()
 
# The monthly report set (App Store Connect / AdMob / three mediation networks)
report_files = [
    "asc_financial_2026_05.csv",
    "admob_2026_05.csv",
    "unity_ads_2026_05.csv",
    "liftoff_2026_05.csv",
    "inmobi_2026_05.csv",
]
 
uploaded = []
for path in report_files:
    f = client.beta.files.upload(file=Path(path).open("rb"))
    uploaded.append({"type": "container_upload", "file_id": f.id})
 
AGGREGATION_RULES = """You are performing a monthly revenue aggregation for mobile apps. Follow these rules strictly.
 
- Convert all amounts to JPY. For USD rows, use the exchange_rate column if present; otherwise use 1 USD = 155 JPY
- Align the period to calendar days from 2026-05-01 through 2026-05-31. Exclude rows outside the range
- Identify apps by whichever of bundle_id / package_name / app_id exists, and build a mapping table for naming variants first
- Write the aggregated result to $OUTPUT_DIR/summary_2026_05.csv, broken down by network and by app
- Save a stacked bar chart (network x app) to $OUTPUT_DIR/revenue_2026_05.png
- Never fill in missing numbers by guessing. Write any row you are unsure about to $OUTPUT_DIR/excluded_rows.csv with a reason
- Write all three files flat in $OUTPUT_DIR, within the same single command
- Print only row counts and totals to stdout. Never print a whole dataframe
"""
 
response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    betas=["files-api-2025-04-14"],
    max_tokens=8192,
    messages=[{
        "role": "user",
        "content": [{"type": "text", "text": AGGREGATION_RULES}] + uploaded,
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

The heart of this code is not the upload loop — it is AGGREGATION_RULES. Exchange rates, period definitions, exclusion criteria: these are accounting decisions, and they belong to the human no matter how capable the sandbox is. This is also why the prompt asks for a naming-variant mapping table before any aggregation: when the same app appears as a bundle ID in one report and a marketing name in another, I want that reconciliation made explicit and inspectable rather than implied inside a join.

The line that earns its keep is the last one. Instructing Claude to write every questionable row to excluded_rows.csv with a reason means nothing ever drops out of the aggregation untraceably. I added that rule after watching a run come close to quietly imputing averages into rows with missing values — exactly the failure mode you never notice until a quarter later. Since then, every aggregation prompt I write includes an exclusion log, and I would recommend the habit for any LLM-driven data work, not just this tool.

The exchange rate is passed in the prompt because of the constraint mentioned earlier: the container cannot reach the network. In my first month I overlooked that and watched Claude attempt to call a currency API and fail, politely, several times. Deciding up front which information must be supplied from outside, versus computed inside, removes a whole class of confusion — I now keep a short written list of externally-sourced facts that the monthly prompt must carry.

Run a Three-Point Check Locally Before You Upload

Having written all of that, I never call client.beta.files.upload() without first running a small check on my own machine. The reason is the billing rule covered further down: attaching a file starts the execution-time meter by itself. Upload a report whose columns quietly changed, watch the sandbox fail on it, fix the file, upload again — and that round trip costs a whole billing unit for nothing.

The check covers three things only. Can each required field be resolved from the header? Is more than one currency present? How many rows fall outside the closing period?

"""Pre-upload three-point check: column resolution / currency / period."""
import csv, re
from datetime import date, datetime
 
FIELD_PATTERNS = {
    "app":      re.compile(r"(bundle|package|app[ _]?(id|name)|vendor)", re.I),
    "revenue":  re.compile(r"(revenue|earning|share|proceeds)", re.I),
    "date":     re.compile(r"(date|day)", re.I),
    "currency": re.compile(r"(currency|^cur$)", re.I),
}
DATE_FORMATS = ("%Y-%m-%d", "%m/%d/%Y", "%d-%m-%Y", "%Y/%m/%d")
 
 
def parse_date(value):
    for fmt in DATE_FORMATS:
        try:
            return datetime.strptime(value.strip(), fmt).date()
        except ValueError:
            continue
    return None
 
 
def preflight(path, period_start, period_end):
    with open(path, newline="", encoding="utf-8") as fp:
        reader = csv.DictReader(fp)
        header = reader.fieldnames or []
        # Resolve by meaning rather than by exact column name
        mapping = {}
        for field, pattern in FIELD_PATTERNS.items():
            hit = next((c for c in header if pattern.search(c)), None)
            if hit:
                mapping[field] = hit
        missing = [f for f in ("app", "revenue", "date") if f not in mapping]
 
        currencies, out_of_range, unparsable = set(), 0, 0
        for row in reader:
            if "currency" in mapping:
                currencies.add((row[mapping["currency"]] or "").strip().upper())
            parsed = parse_date(row[mapping["date"]]) if "date" in mapping else None
            if parsed is None:
                unparsable += 1
            elif not (period_start <= parsed <= period_end):
                out_of_range += 1
 
    return {
        "file": path, "mapping": mapping, "missing": missing,
        "currencies": sorted(c for c in currencies if c),
        "out_of_range": out_of_range, "unparsable": unparsable,
    }

I ran this against five CSVs that reproduce the naming and format drift described earlier — 3,000 rows, 140,600 bytes in total — on local Python 3.10. Five runs averaged 0.070 seconds (min 0.069, max 0.070). That is less than the time a single upload takes.

On the clean set it passes, flagging only a handful of out-of-period rows across three files. Then I simulated a report format change: renamed revenue to net_payout and switched the date from 2026-05-14 to 14.05.2026. The output became:

unity_ads_2026_05.csv: could not resolve required columns: ['revenue', 'date'] / unparsable dates: 600

Exit code 1. All 600 rows unparsable — meaning that had I uploaded as usual, an entire network would have dropped out of the aggregation. That failure is nasty precisely because it is quiet: the monthly total simply comes back a little smaller, which is indistinguishable from a soft month at a glance.

Resolving fields by regex rather than by literal column name is the whole point. A rename as far out as net_payout still escapes the pattern — but then the check reports it as unresolvable and stops. Fail loudly rather than fail quietly is the only design rule I hold onto for aggregation code.

Only What Lands in $OUTPUT_DIR Comes Back

There is a reason the aggregation rules above spell out $OUTPUT_DIR for every write. The only files returned as file IDs are the ones sitting directly in the $OUTPUT_DIR assigned to that command. Anything written elsewhere stays in the container and never appears in the response.

$OUTPUT_DIR is also fresh and empty for each bash invocation. Split aggregation and charting across two commands, have only one of them write to $OUTPUT_DIR, and the other one's output never reaches you.

I worked this out while chasing a mismatch that made no sense at the time: an ls inside the container listed the summary file plainly, and the download list never showed it. The file existed. It was simply written somewhere the retrieval contract does not reach. So I gave up on tidy subdirectories and keep everything I want back flat at the top level — that is what the last line of the rules block is doing.

With the destination pinned down, you collect the file IDs from the response and download them through the Files API. Two details are worth knowing: the IDs are nested fairly deep inside the result blocks, and the official sample walks only the bash result family. I scan all result blocks defensively instead.

def extract_generated_file_ids(response) -> list[str]:
    """Collect file_ids of generated files from every tool-result block."""
    file_ids = []
    for block in response.content:
        if not block.type.endswith("_tool_result"):
            continue
        content = getattr(block, "content", None)
        if content is None:
            continue
        # Output-file references arrive in the result's content list
        for item in getattr(content, "content", None) or []:
            file_id = getattr(item, "file_id", None)
            if file_id:
                file_ids.append(file_id)
    return file_ids
 
 
for file_id in extract_generated_file_ids(response):
    meta = client.beta.files.retrieve_metadata(file_id)
    client.beta.files.download(file_id).write_to_file(meta.filename)
    print(f"Downloaded: {meta.filename}")

One surprise when I tried to verify a download byte-for-byte against the container copy: generated images carry embedded C2PA Content Credentials, so the PNG's size and checksum will not match what was written inside the sandbox. The manifest adds a few kilobytes. Images, audio, and video get signed; text, PDF, and office documents do not. If you want a verification step, run it against the CSVs.

The getattr-based defensive style is deliberate. The result block types have already changed once between tool versions, and for an API that is still evolving, encoding the intent — collect anything that carries a file_id — has proven more durable than pinning exact types with isinstance. When the SDK adds a new result variant, this function keeps working; a type-pinned version would need another patch, which is the exact failure pattern I left local scripts to escape.

One lifecycle note: files generated by code execution persist on the Files API side until you explicitly delete them, while the container's own working data expires on the 30-day schedule. If you produce a chart every month and never clean up, the file list grows quietly — worth a periodic sweep.

Of everything that comes back, the file I open every single month is excluded_rows.csv. Reading the reasons attached to dropped rows is how I noticed that Liftoff's export had test-campaign rows mixed in, and that a timezone notation had changed in one date column. The aggregated answer is useful, but the rows that fell out of the answer carry more operational signal — that is an honest takeaway from doing this close month after month.

Container Reuse Turns the Close Into a Conversation

The part I have come to appreciate most is that the close no longer has to finish in a single round trip. Every response from a code-execution request carries a container reference; pass that ID into the next request and you get the same sandbox back, working files included.

container_id = response.container.id
 
followup = client.beta.messages.create(
    container=container_id,  # Reuse the same sandbox, working files included
    model="claude-sonnet-4-6",
    betas=["files-api-2025-04-14"],
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Re-read summary_2026_05.csv and list the three app x network pairs with the largest month-over-month decline",
    }],
    tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
)

The conversation is brand new — no prior messages carried over — but summary_2026_05.csv is still sitting in the container, so follow-up questions need no re-upload and no re-aggregation. "Is that drop coming from eCPM or from impressions?" "Show me this network by day." "Recompute with last month's exchange rate so I can see how much is currency movement." The closing numbers become something you can interrogate interactively, which is precisely what a static script never gave me.

The caveat: containers expire 30 days after creation. Persist a container_id in your database and reuse it next month, and requests pointing at that ID come back as errors instead of your data. Recovery is trivial — drop the container parameter and you get a fresh one. My rule is simple: reuse within the same working day, recreate every month from the source CSVs, which I keep anyway.

One genuinely confusing detail is container.expires_at in the response. That value does not represent the 30-day deadline. It is a much shorter rolling timestamp that moves with each request. Judging "still usable" or "already gone" from expires_at will mislead you. After roughly five idle minutes the container is checkpointed, which is not expiry at all — send the ID again any time within the 30 days and it comes back with your working files intact. Base the decision on the creation date instead. The newer code_execution_20260120 version also persists REPL variable state between requests, not just files, which suits longer analytical sessions; but for a monthly close, the file persistence in 20250825 has been entirely sufficient for me.

Understand the Billing Before You Ship — the 5-Minute Minimum and the Free Tier

Code execution is billed by execution time, tracked separately from tokens, and the published terms have a few corners worth knowing before you wire this into anything recurring.

• Each billed session counts a minimum of 5 minutes, even if the actual run took forty seconds
• Every organization gets 1,550 free hours per month; beyond that it is $0.05 per hour, per container
• Model token charges (input and output) apply as usual, on top of execution time
• When web_search_20260209 or web_fetch_20260209 is in the same request, code execution itself carries no extra charge beyond tokens (this pairing requires code_execution_20260120 or later on the code execution side)
• The response reports tool activity under usage.server_tool_use.code_execution_requests, which is the number to watch in monitoring

And then there is the clause that catches nearly everyone. If a request includes files, execution time is billed even when the tool is never invoked, because the files are preloaded onto a container regardless of whether Claude decides to run code. While you are still iterating on prompt wording, leave the files out and tune the text alone; attach the files only once the instructions have settled. That ordering alone prevents a pile of pointless 5-minute charges, and it is not a hypothetical — my first week of experimentation was mostly prompt tuning with files attached, which in hindsight was paying for preloads I never used.

For scale, here is what the real operation looks like. My monthly close runs one container for 5 to 15 minutes, follow-ups included, and never approaches one hour per month. Execution time therefore stays entirely inside the free tier, and the actual spend is the token side — a close costs somewhere in the tens of thousands of tokens including output, which lands under a dollar. For contrast, pushing five files totaling roughly 8MB through the prompt as raw text would be on the order of two million tokens. That does not fit a standard context window at all; even split across chunked requests it would cost several dollars in input tokens alone, before you account for the accuracy loss of making a language model eyeball-parse half a million CSV rows instead of running pandas over them. Files go to the container; the prompt carries the judgment rules. That split has been the right one on both cost and precision, and I expect it generalizes well beyond revenue reports.

A pause_turn Run Quietly Loses Half the Files You Generated

On long reconciliations across five files, the API sometimes returns mid-task with stop_reason set to pause_turn. It is not an error and not a refusal — it means "there is more." Append the response to the conversation as-is, send it back, and execution resumes where it stopped.

messages = [{
    "role": "user",
    "content": [{"type": "text", "text": AGGREGATION_RULES}] + uploaded,
}]
 
while True:
    resp = client.beta.messages.create(
        model="claude-sonnet-4-6",
        betas=["files-api-2025-04-14"],
        max_tokens=8192,
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
    if resp.stop_reason != "pause_turn":
        break
    messages.append({"role": "assistant", "content": resp.content})

So far this matches the documentation. The problem was what I did next: calling extract_generated_file_ids(resp) on the response after the loop.

The resp you hold once the loop exits is only the final turn. If the aggregation finished writing summary_2026_05.csv during the first turn and the chart rendering spilled into the second, the CSV's file_id disappears along with the response it was overwritten by.

I reproduced this locally with stand-in response objects — one file generated in turn one, another in turn two — and pushed both through each style of retrieval.

What made this awkward was which file went missing. The chart arrives, so the run looks like it succeeded; you find out the summary is absent at the moment you try to open it.

The fix is to collect inside the loop rather than after it, with a turn cap so an unexpected chain of pauses cannot spin forever.

MAX_TURNS = 10
 
collected_file_ids: list[str] = []
for turn in range(MAX_TURNS):
    resp = client.beta.messages.create(
        model="claude-sonnet-4-6",
        betas=["files-api-2025-04-14"],
        max_tokens=8192,
        messages=messages,
        tools=[{"type": "code_execution_20250825", "name": "code_execution"}],
    )
    # A paused turn can still have produced files, so collect every time
    collected_file_ids += extract_generated_file_ids(resp)
 
    if resp.stop_reason != "pause_turn":
        break
    messages.append({"role": "assistant", "content": resp.content})
else:
    raise RuntimeError(f"pause_turn persisted for {MAX_TURNS} turns; split the aggregation rules")
 
# The same file can be referenced across turns, so dedupe while preserving order
collected_file_ids = list(dict.fromkeys(collected_file_ids))

The for/else is there so that exhausting the turn cap is never mistaken for success. Pauses tend to chain when the rule set is asking for too much in one pass, and in those cases splitting the request into aggregation and visualization turns out to be faster overall.

What Comes Back When It Fails — Branching on error_code

Learn only the happy path and the first failure stops you cold. When the tool fails, you get a bash_code_execution_tool_result_error block in place of the result, and its error_code tells you why. Six are currently defined.

The split is simple enough: retry only what time will fix, and stop on anything caused by how I wrote the request. Put invalid_tool_input on the retry path and you will resend an identical request while the 5-minute charges stack up behind it.

output_file_too_large shows up more often than you would expect in aggregation work. The usual cause is a print(df) added "just to check," which sends a few thousand rows straight to stdout. Adding one line to the rules — print only counts and totals — made it stop happening. Each rule I add feels less like improving the analysis and more like retiring one category of failure.

Common Mistakes and Pitfalls

These are the ones I hit, or came close to hitting, in real operation.

1. Mixing in legacy sample code. Search results still surface tutorials from the Python-only code_execution_20250522 era. Copy response-parsing code from them and you will silently miss the current bash_code_execution_tool_result / text_editor_code_execution_tool_result blocks — your loop simply never matches, and the symptom looks like "Claude ran nothing." Standardize on 20250825 and parse both result families.

2. Assuming "no tool call, no charge." As above: attaching files starts the execution-time meter on its own. Ten prompt-tuning iterations with files attached burn fifty minutes of free tier without a single execution. Iterate file-free, attach when stable.

3. Treating pause_turn as the end of the turn. Reading a half-finished aggregation as the final result — the partial output looks plausible, which is what makes it dangerous. As covered in the previous section, build the response-replay loop and the accumulating file_id retrieval in from day one.

4. Storing container IDs as if they were permanent. Thirty days after creation the container is gone, and expires_at will not warn you — it reports something shorter and unrelated. Never design for cross-month reuse; recreate monthly from source files.

5. Forgetting the sandbox is offline. No exchange-rate lookups, no pip install, no reference data fetched from a URL. State externally-sourced facts in the prompt, and check the preinstalled library list covers your needs before committing to the design. For aggregation work, pandas, numpy, matplotlib, and openpyxl were all I needed; if your workflow depends on a niche package, this tool may not be the right home for it.

6. Writing outputs outside $OUTPUT_DIR. The files exist in the container but never appear in the response, which reads exactly like "nothing was generated." Name the destination in the rules and forbid subdirectories.

7. Sending sensitive data raw. This feature is not eligible for zero data retention, and container data persists for up to 30 days on Anthropic's side. Revenue reports contain little personal data, but the moment you route user reviews or support logs through the same pipeline, put a masking step in front — the approach I use is in Before You Send Reviews and Crash Logs to the Claude API: A Reversible PII Masking Design. For managing the uploaded files themselves — listing, lifecycle, deletion — Claude API Files API — Persist Documents and Slash API Costs covers the mechanics in more depth.

Start by Handing Over a Single AdMob CSV

There is no need to build the whole pipeline at once, and I would actively advise against trying. The first step I would actually recommend: upload just this month's AdMob report, add a single container_upload block to the minimal example from earlier, and ask for nothing more than "plot estimated daily earnings as a line chart and save it as a png." That one exchange teaches you the response-block anatomy, the file_id retrieval, and the download path — the three things every later iteration builds on. Once you have been around that loop, growing the rule set line by line carries you the rest of the way to a full monthly close.

When month-end stops being about chasing format drift and becomes about writing down judgment rules in plain language, the close itself turns into time spent reviewing how the business actually runs. I am still adding conversion rules every time excluded_rows.csv teaches me something new — and I find I do not mind the loop at all. Thank you for reading along this far.