API Documentation
Real-time carbon intensity, cost, and speed data for AI inference across providers and regions. All endpoints return JSON. No authentication required for the public API.
https://carbonbench.ai
Endpoints
Returns a ranked list of model + provider + region combinations, sorted by carbon intensity by default. Each entry includes cost, carbon emissions, speed, and rank.
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| model | string | Filter by model family: llama, gpt, claude, mistral, gemma, qwen, deepseek, phi |
| provider | string | Filter by provider (comma-separated): aws, gcp, azure, together, groq, fireworks |
| sortBy | string | Sort order: carbon (default), cost, or speed |
| limit | number | Max results (default 50, max 200) |
curl "https://carbonbench.ai/api/leaderboard?model=llama&sortBy=carbon&limit=5"
{
"data": [
{
"modelId": "meta-llama/llama-3.1-8b",
"displayName": "Llama 3.1 8B",
"family": "llama",
"provider": "gcp",
"region": "GCP Europe West (Netherlands)",
"regionCode": "europe-west4",
"costPerMTokens": 0.20,
"carbonPerMTokens": 4,
"tokensPerSec": 100,
"calculatedAt": "2026-04-17T15:00:01.000Z",
"rank": { "byCost": 2, "byCarbon": 1 }
}
],
"meta": {
"lastUpdated": "2026-04-17T15:00:01.000Z",
"totalModels": 85,
"totalProviders": 6
}
}Returns the lowest-carbon option for a model family, with up to 4 alternatives and a human-readable insight string explaining the recommendation.
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| modelrequired | string | Model family to find the lowest-carbon option for |
| maxCostPerMTokens | number | Maximum cost constraint in USD per million tokens |
| maxLatencyMs | number | Maximum latency constraint in milliseconds |
curl "https://carbonbench.ai/api/recommend?model=llama&maxCostPerMTokens=1"
{
"recommendation": {
"modelId": "meta-llama/llama-3.1-8b",
"displayName": "Llama 3.1 8B",
"provider": "gcp",
"region": "GCP Europe West (Netherlands)",
"costPerMTokens": 0.20,
"carbonPerMTokens": 4,
...
},
"alternatives": [ ... ],
"insight": "Gcp (Netherlands) is the lowest-carbon option for Llama 3.1 8B right now — 4 gCO2/M tokens, 67% less than the highest option, at $0.20/M tokens.",
"constraints": {
"model": "llama",
"maxLatencyMs": null,
"maxCostPerMTokens": 1
}
}Returns carbon intensity history for a specific region. Use this to build time-of-day charts showing when carbon is lowest.
| PARAMETER | TYPE | DESCRIPTION |
|---|---|---|
| regionrequired | string | Region code: us-east-1, us-west-2, eu-west-1, europe-west4, us-central1, etc. |
curl "https://carbonbench.ai/api/carbon/us-west-2"
{
"data": [
{ "time": 1713340800, "value": 193 },
{ "time": 1713344400, "value": 187 },
{ "time": 1713348000, "value": 210 }
],
"meta": {
"region": "AWS US West (Oregon)",
"regionCode": "us-west-2",
"zone": "US-NW-PACW",
"latestValue": 193,
"latestAt": "2026-04-17T14:00:00.000Z"
}
}Returns carbon intensity data for all regions. Used for multi-series comparison charts.
curl "https://carbonbench.ai/api/carbon/all"
Returns database row counts for each table. Use this to verify data is flowing correctly.
curl "https://carbonbench.ai/api/health"
{
"data": {
"regions": 9,
"models": 85,
"benchmarks": 85,
"pricing": 92,
"scores": 184,
"readings": 9
},
"meta": { "timestamp": "...", "status": "healthy" }
}Data
Carbon intensity — sourced from Electricity Maps, updated daily. Measured in gCO2eq per kWh for each electricity grid zone.
Energy benchmarks — GPU energy consumption per model from the AI Energy Score project (measured on NVIDIA A100) and ML.Energy leaderboard.
Provider pricing — collected from published pricing pages for AWS Bedrock, GCP Vertex AI, Azure OpenAI, Together AI, Groq, and Fireworks AI.
Carbon per million tokens is calculated as: energy_per_token × grid_carbon_intensity. This means the same model produces different carbon in different regions at different times.