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. 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), current version 2.0.0 at 10.5281/zenodo.22767475, CC BY 4.0.

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 B and class_assumed is true.
• provider — used to pick the default region only when region is absent. greenpt defaults to EU France; openai, anthropic, aws, bedrock and azure default to US East; anything else defaults to the global average.
• region — an AWS, GCP or Azure region id (eu-west-1, europe-west2, westeurope) or one of SOMA's own region ids. If it isn't recognised, the provider's default region is used instead 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_ireland",
  "region_label": "EU Ireland",
  "region_assumed": false,
  "kg_co2e_per_million_tokens": {
    "central": 0.05311,
    "lower_bound": 0.02321,
    "electricity": 0.046,
    "embodied": 0.00303,
    "training": 0.00408
  },
  "litres_water_per_million_tokens": 0.241,
  "uncertainty_pct": 50,
  "factor_version": "soma-ai-ef-2026.09-lifecycle-v2",
  "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)",
    "Dell PowerEdge XE9680 PCF (Apr 2025), NVIDIA HGX H100 PCF (ISO 14067), 5 yr / 60% utilisation",
    "Meta Llama 3.1 model card, location-based, over 500 T tokens served"
  ],
  "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 B was assumed.
• tier — the accounting tier this factor supports; always 2a (exact token counts).
• is_reasoning — true when the model id matches a known reasoning-model pattern (extended thinking generates far more tokens per query).
• region — the cloud region the factor was computed for.
• region_label — a human-readable name for region.
• region_assumed — true when the requested or derived region wasn't recognised and a provider default was used instead.
• kg_co2e_per_million_tokens — carbon per million tokens: a central estimate, a lower bound, and the electricity / embodied-hardware / training components that sum to the central estimate.
• litres_water_per_million_tokens — water per million tokens.
• uncertainty_pct — the stated uncertainty band on the central estimate.
• factor_version — the factor table version this row was computed from.
• 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 region — 48 rows today (3 model classes × 16 regions).

• 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.

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