AI factors API

GET https://app.somaai.earth/api/v1/ai-factors returns the SOMA AI Emission Factors (SAEF): carbon, water, uncertainty, tier, factor version and sources for a model id, provider and cloud region. The endpoint is served by the SOMA app; this page is its documentation. 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: somaai.earth/ai-footprint/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 earlier version 2 values are record 10.5281/zenodo.22767475. Record status, v3 record: 10.5281/zenodo.23371447. If you only need the tables, download the CSV instead.

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, for example claude-sonnet-4-5 or openai/gpt-4o. Omit it to get the full table (see below) instead of one row. If SOMA does not 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 is not 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_..."

An example row, computed from the same code and data as the endpoint (the method_note sentence is shortened here):

{
  "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.",
  "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-Garcia, 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://somaai.earth/ai-footprint/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 was not 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 token count from billing already includes the extra tokens, so this endpoint applies no multiplier. Estimates built from message counts apply the Tier 2b uplift described in the methodology.
• 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 was not 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 and output mix, no cache credit. It holds 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, and 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 is the million, effective_tokens is billed tokens weighted by w_in for uncached input and w_cache for cached input, divided by the benchmark-to-billing factor.
• 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, with id, source and year.
• litres_water_per_million_tokens: water per million billed tokens, on the same basis as the carbon fields: 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, which resolves to the latest version.
• dataset_version: which dataset copy the figures come from (its date).
• 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 of the serving chain, 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). The region-by-class table that this site publishes is a subset of it, available without a key as a CSV download and on the SOMA AI Emission Factors (SAEF) page.

• 401: the key is missing or invalid.
• 403: the key does not 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. Every version and what changed in it is on the changelog.

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

• Methodology. What each field means and how it is built
• SOMA AI Emission Factors (SAEF) table and download
• Changelog
• Using the factors in a Scope 3 inventory