AI factors API

GET https://app.somaai.earth/api/v1/ai-factors returns SOMA's AI-inference emission factors — carbon, water, uncertainty, tier, factor version and sources — for a model id, provider and cloud region. Every figure is a modelled estimate from published benchmark energy, grid intensity and lifecycle terms. Leave out model and it returns the full table instead of one row.

Method: app.somaai.earth/methodology. Dataset: 10.5281/zenodo.20443585 (concept DOI — always the latest version), SOMA factor version soma-ai-ef-2026.10-dataset-v3.0.0 (SOMA's own pinned version, not the dataset's), CC BY 4.0. The concept DOI resolves to the latest dataset version; the earlier version 2 values are record 10.5281/zenodo.22767475. Record status, v3 record: 10.5281/zenodo.23371447.

Send an API key as a bearer token: Authorization: Bearer sk_soma_.... Keys are issued to partners by SOMA and carry the ai_factors scope.

There is no self-serve signup yet. To request a key, write to guillermollopis@somaai.earth.

Query parameters, all optional:

• model — the model id as billed, e.g. claude-sonnet-4-5 or openai/gpt-4o. Omit it to get the full table (see below) instead of one row. If SOMA doesn't recognise the id, the row is computed for class C and class_assumed is true. A model id the dataset marks out of scope (embedding, speech, image, video, moderation, rerank) is refused with 422.
• provider — pins a cloud region id to that provider. When region is absent the serving region comes from the model and provider: glm-*, mistral-* and deepseek-v4-flash-0731 are priced in eu-west-3 (France), claude-* models and the openai, anthropic, aws, bedrock and azure providers in us-east-1 (US East), and everything else on the global-average grid. In every one of those cases region_assumed is true.
• region — one of the 17 printed regions (eu-north-1, eu-west-3, europe-north1, europe-west1, eu-27, europe-west2, europe-west4, eu-west-1, eu-central-1, us-east-1, us-west-2, us-south-central, us-south, us-central1, ap-southeast-1, ap-northeast-1, global-average), any ISO-3 country code, an eGRID subregion, or any AWS, GCP or Azure region id. If it isn't recognised, the global-average grid is applied (not the provider's default region) and region_assumed is true.

curl "https://app.somaai.earth/api/v1/ai-factors?model=claude-sonnet-4-5&provider=anthropic&region=eu-west-1" \
  -H "Authorization: Bearer sk_soma_..."

The row above, computed live from the same code this page runs:

{
  "model": "claude-sonnet-4-5",
  "model_class": "B",
  "model_class_label": "Class B — Mid",
  "class_assumed": false,
  "tier": "2a",
  "is_reasoning": false,
  "region": "eu-west-1",
  "region_label": "EU West - Ireland",
  "region_assumed": false,
  "kg_co2e_per_million_tokens": {
    "central": 0.0245398,
    "lower_bound": 0.017650063760268855,
    "electricity": 0.020139146751306947,
    "embodied": 0.001011396004480956,
    "construction": 0.0004550609036594473,
    "training": 0.00293425,
    "development_separate": 0.027462448095593728
  },
  "basis": {
    "effective_tokens": 302464.52576549666,
    "billed_tokens": 1000000,
    "w_in": 0.3,
    "w_cache": 0.05
  },
  "high_case": 0.038093,
  "class_range": {
    "low_pct": -38.595737472666244,
    "high_pct": 22.84599086121304
  },
  "own_model": null,
  "grid": {
    "id": "IRL",
    "source": "Ember yearly electricity data, CO2 intensity 2023, 282.5 g/kWh (lifecycle, IPCC AR5)",
    "year": 2023
  },
  "litres_water_per_million_tokens": 0.10601302108342046,
  "uncertainty_pct": 39,
  "factor_version": "soma-ai-ef-2026.10-dataset-v3.0.0",
  "dataset_doi": "10.5281/zenodo.20443585",
  "dataset_version": "dataset dated 2026-10-19",
  "dataset_model_class": "class_b_mid",
  "factor_note": null,
  "method_note": "Modelled estimate: benchmark GPU energy × facility overhead × regional grid intensity, plus lifecycle add-ons. Not a measurement of your provider's infrastructure.",
  "sources": [
    "ML.ENERGY Leaderboard v3 (May 2026)",
    "EPA eGRID 2023",
    "Ember Yearly Electricity Data 2023",
    "Li et al. 2025 (WUE)",
    "Reig et al. 2020 (EWIF)",
    "Llopis, G. (2026), Accounting for Purchased AI Inference in Corporate GHG Inventories: A Token-Based Method",
    "SOMA AI inference emission factors, dataset v3.0.0 (2026-10-19), concept DOI 10.5281/zenodo.20443585; v3 record: 10.5281/zenodo.23371447"
  ],
  "methodology_url": "https://app.somaai.earth/methodology"
}

