---
title: "Estimate CO2e, electricity, and water from token buckets"
method: POST
path: "/api/v1/public/emissions-estimate"
tags: ["Usage"]
---

# Estimate CO2e, electricity, and water from token buckets

`POST /api/v1/public/emissions-estimate`

## Request

- Base URL: `https://api.crbonfree.com`
- URL: `https://api.crbonfree.com/api/v1/public/emissions-estimate`
- Auth: none required
- TypeScript: <https://skmtc.dev/crbonfree/apis/crbonfree-api/docs/api/v1/public/emissions-estimate/post.ts> (a function with typed inputs; its response is checked against the schema)

Runs the exact same factor-resolution and emissions math path the worker uses before writing carbon_calculations. Accepts a model id plus token buckets and returns CO2e, electricity, and water estimates with the same metadata fields the worker persists.

## Request body

- PublicEmissionsEstimateRequest
  - `model` string, required: Model id matched against carbon_factors exactly like the worker ingestion path.
  - `inputTokensUncached` integer
  - `inputTokensCached` integer
  - `inputTokensCacheCreation` integer
  - `outputTokens` integer

## Response `200`

Emissions estimate

- object
  - `success` true, required
  - `data` PublicEmissionsEstimate, required
    - `energyJoules` number, required
    - `energyKwh` number, required
    - `co2Kg` number, required
    - `co2LowerBoundKg` number, required
    - `co2UpperBoundKg` number, required
    - `waterLiters` number, required
    - `waterLowerBoundL` number, required
    - `waterUpperBoundL` number, required
    - `waterFactorsVersion` string, required
    - `modelTier` string, required
    - `pue` number, required
    - `gridIntensity` number, required
    - `uncertaintyPct` number, required
    - `factorsVersion` string, required

## Other responses

- `400`: Bad request — validation failed or malformed JSON body
- `401`: Unauthorized — token missing, expired, or invalid
- `429`: Too many requests — rate limit exceeded
- `500`: Internal server error

## Changes

- **2026-08-14** `7d245a8d7a75`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/crbonfree/apis/crbonfree-api/changes/api/v1/public/emissions-estimate/post.md)

---

[API](https://skmtc.dev/crbonfree/apis/crbonfree-api.md) - [All operations](https://skmtc.dev/crbonfree/apis/crbonfree-api/llms.txt) - [OpenAPI document](https://skmtc.dev/crbonfree/apis/crbonfree-api/revisions/a21ffdb80e67?raw)