# 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)
```
```ts
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`.