Methodology_

Version: v3.8-methodology-2026-08 Last updated: 2026-08-21 Status: versioned document; every change produces a new version. English translation of the French original (docs/methodology.md), which remains the source of truth; both carry the same version number, enforced in CI.

TokenClimate produces an estimate of the environmental impact of LLM usage per team, on three quantities: energy consumed (Wh), greenhouse gas emissions (gCO₂e) and estimated water consumption (mL). These are not measurements; they are estimates derived from the volume of tokens consumed and from sourced public parameters. This document describes the scope, the assumptions, the equations, the sources, the known limits, and how to verify the values.

Normative framing and scope

The methodology is grounded in LCA principles (ISO 14040), in an attributional approach, and aligned with AFNOR Spec 2314 for the datacenter third. It is not a full third-party-verified LCA. The structure of this document follows the AFNOR Spec 2314 §4.1 checklist:

Functional unit

The token. All quantities are expressed per million tokens (Mtok), broken down by token type (non-cached input, cache write, cache read, output) and by model family.

System boundaries

The covered scope is the datacenter third, inference only:

• IT electricity of the inference servers, increased by the PUE (cooling and datacenter overhead);
• embodied carbon of the inference hardware (GPU + host server), amortised;
• on-site cooling water (WUE) and water embedded in purchased electricity (EWIF, off-site).

Excluded: user devices and networks (respectively ~50% and ~4% of the digital footprint in France according to the Arcep report of May 2026: the datacenter third is only part of the whole), and model training (not allocated to inference; the split is not published by Anthropic).

Allocation

The impact of shared infrastructure is allocated pro rata to the IT energy attributable to the session's tokens. Embodied carbon is amortised over 5 years of hardware service then allocated per IT kWh. That figure is the one Amazon adopted on 1 January 2025, shortening the accounting useful life of a subset of its servers and network equipment from 6 to 5 years, with the stated reason: "the increased pace of technology development, particularly in the area of artificial intelligence and machine learning". Two counterpoints exist, pulling in opposite directions: the AWS Customer Carbon Footprint methodology (Model v3.0, October 2025, §3.3.4.3) aligns racks on 6 years, while EcoLogits uses 3. Claude Code subagent tokens are aggregated into the parent session (see Caveats). No offsets, no compensation: market instruments are outside the calculation, in line with the SCI.

SCI vocabulary (ISO/IEC 21031)

The calculation can be described in the vocabulary of the Software Carbon Intensity for AI: a Consumer-type score (inference usage, not training), per token (R = the token). The three components are published separately and never merged into an opaque score:

• E (energy): energy_wh, the estimated IT energy;
• I (intensity): PUE × CIF, location-based;
• M (embodied): EMB, the hardware term.

That is SCI = (E × I) + M per token. Offsets are excluded by construction.

Assumed location

We do not know in which region each request is served. The assumption remains US multi-cloud, AWS-dominant: the CIF is the weighted mix of AWS inference regions (see next section). It is now partial, and that has to be said.

On 6 May 2026, Anthropic announced a deal with xAI covering the entire capacity of Colossus 1, near Memphis, 300 MW, through May 2029. The announcement explicitly mentions inference for subscribers. The grid involved is the Tennessee Valley Authority's, which is not part of the AWS-region weighting our CIF is built on, and whose subregion emission factor we have not opened at primary source.

Added to GCP and Azure, where Anthropic also operates with no published split, this leaves the sensitivity of the CIF to that unknown at ±30%, an estimate we currently have no means of tightening. Work is open to rebuild the weighted mix ourselves from Electricity Maps and to quantify the TVA subregion.

On water

We speak of estimated water consumption, never of a "water footprint". A water footprint in the ISO 14046 sense would require impact characterisation (for example AWARE, weighting by local water stress), which v3 does not do since the location of requests is unknown.

The water figure adds two quantities that are not of the same nature, and we declare it rather than hide it. The equation is water_ml = energy × (WUE + PUE × EWIF). AWS defines its WUE as water withdrawn ("liters of water withdrawn per kilowatt-hour"), whereas WRI-family EWIF factors measure consumption. Adding a withdrawal to a consumption is not homogeneous.

Two reasons not to correct it right away rather than one: the consumption-to-withdrawal ratio depends on a site's cycles of concentration, which we do not know, and the exact definitional basis of the WRI figure of 5.11 L/kWh is not documented in our methodology. What bounds the problem: the on-site term is 2.0% of the millilitres displayed (0.12 out of 5.9454), so the inhomogeneity affects 2% of the figure, not the figure. The remaining 98% is the water used to generate electricity, where the doubt is of a different order: two recent publications put average US power-plant consumption between 1.8 and 2.3 L/kWh, against the 5.11 used here. If that holds, the displayed water will drop sharply. We will not change the value before reopening the primary WRI source.

