spb/doc-api

1# Code execution tool (`code_execution_20250825` · `_20260120` · `_20260521` · legacy `_20250522`)23**Status:** DOCUMENTED · LIVE_VERIFIED 2026-09-18 (e1 `print(2+2)` on haiku 4.5, e2 container reuse, e3 `code_execution_20260521`, g1/g2 Python cell via PTC on sonnet 4.6, k25 bad name; ≈$0.03 in tokens, container time inside the free tier).4**Sources:** [Code execution tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool) · [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) · [Skills guide](https://platform.claude.com/docs/en/build-with-claude/skills-guide) · [Files API](https://platform.claude.com/docs/en/build-with-claude/files) · [Messages API](https://platform.claude.com/docs/en/api/messages/create).5**Last verified:** 2026-09-18.67## Definition and versions8```json9{"type": "code_execution_20250825", "name": "code_execution"}      // name fixed (k25: 400 "Input should be 'code_execution'")10```11| `type` | What | Header | Live |12|---|---|---|---|13| `code_execution_20250522` | legacy Python-only, result type `code_execution_result` | `code-execution-2025-05-22` (still valid opt-in) | tag accepted by schema (not exercised) |14| `code_execution_20250825` (2025-09-02) | Bash commands + file ops via sub-tools `bash_code_execution`, `text_editor_code_execution` | none (legacy `code-execution-2025-08-25` accepted) | e1/e2 haiku |15| `code_execution_20260120` | + REPL state persistence across container reuse + **programmatic tool calling**; minimum for `web_search/_fetch_20260209+` | none | g1/g2 sonnet 4.6 |16| `code_execution_20260521` (2026-06-11) | same runtime; tool description discloses the 90 s per-cell wall-clock limit (`detection_timeout` status in output) | none | e3 haiku |1718Models: Fable 5.1, Mythos 5.1, Fable 5, Mythos 5, Opus 5, 4.8, 4.7, 4.6, 4.5, Sonnet 5, 4.6, 4.5, **Haiku 4.5** (haiku: no PTC / REPL persistence — newer versions behave like 20250825). Platforms: Claude API, Claude Platform on AWS, Foundry Hosted-on-Anthropic; not Bedrock/Vertex. Not ZDR-eligible.1920## Runtime21Python 3.11, Linux x86_64, 1 CPU, 5 GiB RAM, 5 GiB disk, **no internet** (only pre-installed libs: pandas, numpy, scipy, scikit-learn, statsmodels, matplotlib, seaborn, pyarrow, openpyxl, xlsxwriter, pillow, python-docx/pptx, pypdf, pdfplumber, reportlab, sympy, mpmath…; CLI: unzip, 7zip, bc, rg, fd, sqlite). Sandboxed per request's workspace. Whole-invocation timeout → `execution_time_exceeded`.2223## Files in / out24* In: upload with the Files API then reference `{"type":"container_upload","file_id":"file_…"}` in the user content (CSV, xlsx, JSON, images, text…). Files preloaded bill container time even if the tool is not called.25* Out: files Claude leaves at the top level of `$OUTPUT_DIR` of a `bash_code_execution` call are returned as `content: [{type: code_execution_output, file_id}]` in the result; download via `GET /v1/files/{id}/content`. Media files carry C2PA Content Credentials.26* Skills: `"container": {"skills": [{"type": "anthropic", "skill_id": "pptx", "version": "latest"}]}` (max 20; Skills API CRUD documented by the Skills agent).2728## Containers29Response top level: `"container": {"id": "container_01YXRh6bhAJd4WeWsdo29Bgg", "expires_at": "2026-09-19T02:49:11.949149Z"}` (live: `expires_at` ≈ 5 h ahead, rolling; the 30-day hard limit is not reported). Reuse by sending `"container": "<id>"` (or `{"id": …, "skills": […]}`) — e2 reused the same id and `expires_at` advanced. Checkpoint after ≈5 min idle, restore within 30 days; expired → error, resend without `container`. State independent of prompt cache. **Required** on continuation requests with a pending programmatic call. Sending an unknown id with a prompt that did not run code returned 200 without a `container` (k26) — behaviour for a real expired id remains UNVERIFIED.3031## Response blocks (live e1 / g2)32```json33{"type":"server_tool_use","id":"srvtoolu_017wg…","name":"bash_code_execution","input":{"command":"python3 -c \"print(2+2)\""}}34{"type":"bash_code_execution_tool_result","tool_use_id":"srvtoolu_017wg…","content":{"type":"bash_code_execution_result","stdout":"4\n","stderr":"","return_code":0,"content":[]}}35// text editor sub-tool: server_tool_use{name:"text_editor_code_execution", input:{command: view|create|str_replace, path, …}} ->36//   text_editor_code_execution_tool_result{content: text_editor_code_execution_view_result{file_type,content,num_lines,start_line,total_lines} | _create_result{is_file_update} | _str_replace_result{old_start,old_lines,new_start,new_lines,lines[]}}37// PTC python cell (20260120+): server_tool_use{name:"code_execution", input:{code}} ->38{"type":"code_execution_tool_result","tool_use_id":"srvtoolu_01XRk…","content":{"type":"code_execution_result","stdout":"[{'one': 1}]\n","stderr":"","return_code":0,"content":[],"abort_reason":null}}39```40Errors: `{"type":"bash_code_execution_tool_result_error","error_code":"unavailable"}`; codes `unavailable`, `execution_time_exceeded`, `invalid_tool_input`, `too_many_requests`, `output_file_too_large` (bash), `file_not_found` (text editor). `abort_reason` is undocumented (LIVE_DISCOVERED). `pause_turn` possible; mixed with client tools the code-execution result arrives after your `tool_result`s. Streaming: sub-tool input as `input_json_delta`, result block whole.4142Undocumented internal type ids seen in the per-model "Did you mean" error list (`bash_code_execution_20250825`, `text_editor_code_execution_20250825`, `python_with_tools_code_execution_20250825/20260120/20260521`) are **not** accepted as request tool types (k11/k12/k12b → 400).4344## Usage / pricing45Docs show `usage.server_tool_use.code_execution_requests`; live responses (e1–e3, g1–g2) only contained `web_search_requests`/`web_fetch_requests` = 0 — no code-execution counter (discrepancy). Billing: **free when `web_search_20260209+` or `web_fetch_20260209+` is in the request**; otherwise container-hours with a 5-minute minimum, **1,550 free hours/org/month**, then **$0.05 per hour per container**. Tokens as usual — e1 cost 4,611 input tokens on haiku (tool description is large). Container data retained 30 days; Files API outputs persist until deleted.4647## Interplay48Web search/fetch dynamic filtering auto-provisions code execution (shared container); if you also declare `code_execution` it must be `20260120+`. With a client bash tool present, tell Claude the two environments are separate. Skills load into the container. Programmatic tool calling: [programmatic-tool-calling.md](programmatic-tool-calling.md).4950Examples: `examples/anthropic/code-execution/code_execution.{sh,py,ts}` (sh does the container reuse); test `test_code_execution_and_container_reuse` (expensive).51