crbonfree 0.4.1

crbonfree

Measure and offset the carbon footprint of your AI workloads.
One SDK. Every major provider. Verified retirement receipts.

pip install crbonfree

Get started

1. Log in (one command — no dashboard needed)

crbonfree login

Opens your browser, creates an account (or signs in), generates an API key, and saves it locally.

2. Use the SDK

from crbonfree import CrbonFree

crbon = CrbonFree()  # reads saved credentials automatically

summary = crbon.telemetry.get_summary()
print(f"{summary.data.total_co2_kg} kg CO₂ from your AI usage")

No API key to copy-paste. No env vars to set. Just crbonfree login and go.

Works with

OpenAI  ·  Anthropic  ·  OpenRouter  ·  AWS Bedrock  ·  and growing

Connect your provider accounts. We meter the inference. You get the emissions data + signed retirement receipts.

What you can do

Authentication

crbonfree login

from crbonfree import CrbonFree

crbon = CrbonFree()

crbonfree logout   # remove saved credentials
crbonfree whoami   # check who you're logged in as

import os
from crbonfree import CrbonFree

crbon = CrbonFree(api_key=os.environ["CRBONFREE_API_KEY"])

export CRBONFREE_API_KEY="ck_live_..."

crbon = CrbonFree()

The client authenticates exclusively with an API key, sent as the X-API-Key header — there is no bearer-token path. When you omit api_key, the key is resolved in order: the explicit api_key= argument → the CRBONFREE_API_KEY environment variable → the ~/.crbonfree/credentials file written by crbonfree login. If none are found it raises MissingCredentialsError (importable from crbonfree.client). Keys look like ck_live_….

Async

import asyncio
from crbonfree import AsyncCrbonFree

async def main():
    crbon = AsyncCrbonFree()  # same credential resolution as the sync client
    summary = await crbon.telemetry.get_summary()
    print(f"{summary.data.total_co2_kg} kg CO₂ from your AI usage")

asyncio.run(main())

Pagination

Listing endpoints accept page and limit directly, but the helpers drive the page loop for you:

from crbonfree.pagination import auto_paginate, collect_all

# Stream every item across all pages
for receipt in auto_paginate(crbon.billing.list_receipts, limit=100):
    print(receipt.serial_number)

# Or pull everything into a list at once
receipts = collect_all(crbon.billing.list_receipts, limit=100)

Async clients get auto_paginate_async and collect_all_async. These apply to the paginated list endpoints — billing.list_receipts and billing.list_audit_packs. Capped-list endpoints (projects.list, telemetry.list_models) return plain lists and need no pagination.

Error handling

Failed requests raise typed exceptions carrying the status code and parsed body:

from crbonfree import CrbonFree, NotFoundError

crbon = CrbonFree()

try:
    crbon.billing.get_receipt(id="nope")
except NotFoundError as err:
    print(err.status_code, err.body)  # 404, with a typed ErrorResponse

Configuration

from crbonfree import CrbonFree

crbon = CrbonFree(
    api_key="...",                 # explicit key (overrides env + saved credentials)
    timeout=30,                    # seconds
    max_retries=3,
    base_url="https://custom.api/",
)

MCP server

Want to give AI agents direct access to your carbon data? Check out @crbonfree/mcp — works with Claude Desktop, Cursor, and any MCP-compatible client, and shares the same ~/.crbonfree/credentials login.

Dashboard  ·  Issues  ·  Website

_{MIT — Crbon Labs Inc.}