Equations

For a session, with energies E_in and E_out in Wh per million tokens (IT energy, server side):

energy_wh = (
    (input_tokens + cache_creation_tokens) * E_in
  + cache_read_tokens * E_in * 0.08
  + output_tokens * E_out
) / 1_000_000

co2_grams = energy_wh * (PUE * CIF + EMB)
water_ml  = energy_wh * (WUE + PUE * EWIF)

With the Anthropic parameters of the next section, the composite constants are:

Embodied carbon represents 11.9% of total CO₂e (0.044 / 0.37118). Total CO₂e is therefore usage CO₂e × 1.1345.

The equation is implemented in lib/co2.ts, function computeImpact, which returns { energyWh, co2Grams, waterMl }. The three values are stored per usage row (energy_wh, co2_grams, water_ml). The USD cost is computed separately (see "USD cost").

Example

A Sonnet session with 50,000 input tokens, 200,000 cache write, 3,000,000 cache read and 30,000 output:

energy_wh = (250_000 * 119 + 3_000_000 * 119 * 0.08 + 30_000 * 2525) / 1e6
          = 134.06 Wh
co2_grams = 134.06 * 0.37118 = 49.76 g   (usage 43.86 g + embodied 5.90 g)
water_ml  = 134.06 * 5.9454  = 797.0 mL

Anthropic parameters

params block of lib/providers/seed/anthropic.json. Since v3.8 this block is composite: PUE and WUE come from a first-party AWS disclosure (2025 vintage), while CIF, EWIF and embodied stay pinned to Jegham N., Abdelatti M., Hendawi A., "How Hungry is AI? Benchmarking Energy, Water, and Carbon Footprint of LLM Inference", arXiv:2505.09598, version v6, Table 1.

Source tiers: T1 = published primary measurement or report, T2 = documented derivation from T1 sources, T3 = engineering estimate.

Tier reclassification in v3.8

Three rows change tier, and no value moves with them.

CIF and EWIF move from T1 to T2. T1 is defined here as "published primary measurement or report". Jegham et al. is a non-peer-reviewed preprint that republishes third-party parameters (Electricity Maps for the CIF) and models the rest: that is a documented derivation, hence T2. PUE and WUE stay T1 because they are now sourced from a disclosure published by the infrastructure operator itself, no longer from the preprint.

cache_read_factor moves from T3 to T2: since May 2026 a direct measurement of the hit/miss ratio exists (see "Cache energy"), which takes it out of engineering-estimate status without making it a measurement of our exact quantity.

The E_in / E_out ratio moves from T2 to T3, and its range widens in the opposite direction from the convention (see "The input/output ratio").

Version pin on the primary source

The CIF changed during the life of the source paper: 0.385 kgCO₂e/kWh up to v4, 0.287 since v5 (sourced from Electricity Maps). The value used here is pinned on v6, Table 1. Note: 0.287 is not "the global electricity mix"; it is a mix weighted across AWS inference regions.

Energy per model family

Source: lib/providers/seed/anthropic.json, energy block per model. Values in Wh per million tokens, IT energy.

2026-07 recalibration: the three per-request energies measured by Jegham v6 for Claude 3.7 Sonnet (0.950 / 2.989 / 5.671 Wh, PUE included) are fitted by OLS regression through the origin, which yields the 39/826 gCO₂e/Mtok usage factors of the OSS plugin; the IT energies above are de-compounded from them (E = factor / (PUE × CIF), rounded to the integer). The previous calibration (tokenclimate-v3-2026-06, Sonnet 580/3480) relied on the pre-v6 composites (190/1140). These energies stay aligned with those of the open source plugin claude-carbon (same author); an automated weekly check verifies consistency to ±0.5%.

Validity date of the energies

These energies are valid as of 2026-07 and go stale mechanically, in the direction of overestimation. On identical hardware, on H100, per-token energy fell by 15 to 41% depending on model size between vLLM 0.5.4 (September 2024) and vLLM 0.11.1 (December 2025), with no model changing: that is the serving stack alone (ML.ENERGY, longitudinal analysis). Our values are a fit on November 2025 measurements. They are renewed at least once a year, and sooner if a pinned source moves.

Sensitivity note: the overestimation charge

Three independent signals suggest these energies may be too high. We publish them rather than arbitrate in silence.

Microsoft (arXiv:2509.20241) measures a median of 0.31 Wh per request for models above 200 billion parameters on H100 nodes, and writes verbatim that "widely cited estimates are overstated by 4-20x". The family of estimates targeted is the one Jegham belongs to, that is, our primary source. Our Sonnet at 2,525 Wh/Mtok gives roughly 1.26 Wh for a 500-token response, about 4 times their median: we would therefore sit at the low end of the alleged overestimation range. Two further signals point the same way: EcoLogits publicly revised its estimates downward in March 2026 for overestimation, and a B200 measurement places a frontier model around 111 Wh/Mtok.

