crbonfree 0.3.0

Python SDK for the CrbonFree carbon-offset API

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

	Method	What it returns
Measure	crbon.telemetry.get_summary()	Total CO₂, per-model rollups, daily chart
Analyze	crbon.usage.get_breakdown()	Which models cost the most carbon
Organize	crbon.projects.list()	Track emissions by project / team
Track	crbon.billing.get_retirement_status()	Where the current period sits in its retirement lifecycle
Prove	crbon.billing.list_receipts()	Signed carbon retirement receipts
Audit	crbon.billing.list_audit_packs()	CSRD-ready compliance artifacts

Full API surface (4 sub-clients, 12 methods)

Sub-client	What it does	Methods
crbon.projects	Workspace organization	list()
crbon.usage	Aggregated analytics	get_summary(), get_breakdown(), get_daily(), export_daily()
crbon.telemetry	Emissions rollups	get_summary(), list_models()
crbon.billing	Retirement, receipts + compliance	get_retirement_status(), list_receipts(), get_receipt(), list_audit_packs(), get_audit_pack()

Every sync method has an async twin on AsyncCrbonFree.

---

Authentication

Auto-login (recommended — zero config after first run)

crbonfree login

Saves your API key to ~/.crbonfree/credentials (the same file the MCP server and TS SDK use). The client reads it automatically — no constructor args needed:

from crbonfree import CrbonFree

crbon = CrbonFree()

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

Explicit API key (for CI / env-var workflows)

import os
from crbonfree import CrbonFree

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

Or set the variable and let the client pick it up:

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

All error types

Error	Status
BadRequestError	400
UnauthorizedError	401
PaymentRequiredError	402
ForbiddenError	403
NotFoundError	404
ConflictError	409
TooManyRequestsError	429
InternalServerError	500
ServiceUnavailableError	503

All are importable from crbonfree and extend ApiError (crbonfree.core.api_error) with status_code, headers, and body. Missing credentials raise MissingCredentialsError.

---

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