• model — the model id as sent in the request.
• model_class — SOMA's size class for the model: A (small), B (mid) or C (frontier).
• model_class_label — a human-readable label for model_class.
• class_assumed — true when the model id wasn't recognised and class C was assumed.
• tier — the accounting tier this factor supports; always 2a (exact token counts).
• is_reasoning — true when the dataset flags the model as a reasoning model by default. The API returns factors for billed tokens, which already include the extra reasoning tokens, so it applies no multiplier. Estimates from message counts apply the Tier 2b uplift, where no public source gives the multiplier and k is an author assumption.
• region — the region id the factor was computed for (a printed region, a cloud region, a grid id, or global-average).
• region_label — a human-readable name for region.
• region_assumed — true when no region was given (the default for the model and provider was used) or the region given wasn't recognised (the global-average grid was used); false when the region you passed was recognised.
• kg_co2e_per_million_tokens — carbon per million billed tokens of the dataset's default input/output mix, no cache credit: central, and the four terms electricity, embodied (server hardware), construction (data-centre construction) and training (amortised), which sum to central only to the dataset's published precision: for a model class central and high_case are the dataset's published cells, and the terms are calculated from the same constants. lower_bound is the B200 value at the same basis (a hardware sensitivity, not a bound; for class C it sits above the central). development_separate is model development, reported beside the total and never added to it, or null.
• basis — what "per million tokens" means: billed_tokens (the million), effective_tokens (billed tokens weighted by w_in for uncached input and w_cache for cached input, divided by the benchmark-to-billing factor), and the two weights.
• high_case — the same figure with the dataset's high-case constants, or null.
• class_range — { low_pct, high_pct }, the spread of the benchmarked models inside the class around the class value at this grid, as signed percentages; null for a model with its own factor.
• own_model — the benchmarked model id when the dataset has factors for this exact model, otherwise null.
• grid — the grid row behind the electricity term: id, source and year.
• litres_water_per_million_tokens — water per million billed tokens, the same basis as the carbon fields (basis gives the effective-token split if you need to convert): on-site cooling plus the water behind the grid electricity (hydro allocated), or null where the dataset has no water factor for the region.
• uncertainty_pct — the larger side of the class range, rounded up; for a model with its own factor, the high case's distance from the central.
• factor_version — SOMA's pinned factor version this row was computed from.
• dataset_doi — the concept DOI of the published dataset; it resolves to the latest version.
• dataset_version — which dataset copy the figures come from (its date). The dataset's own record DOIs are in the citation above.
• dataset_model_class — the dataset's own class id behind this row, or null when the class was assumed.
• factor_note — a caveat on the row, or null.
• method_note — one sentence saying the figure is a modelled estimate, not a reading of your provider's infrastructure.
• sources — the underlying data sources cited for this row.
• methodology_url — link to the SOMA methodology page.

Without model, data is an array of one row per model class and grid — 738 rows today (3 model classes × 240 grids, then one row per benchmarked model at the global-average grid, 18 models).

• 401 — the key is missing or invalid.
• 403 — the key doesn't carry the ai_factors scope.
• 422 unsupported_modality — for embedding, speech, image, video, moderation and rerank model ids. Body: { error, modality, model, message }. Factors cover chat and completion models only.
• 429 — rate limit exceeded: 120 requests per minute per key. The response carries a Retry-After header.
• 405 — anything other than GET.

Responses carry Cache-Control: private, max-age=86400. The factor version changes whenever a table changes, and partners are told when it does. Cite the version shown with every figure you display.

Factors are versioned snapshots: a published version never changes, and a new dataset release gets a new version. A company that cites a factor should name the version it used.

Version history

• 3.0.0, published 2026-10-15, record 10.5281/zenodo.23371447, SOMA factor version soma-ai-ef-2026.10-dataset-v3.0.0.
  • Four-term lifecycle boundary (electricity, embodied hardware, data-centre construction and training) with a separate development line.
  • Effective-token basis with input weight W_in 0.30 and a per-run prefix-cache share; 0.3025 effective tokens per billed token at the default mix.
  • Three model classes (A small, B standard, C frontier), each the mean of its measured members: 18 open-weight models on H100 and B200 from the ML.ENERGY Leaderboard v3. Versions 1 and 2 used a named proxy model per class.
  • Coverage of 210 countries, 27 eGRID subregions and 143 cloud regions, with water for 17 regions using AWARE 2.0.
  • Monte Carlo uncertainty ranges.
  • The reasoning uplift for Tier 2b applies to output tokens only.
  • Headline spreads on the inference footprint: class A to C about 12x, Singapore to Sweden about 9x (electricity only about 13x).
• 2.0.0, published 2026-09-15, record 10.5281/zenodo.22767475, SOMA factor version soma-ai-ef-2026.09-lifecycle-v2.
  • Added regions France (eu-west-3), Finland (europe-north1), UK (europe-west2), Belgium (europe-west1) and Iowa (us-central1).
  • Completed the carbon rows for us-west-2, us-south-central and us-south.
  • Corrected two v1 rows: us-east-1 class B carbon from 0.04380 to 0.04378 kg CO2e per M tokens, and Sweden class C water from 1.254 to 1.253 L per M tokens.
  • Introduced lifecycle add-ons (embodied hardware and training amortisation).
  • Restated the headline regional spread from 13x to 12x electricity only and about 6x with add-ons, the earlier figure being a rounding artefact.
• 1.0.0, published 2026-06-09, record 10.5281/zenodo.20443586, SOMA factor version soma-ai-ef-2026.09-lifecycle-v1.
  • First release, accompanying arXiv 2606.10660 v1.
  • Four classes (small, mid, large MoE, large dense).
  • Electricity-only factors per region and class.
  • Regional spread about 13x, Singapore to Sweden.

Any figure you display to your own users must say "carbon data powered by SOMA", linking to app.somaai.earth/methodology.