We are not switching the value. The Microsoft paper is a bottom-up model under deployment assumptions, produced by an interested party, not a measurement of our models. But the conflict exists, it is documented, and a reader who brings it to a meeting should find it here before finding it elsewhere.

The input/output ratio

Since the v6 recalibration, the ratio is no longer an assumption: it is recovered from the fit on the three measured points, about 21:1 output:input (2525 vs 119 Wh/Mtok for Sonnet). A long context adds little energy compared with the same volume of generated tokens, which a flat low ratio would miss. For non-Anthropic providers whose input energy is not measured (EcoLogits energies, which only publishes output, or Jegham fits whose input coefficient is forced to 0 by NNLS), the convention E_in = E_out/6 still applies.

That convention is now presented for what it is: a contested assumption, not a consensus value. The defensible range in the literature is far wider than what v3.7 published. It runs from 1/21, our own fit on Jegham v6, to 1.2, that is, an input more costly than an output, a value given by Vartziotis et al. (arXiv:2607.26571, equation 29). Their estimator is analytical, explicitly "compute-dominated" and set in a short-prompt regime: it misses the memory-bandwidth wall that dominates decode, so it is not transposable to our case. But it is published, it points the opposite way from our convention, and staying silent about it would mean publishing a range that does not exist.

The Fable case

No public source documents the size or energy of Fable 5 / Mythos 5. The anchor used is the price proxy: 2x Opus, the ratio of public prices (10/50 vs 5/25). To be revised as soon as an independent estimate is published.

Cache energy (cache_read_factor = 0.08)

A cache_read token is an already-processed context token whose key/value tensors are reused: its prefill compute is avoided. It is not free either.

What the term captures, and what it does not

The equation applies cache_read × E_in × 0.08, that is, a fraction of the energy of an uncached input token. It is therefore a prefill residual: what is still paid at prefill when the prefix is already cached.

Up to v3.7, that same term was justified by the KV re-read residual during decode. These are not the same object, and the second is not linear in cache_read: every generated token re-reads the entire KV cache from HBM, cached tokens included (GreenCache, SIGMETRICS: "caching does not reduce computation in the decode phase"). That cost is bilinear, depending on the product (context size × number of generated tokens). Today it is absorbed into an E_out assumed constant, calibrated at context lengths the source does not publish and which are probably short. The consequence, stated plainly: in a long-context regime, hence in agentic use, our figure underestimates this term.

What the literature measures

A direct measurement of the hit/miss ratio has existed since May 2026. Irminsul (arXiv:2605.05696, Table 1) instruments prefill energy per cache event, NVML hardware counters, at 4,096 prefix tokens:

Three reservations before drawing a value from this. The measurement is taken at 4,096 tokens of prefix, whereas the median Claude Code session step carries 126,180 tokens (TraceLab, arXiv:2606.30560v2, Table 8): at that scale fixed kernel-launch costs amortise and the real ratio falls, which the paper itself acknowledges for its small cells. The two high rows, MLA and MHA, are measured on 16-billion-parameter models, exactly where those fixed costs weigh most. Finally, Claude's attention architecture is not published: nothing says which of the three rows applies.

The value we keep

0.08, unchanged, published range 0.05-0.20. The tier moves from T3 (engineering estimate) to T2: a direct measurement now exists, on an adjacent object and in a different regime from ours, which is a documented derivation rather than a measurement of our quantity.

We did not switch to 0.14 despite Irminsul. Applying a measurement taken at 4K of context to usage that runs at 126K would move the figure of a Claude Code-dominated organisation by 25 to 30%, on a basis we could not defend. The published upper bound does move from 0.15 to 0.20, because two of the three measured architectures sit above the old ceiling: our stated uncertainty was understating the upside risk.

The adjacent measurements behind the original estimate still hold as a bracket: prefill represents at most 3.4% of total inference energy on generation workloads (Solovyeva & Castor), a larger KV cache amplifies per-token decode energy by 1.3 to 51.8%, and per-token energy roughly triples between 2K and 10K of context (TokenPowerBench, H100).

The real fix is not a new constant, it is a new equation shape, with a residual prefill term and a decode term as a function of context length. Until we measure that curve ourselves, the constant stays.

This factor is not Anthropic's 0.1x billing ratio. That is a price, not an energy measurement (OpenAI bills the same mechanism at 0.5x). Setting cache_read_factor to 0 would be a defensible lower bound, but it would treat a reused 100K-token system prompt as carbon-neutral, ignoring a real memory-bandwidth cost.

