# Gemini — Code execution (`tools[].codeExecution`)

Status: DOCUMENTED + LIVE_VERIFIED (2026-09-18 run — see "Live verification" section at the end)

Sources:

https://ai.google.dev/gemini-api/docs/generate-content/code-execution · https://ai.google.dev/gemini-api/docs/code-execution
https://ai.google.dev/api/generate-content (#CodeExecution #ExecutableCode #Language #CodeExecutionResult #Outcome)
https://ai.google.dev/gemini-api/docs/pricing · https://ai.google.dev/gemini-api/docs/tool-combination

Last verified: 2026-09-18 (docs only)

# 1. Request

tools: [{"codeExecution": {}}] — no fields. Interactions API: {"type":"code_execution"}. Input files: part.inlineData or part.fileData (Files API); best with text/CSV. Prompt explicitly for non-obvious uses ("write code to …").

# 2. Response parts

Part	Fields	Notes
`executableCode`	`language: PYTHON` (only enum value besides UNSPECIFIED; "Python ≥3.10"), `code`, `id?`	generated code
`codeExecutionResult`	`outcome: OUTCOME_OK \| OUTCOME_FAILED \| OUTCOME_DEADLINE_EXCEEDED`, `output` (stdout / stderr), `id?` (matches executableCode.id)	result
`inlineData`	`mimeType: image/png`, `data`	matplotlib graphs / image manipulations (Gemini 3 Flash "code execution with images", requires thinking enabled)
`text`		final summary
`thoughtSignature`		on parts; echo in multi-turn history together with `id` (required for Gemini 3 tool combination)

Streaming (streamGenerateContent): parts arrive as produced. Chat/multi-turn: append the whole model content (code + result parts) to history.

# 3. Limits

Limit	Value
Language	Python only (other languages can be generated, not run)
Runtime	30 s per execution
Retries	up to 5 automatic regenerations on error
Libraries (fixed, no pip)	attrs, chess, contourpy, fpdf, geopandas, imageio, jinja2, joblib, jsonschema, jsonschema-specifications, lxml, matplotlib, mpmath, numpy, opencv-python, openpyxl, packaging, pandas, pillow, protobuf, pylatex, pyparsing, PyPDF2, python-dateutil, python-docx, python-pptx, reportlab, scikit-learn, scipy, seaborn, six, striprtf, sympy, tabulate, tensorflow, toolz, xlrd
Graphs	matplotlib only; returned as `inlineData`
Input size	bounded by the model context window (AI Studio: ~1M tokens ≈ 2 MB text)
Artifacts	cannot return media files other than images
Quality	may regress other outputs (e.g. creative writing); model-dependent reliability
Live API	not supported

# 4. Billing

No fee. Input tokens: your prompt. Output tokens: generated code, execution output, thinking, summary. When the model re-reads prompt + code + results they are "intermediate" input tokens (reported in usageMetadata). Session runtime is not billed. Free tier: free.

# 5. Models and combinations

All current text models per model pages (Gemini 3.8/3.7/3.6/3.5 Flash, 3.5 Flash-Lite, 3.1 Pro Preview, 3.1 Flash-Lite, 3 Flash/Pro Preview, 2.5 Pro/Flash/Flash-Lite, robotics ER 2). Combinable with googleSearch (since 2025-05), with function calling on Gemini 3 (echo id + thoughtSignature), with structured outputs (Gemini 3). Not with fileSearch.

# 6. Examples

bash

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash-lite:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Sum of the first 50 integers, use code."}]}],"tools":[{"codeExecution":{}}]}'

python

r = client.models.generate_content(model="gemini-3.5-flash-lite", contents="Sum of the first 50 integers, use code.",
      config=types.GenerateContentConfig(tools=[types.Tool(code_execution=types.ToolCodeExecution())]))
for p in r.candidates[0].content.parts:
    if p.executable_code: print(p.executable_code.code)
    if p.code_execution_result: print(p.code_execution_result.outcome, p.code_execution_result.output)

const r = await ai.models.generateContent({ model: 'gemini-3.5-flash-lite', contents: 'Sum of the first 50 integers, use code.',
  config: { tools: [{ codeExecution: {} }] } });
for (const p of r.candidates?.[0]?.content?.parts ?? []) { if (p.executableCode) console.log(p.executableCode.code); if (p.codeExecutionResult) console.log(p.codeExecutionResult.output); }

# Live verification (2026-09-18)

LIVE_VERIFIED on gemini-3.5-flash-lite (tmp-live/gemini-tools/d_code_execution.json): tools:[{"codeExecution":{}}] + "Run print(2+2) in Python and report the output." → HTTP 200 with parts [{executableCode:{language:"PYTHON", code:"print(2+2)", id:"call_348726"}, thoughtSignature}, {codeExecutionResult:{outcome:"OUTCOME_OK", output:"4\n", id:"call_348726"}}, {text:"4", thoughtSignature}]. Note the id field on both parts (same value) — not shown in the guide. usageMetadata.toolUsePromptTokenCount: 34. Examples examples/gemini/tools/code-execution/code_execution.{py,sh} (both executed), test tests/gemini/test_tools.py::test_code_execution_parts.

# Gemini — Code execution (tools[].codeExecution)