Sources: Irminsul (arXiv:2605.05696), GreenCache (arXiv:2505.23970), TokenPowerBench (arXiv:2512.03024), Solovyeva & Castor (arXiv:2602.05712), From Prompts to Power (arXiv:2511.05597), TraceLab (arXiv:2606.30560v2).

The factor lives in lib/providers/seed/anthropic.json (key cacheReadFactor) and is exposed by lib/providers/registry.ts.

Usage profiles of the public calculator

The public calculator (/calculator, /en/calculator) asks for a volume of generated tokens per month. Historically it only counted that volume. Yet generated tokens are only part of what the machine processes: in agentic use, context re-read from cache dominates the volume by far (see the example in the Equations section: 3,000,000 cache reads for 30,000 generated tokens, about 91% of the tokens processed).

A usage profile makes this assumption explicit instead of leaving it implicit. Each profile is a set of reference volumes per token class, stored verbatim from its source in lib/calculator/profiles.ts. Selecting a profile scales these volumes to the entered generated-token volume (rule: factor = entered volume / reference output volume). The default "Output only" profile reproduces the historical behaviour: links already in circulation produce the same figures as before.

The coding-agent profile is given in raw aggregates so it stays literally the source. Scaled to one million generated tokens, that is 4.8 M fresh input tokens, 19.3 M cache write and 269.7 M cache read, i.e. 270 tokens re-read from cache per generated token and 91.5% of total volume actually read from cache.

What changes against v3.7: the profile was 100 re-read tokens per generated token, taken from the worked example of the Equations section and corroborated after the fact. It is now 270, copied from measured aggregates. The figure the calculator shows for this profile is multiplied by roughly 1.78 (4,468.7 to 7,961.1 Wh per million generated tokens on Sonnet). The calculator was understating what an organisation sees in its Bilan.

Splitting the fresh volume between uncached input and cache write (1:4) is the only derivation left: TraceLab does not separate the two. It has no effect on energy, both classes costing full E_in, and only moves the dollar cost.

An intermediate profile (assistant with cached context) was considered then dropped: no published source breaks that workload down by token class, and the calculator does not display an assumption it cannot source. The manual entry mode covers that case; published cache shares for conversational services range from about 40% (Mooncake trace, arXiv:2407.00079) to 75-95% in production (TokenLake, arXiv:2508.17219).

Profile sources:

• Splitwise: Patel P. et al., "Splitwise: Efficient Generative LLM Inference Using Phase Splitting", ISCA 2024, arXiv:2311.18677. Azure production traces (November 2023): conversation service, median 1,020 prompt tokens and 129 generated tokens per request. Corroboration on response lengths: WildChat (arXiv:2405.01470, 441 tokens per response on average) and LMSYS-Chat-1M (arXiv:2309.11998, 215).
• TraceLab: Zhu J. et al., "TraceLab: Characterizing Coding Agent Workloads for LLM Serving", arXiv:2606.30560. Trace of 2,676 real Claude Code sessions (43 developers, October 2025 to June 2026): 95.5% of total volume in cache reads, 0.34% in output, prefix cache hit rate 95.7%.
• Bai et al.: "How Do AI Agents Spend Your Money?", arXiv:2604.22750. OpenHands on SWE-bench Verified: average input/output ratio of 153.85 in agentic coding (the agent profile uses ~109, conservative), ~4.17M tokens per task.

Limits

These profiles are orders of magnitude, not measurements. The real ratio between token classes varies strongly from one organisation to another depending on tooling, context sizes and the share of agentic usage. The AI usage report measures this ratio on the organisation's real data (cache read share shown in the report).

Dual reporting: location-based and market-based

The CO₂e displayed by default is location-based: the carbon intensity of the real electricity grid of the regions where inference runs. This is the requirement of AFNOR Spec 2314 (§4.3) and of the SCI, which exclude market instruments (PPAs, RECs, offsets) from the score.

Market-based figures are published for comparison, never as the default:

• Google 2024: 94 gCO₂e/kWh market-based vs 345 location-based (arXiv:2508.15734). The 3.7x gap shows what market instruments mask.
• AWS (TokenClimate's dominant location assumption): claims 100% renewable matching, but declares 2.80 MtCO₂e of residual market-based scope 2 in 2024 and publishes no market-based kg/kWh factor. The AWS market-based value is therefore "not published by AWS". We will never write "market-based = 0".

Third-party providers (EcoLogits + Jegham v6)

TokenClimate is built multi-provider (OpenAI, Google, Mistral, DeepSeek, Meta), even though the product sold is Claude-first. Google and Mistral remain entirely sourced from EcoLogits 0.10.2 (mlco2/ecologits repo, release of 2026-06-04, pinned version): PUE google 1.09, mistral 1.16, output energies derived from their parametric model (for example gpt-4o: 1676 Wh/Mtok IT, still sourced from EcoLogits, see OpenAI below). The gemini-1.5-* family is absent from EcoLogits 0.10.2: its values remain marked tokenclimate-manual with low confidence.

OpenAI and DeepSeek were recalibrated in 2026-07 on Jegham et al. v6, Table 1 and Table 4 (the same primary source as the Anthropic parameters):

• OpenAI, infra: PUE 1.12, CIF 0.35 kgCO₂e/kWh, WUE on-site 0.30 L/kWh, EWIF off-site 4.35 L/kWh (Table 1, OpenAI/Azure row, verbatim). This corrects an erroneous citation of that same Table 1 in the previous seed (PUE 1.20, CIF 0.3844, EWIF 3.13: only the on-site WUE was right). Energies: gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini and o3-mini remain sourced from EcoLogits (low confidence, unpublished architectures); o3, o4-mini, gpt-4.1-nano, gpt-4-turbo and o1 move to direct Table 4 measurements (3-point OLS fit, same method as the Anthropic seed). o3 and gpt-4-turbo have a clean two-coefficient fit (high confidence); o4-mini, gpt-4.1-nano and o1 yield a negative input coefficient under constraint, forced to 0 by NNLS, hence E_in = E_out/6 and medium confidence. 2026-07-19 extension: the current OpenAI range enters the catalogue. gpt-5.5 and the gpt-5.4 family (mini, nano) are sourced from EcoLogits 0.11.1 (genai-impact/ecologits repo, tag 0.11.1): output energy at the middle of the estimated active-parameter range, latency 1/tps, batch 64 - replay validated by reproducing gpt-4o (1676), gpt-4.1 (1536) and gpt-4o-mini (71 Wh/Mtok) from the 0.10.2 data; E_in = E_out/6, low confidence. The gpt-5.6 family (sol, terra, luna; GA 2026-07-09) is not yet covered by EcoLogits 0.11.1: sol takes the energy of gpt-5.5 and terra that of gpt-5.4, the models they replace at the same price (OpenAI pricing page, retrieved 2026-07-19); luna is extrapolated by output-price ratio from gpt-5.4 (6/15 = 0.4×). low confidence for all three, to be replaced as soon as EcoLogits covers them. The ten previous OpenAI models (gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4-turbo, o1, o3, o3-mini, o4-mini) become legacy: deprecated or absent from OpenAI pricing (deprecations and pricing pages, retrieved 2026-07-19). Their sheets and factors remain published to quantify past usage, but they leave the /models table, the rankings and the comparisons.
• DeepSeek, infra: PUE 1.27, CIF 0.6 kgCO₂e/kWh, WUE on-site 1.20 L/kWh, EWIF off-site 6.016 L/kWh (Table 1, DeepSeek/China row, verbatim) - replaces the old generic "China colo / IEA" figures (PUE 1.30, CIF 0.555, WUE 0.18, EWIF 3.13), whose on-site WUE was underestimated by about 7x. Energies: deepseek-chat and deepseek-reasoner are no longer manual estimates; they are direct Table 4 measurements on the DS rows (China-hosted, the API actually billed by these models): 6940 and 17442 Wh/Mtok in output, high confidence. The NNLS fit also forces the input coefficient to 0 for both models, hence E_in = E_out/6.

Meta (new provider): llama-3.1-8b-instant and llama-3.3-70b-versatile, measured in Table 4 with a clean two-coefficient fit (no E_in = E_out/6 convention here). Groq, the billed host, publishes neither PUE nor electricity mix: the decompounding uses a generic PUE of 1.2 (mid-range hyperscale placeholder, not Groq-specific), and the CIF and EWIF are proxied from the AWS/Anthropic row of Table 1 (0.287 kgCO₂e/kWh, 5.11 L/kWh) and the WUE follows the same AWS row, hence the 2025 first-party vintage (0.12 L/kWh), for lack of better. medium confidence: PUE and grid not sourced for Groq, and the Jegham measurement infrastructure (GPUs) differs from the real serving hardware (Groq LPUs).

The E_in = E_out/6 ratio and the 0.08 cache_read_factor applied to these non-Anthropic providers are TokenClimate extensions, whatever the source of the output energy (EcoLogits or Jegham).

USD cost

The cost is the theoretical API value of the usage (what it would cost pay-as-you-go), not the subscription price actually paid. Public Anthropic pricing in force on 2026-06-12, in USD per million tokens, tier 1, excluding negotiated Enterprise discounts.

Note: Opus 4.6+ is at 5/25. The 15/75 mentioned in v1 of this document applied to Opus 4.0/4.1, removed from the catalogue.

For a session:

cost_usd = (
    input_tokens * input_price
  + cache_creation_tokens * (input_price * 1.25)
  + cache_read_tokens * (input_price * 0.1)
  + output_tokens * output_price
) / 1_000_000

Implemented in lib/co2.ts, function co2ToCostUsd, rounded to 4 decimals. Per-model cache prices are materialised in lib/providers/seed/anthropic.json (cacheWriteUsdPerMtok, cacheReadUsdPerMtok). On deduplicated data, this calculation reconciles within a few percent with ccusage.

Token counting and deduplication

Counts come from parsing the JSONL transcripts (message.usage). Assistant messages are deduplicated by (message.id, requestId), keeping the last occurrence, before summing. This is necessary because resumed or compacted sessions replay previous messages in the same file, and because streaming rewrites the same message several times with a growing output_tokens. Without dedup, the raw sum overcounts by about 3x. This behaviour matches the deduplication performed by ccusage.

Source coverage: what the measurement sees, what it does not

We get the question with every report: "do you count claude.ai chat? Claude Cowork?". Here is the answer, surface by surface. Two collection paths exist:

• The AI usage report starts from an Anthropic admin key (sk-ant-admin01-...), created in the console by an administrator of the organisation. It exposes two read-only APIs: the Usage & Cost API (tokens and spend of API usage, per model and per day) and the Claude Code Analytics API (Claude Code usage per user and per day, including Team and Enterprise subscription seats).
• Continuous tracking adds the TokenClimate CLI installed on workstations, which measures Claude Code sessions locally (section "Token counting and deduplication"). Overlaps between sources are subtracted by reconciliation (day, member, model family): the same token is never counted twice.

The limits, spelled out:

• The claude.ai chat of a Team plan has no API. Anthropic exposes neither tokens nor counters for chat under a Team subscription, and automated access to claude.ai is forbidden by its terms of use. No tool on the market covers this surface. The report declares it out of scope; it does not estimate it.
• Claude Cowork follows the same rule on a Team plan: usage under subscription, no API.
• The Enterprise case is different. Claude Enterprise organisations have an Enterprise Analytics API that exposes chat, Claude Code and Cowork activity per user (data since 2026-01-01). It requires an Analytics key created on claude.ai by the primary owner, distinct from the admin key, and only provides tokens for usage-billed plans: on a seat plan, activity is available, but CO₂e there would be derived from activity counters and not real tokens, hence estimated. We activate this path on request.
• Every line of the report carries a label: measured, estimated or declared. What is not measurable is written "not covered". No implicit estimate replaces it.

Excluded models (non-Anthropic)

Claude Code can be pointed at non-Anthropic models (for example a local model behind ANTHROPIC_BASE_URL). Their impact profile is not that of an AWS datacenter: neither the energies nor the API pricing apply. Sessions whose dominant model does not contain claude (including the <synthetic> marker) are not pushed by the CLI.

Displayed equivalences

To make the units tangible, the dashboard displays equivalences. All are sourced:

• Water: 60 L showers (primary displayed equivalence, round(water_ml / 60_000), function waterToShowers of lib/co2.ts; below one shower, no equivalence is displayed).
• CO₂e, car: 120 gCO₂e per kilometre, ADEME factor for an average European passenger car (well-to-wheel, weighted petrol-diesel-hybrid mix). car_km = round(co2_grams / 120), function co2ToCarKm of lib/co2.ts.
• CO₂e, reference prompt: a median Gemini prompt emits 0.09 gCO₂e location-based (Google 2025, arXiv:2508.15734).

Assumptions and uncertainties

The min-best-max ranges per parameter are in the "Anthropic parameters" table. The dominant levers on the final figure, in estimated order of importance:

• cache_read_factor (0.08): cache reads represent more than 90% of tokens in intensive Claude Code usage. Range 0.05-0.20, about -40%/+150% on the cache term.
• Location (±30% on the CIF): AWS/GCP/Azure/Colossus split not published by Anthropic.
• E_out Fable: price proxy with no published measurement, on the most expensive family of the catalogue.
• E_in = E_out/6 (non-Anthropic providers): published range E_out/26 to E_out/4, choice in the upper half. For Anthropic, the ~1/21 ratio is recovered from the v6 fit; it is no longer a free assumption.
• EMB (44): sensitivity 22-66. Since v3.7 this bracket has been presented as an amortisation uncertainty; that is inaccurate, it aggregates several sources of uncertainty, and the "3-6 years" label was removed from the table rather than implying a single cause.
• Unknown silicon: the whole hardware chain assumes an NVIDIA fleet. Anthropic also serves on Trainium2 and on TPU, with no published split. Neither the embodied term nor GPU-measured energies cover that case.
• Constant E_out in long context: per-token decode energy rises from 107 to 242 mJ between 4K and 16K of context on GQA (arXiv:2605.11999), a factor of 2.26, while our E_out is flat. The bias runs toward underestimation in the agentic regime, precisely the regime the Bilan measures.

Annex: ADPe (informational)

Abiotic depletion potential, elements (ADPe) is the third priority indicator of AFNOR Spec 2314 (priority 1). v3 documents it for information: no database column, no UI.

Usage: adpe = energy_kwh × 9.855e-8 kgSbeq/kWh (ADEME Base Empreinte factor, via EcoLogits). Per million tokens, on the v3 IT energies:

This term only covers the "usage" share (electricity). The manufacturing share of ADPe, dominant for this indicator, would require a full material LCA that v3 does not do.

Claims that circulate wrong

While verifying our own sources, we ran into six statements that circulate in articles, tender documents and reports, and that are wrong against the text they cite. We publish them because a reader may put them to us, and because nobody else corrects them.

1. "Article 53 of the AI Act requires documenting energy." Article 53(1)(a) requires technical documentation; it is Annex XI, Section 1, point 2(e) that carries the energy obligation. The exact citation to use is "Article 53(1)(a), and Annex XI, Section 1, point 2(e)".
2. "Annex XI covers training energy." The text says "known or estimated energy consumption of the model". It is the preceding point, 2(d), that targets training compute resources.
3. "SCI for AI gives 130 kgCO₂e per billion tokens." That value is marked EXAMPLE in the Green Software Foundation specification, illustrative and non-normative. It is nobody's emission factor. The specification provides no default values at all, no PUE, no grid factor, no amortisation period.
4. The tiers of the Llopis methodology (arXiv:2606.10660) cited in reverse. The paper's order is: Tier 3 = certified supplier carbon reporting, the best; Tier 2a = exact token counts; Tier 2b = estimated tokens; Tier 1 = spend-based, the worst. There is no Tier 4. The paper notes in passing that no major AI provider offered certified carbon reporting as of May 2026.
5. "AWS market-based = 0." AWS claims 100% renewable matching but publishes no market-based kg/kWh factor, and reported 2.80 MtCO₂e of residual market-based scope 2 in 2024. The correct value is "not published by AWS".
6. "Cache is carbon-neutral." No normative framework, SCI for AI included, addresses caching. The absence of a rule is not a rule: see "Cache energy".

Caveats

What we do not measure, and why.

• Order of magnitude only. These figures are structured, sourced estimates, not a regulatory report nor a verified LCA.
• Datacenter third, inference-only scope. Devices (~50% of the digital footprint in France), networks (~4%) and training are excluded (Arcep report, May 2026).
• The cache term does not have the right shape. It captures a prefill residual; the KV re-read residual during decode, bilinear in (context × generated tokens), is absorbed into a constant E_out. See "Cache energy". It is the most important lever of the final figure.
• Anthropic's real hardware fleet is not published (NVIDIA, Trainium2, TPU). None of our hardware values covers it.
• No ground truth exists on energy. Nothing lets us reconcile our Wh against a measurement. The only available check is on cost, via ccusage, and it does not validate the physics.
• No geo-specific coverage. CIF applied uniformly, ±30% sensitivity to the real location.
• Fable is a price extrapolation. No published measurement, to be revised as soon as an independent one appears (Epoch AI or equivalent).
• Embodied carbon is a derivation, not an end-to-end manufacturer figure: NVIDIA PCF + BoaviztAPI, amortised over 5 years, sensitivity 22-66 gCO₂e/kWh.
• Water is an estimated consumption, not an ISO 14046 footprint: no weighting by local water stress, and the total adds a withdrawal (WUE) to a consumption (EWIF), see "On water".
• AWS market-based not published. AWS publishes no market-based kg/kWh factor: we write it as such, we never display zero.
• No cancelled sessions. An interrupted session counts the tokens already generated, in line with Anthropic's billed usage.
• Subagents aggregated into the parent. If Claude Code launches subagents during a session, their tokens are summed into the parent session under its dominant model (see cli/scripts/persist-and-push.sh). A small approximation when a subagent runs on another Claude family.
• History before 2026-06-12. Rows ingested before that date carry an input_tokens that includes cache writes, and their co2/cost did not count the cache_read term. They are kept as is (slight underestimation).

How to verify

The TokenClimate CLI exposes a command that shows the local values before push, identical to what will be ingested on the dashboard side:

tokenclimate org status

You will see per session: input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, detected model, and the computed impact. If you want to audit the calculation end-to-end, compare with the session detail displayed on /employee/[id] of the dashboard.

All energies, all parameters and all prices used are published in this document, with their sources. Test vectors give exact expected values for energy_wh, co2_grams and water_ml, replayed in CI on every change. No value is computed on an opaque client side.

Recomputability

Each usage_events row keeps its raw components (input, output, cache write, cache read): energy_wh, co2_grams, water_ml and cost_usd remain re-derivable at any time from the current methodology. After a parameter or pricing change, pnpm recompute:co2 (script scripts/recompute-co2.ts, dry-run by default, --apply to write) recomputes the whole history with the functions of lib/co2.ts and restamps factor_version. Rows whose model does not resolve in the registry keep a null impact, never an invented one.

Versioning

The current version is v3.7-methodology-2026-08. Parameters are renewed at least once a year (AFNOR Spec 2314 requirement), and earlier if a pinned source moves: new version of Jegham et al., EcoLogits release, publication of a Fable measurement, AWS market-based factor. Every evolution produces a new version of this document.

Since v3.8 that promise has a mechanism rather than an intention. Pinned sources live in a versioned registry (data/sources/registry.json) recording, for each one, what we pinned, what it feeds, and when a human last re-read it. A weekly check queries arXiv and upstream releases, and two alerts block CI: a source that moved past what was explicitly acknowledged, and a factor unreviewed for more than twelve months. Deliberate gaps are handled: EcoLogits is pinned at 0.10.2 for Google and Mistral while the current OpenAI range is sourced from 0.11.1, and that is recorded as such rather than raised every week.

The EcoLogits tool, pinned here at release 0.10.2, is cited by the MiNumEco factsheet of November 2025, whose measurement requirement takes full effect in August 2026. The wording shipped with the AI usage report points to this section for verification.

History:

• v3.8-methodology-2026-08: on-site WUE 0.18 → 0.12 L/kWh, re-sourced on the first-party AWS disclosure (2025 vintage) instead of the Amazon 2023 report; PUE 1.14 unchanged but re-sourced the same way. The parameter block becomes explicitly composite. Tier reclassification: CIF and EWIF T1 → T2, cache_read_factor T3 → T2, E_in/E_out ratio T2 → T3. Published range of cache_read_factor widened from 0.05-0.15 to 0.05-0.20. "Cache energy" rewritten around the Irminsul measurement, including the finding that the term does not have the right shape. "On water" (withdrawal plus consumption) and "Assumed location" (Colossus 1, Memphis) rewritten. The 5-year amortisation is now sourced. New sections "Validity date of the energies", "Sensitivity note: the overestimation charge" and "Claims that circulate wrong". Three caveats added. No change to the equations, to per-model energies or to prices; CO₂e does not move for any model, water drops 1.0% on the Anthropic side.
• v3.7-methodology-2026-08: removal of the "Use cases (one occurrence)" section and its table on the public calculator: per-task volumes judged too imprecise for a public surface (mostly T3). Usage profiles remain; no change to equations, factors or prices.
• v3.6-methodology-2026-08: added the "Usage profiles of the public calculator" section (reference volumes per token class, token-based use cases, sources and tiers); no change to equations, factors or prices.
• v3.5-methodology-2026-07: added the "Source coverage" section (surfaces measured by the admin key, claude.ai chat and Cowork out of scope on Team plans, Enterprise case); no calculation change.
• v3.4-methodology-2026-07: current OpenAI range enters the catalogue (gpt-5.6, gpt-5.5, gpt-5.4, sourced from EcoLogits 0.11.1 or price-extrapolated with low confidence); the ten previous OpenAI models become legacy, factors kept to quantify past usage.
• v3.3-methodology-2026-07: added a paragraph explicitly linking EcoLogits (pinned release) to the MiNumEco factsheet of November 2025, cited by the AI usage report wording; no methodological change.
• v3.2-methodology-2026-07: DeepSeek recalibration (direct Jegham v6 DS-native measurements) and OpenAI (Table 1 verbatim), Meta provider added.
• v3.1-methodology-2026-07: Anthropic energies recalibrated on the Jegham v6 3-point OLS fit (Sonnet 119/2525 Wh/Mtok, previously 580/3480); the Anthropic input/output ratio becomes a measured value (~1/21) instead of the 1/6 convention; Opus moves from 3x to 2x Sonnet. Prices, infra parameters, cache_read_factor and formulas unchanged.
• v3.0-methodology-2026-06: energy-first switch (Wh/Mtok + infra parameters), water and embodied added.

Contact

You dispute a value, a parameter, an assumption? Write to gaetan.wittebolle@gmail.com. Substantiated corrections are welcome; the goal is not to defend the figures but to have the best possible estimate with the available data.