How does it authenticate, and where is the key stored?

With an API key only, sent as the X-API-Key header on every request. Running crbonfree login opens the browser, generates a key that starts with ck_live_ and writes it to ~/.crbonfree/credentials with owner-only permissions. The TypeScript SDK and the MCP server read the same file. In CI, set CRBONFREE_API_KEY or pass api_key to the constructor; an explicit key wins over the variable, and the variable wins over the file. If none of the three is present the constructor raises MissingCredentialsError.

Can I use it from async code?

Yes. AsyncCrbonFree has the same four sub-clients and the same twelve methods as CrbonFree, each returned as a coroutine you await, and it resolves credentials the same way. It runs on an httpx async client by default. For the paginated endpoints, auto_paginate_async and collect_all_async in crbonfree.pagination take a bound async method and walk the pages for you.

What data does it return, and does it meter anything?

It returns what the backend has already computed for your organisation: token totals, CO2e in kilograms with upper and lower bounds, electricity in kilowatt hours, per-model and per-day breakdowns, the retirement status of the current billing period, signed receipts with their serial allocations and verification URLs, and monthly audit packs. It meters nothing and has no method for sending usage in. Metering happens elsewhere in the platform; this package only reads the results.

Which methods paginate, and is there a helper?

Only billing.list_receipts and billing.list_audit_packs paginate, with page and limit arguments and a pagination block in the response that carries page, limit, total and total_pages. The crbonfree.pagination module exports parse_page to normalise one page, auto_paginate to yield every item across pages, and collect_all to gather them into a list, each with an async twin. projects.list and telemetry.list_models return capped plain lists, and the other operations return in a single call.

The package is free and MIT licensed. Reading usage and carbon estimates works on the free plan. Receipts and audit packs are part of the paid plans, so those two billing endpoints answer a free organisation with a 402 and an upgrade link.

crbonfreev0.4.0Build on your numbers

Read your usage, emissions and receipts from Python.

One package gives you a synchronous client and an asynchronous twin for the twelve public API operations. Both return the numbers the backend has already computed, so a notebook, a scheduled job or an internal report shows the same figures your dashboard does.

Install and sign in

pip install crbonfree && crbonfree login

View on PyPI Read the API reference

example

4,500+

SDK and MCP downloads with no paid marketing

Crbon Labs, 2026

public read operations covered, one method each

clients, sync and async, from one package

203,000

verified credits issued, readable as receipts

Crbon Labs, 2026

What is the Python SDK?

The CrbonFree Python SDK, published as crbonfree on PyPI, is a typed client for the twelve public read operations of the CrbonFree API, in synchronous and asynchronous form. It returns usage totals, emissions with their uncertainty bounds, credit retirement receipts and audit packs that the backend has already computed, so a notebook, a scheduled job or an internal report shows the same figures as the CrbonFree dashboard.

Last checked against the product on 5 September 2026. Carbon figures follow methodology v1.2.

At a glance

Package: crbonfree on PyPI
Version: 0.4.0, beta
Licence: MIT
Requires: Python 3.8 or newer
Clients: CrbonFree (sync) and AsyncCrbonFree (async)
Authenticates with: X-API-Key, keys start with ck_live_
Credentials: ~/.crbonfree/credentials, shared with the TypeScript SDK and MCP server
Operations: 12 reads across projects, usage, telemetry and billing
Built on: httpx and pydantic v2, generated from the OpenAPI spec
Data direction: Reads only

Twelve reads, each with a sync and an async form

The CrbonFree class exposes four sub-clients, projects, usage, telemetry and billing, that map one to one onto the public API. Usage returns totals, a per-model breakdown, daily rows and a CSV or JSON export. Telemetry returns CO2e with upper and lower bounds and every provider and model seen. Billing returns the retirement status of the current period, the receipts and the monthly audit packs. AsyncCrbonFree offers the same twelve methods as coroutines, so a FastAPI route or an asyncio job awaits them instead of blocking.

Sign in once from the terminal
Installing the package adds a crbonfree command. crbonfree login opens the browser, generates an API key and saves it to ~/.crbonfree/credentials, so the constructor needs no arguments. The TypeScript SDK and the MCP server read the same file, and one sign-in covers all three. In CI you set CRBONFREE_API_KEY or pass api_key to the constructor instead.
Typed models generated from the API spec
The client is generated from the backend’s OpenAPI specification on top of httpx and pydantic v2, and the package ships a py.typed marker. Every response is a frozen model with a success flag and a data field, attribute names are snake_case with the API’s camelCase kept as aliases, and each error status has its own exception class, from BadRequestError to TooManyRequestsError.
Pagination helpers for receipts and audit packs
Receipts and audit packs arrive in pages of page and limit. The crbonfree.pagination module provides auto_paginate, which yields every item as a generator, collect_all, which gathers them into one list, and parse_page, which normalises a single page with a has_next_page flag. The async client gets auto_paginate_async and collect_all_async. The other ten operations return everything in one call.

How the Python SDK moves your data

1
Your code calls a method
One typed call, for example usage.get_summary with a range of 7d, 30d, 90d or 365d, or await the same method on the async client.
2
The SDK signs it
The API key comes from the api_key argument, CRBONFREE_API_KEY or the credentials file that login wrote, and travels as an X-API-Key header.
3
The API answers from computed data
Usage, emissions with bounds, receipts and audit packs the backend has already produced. Nothing is metered on this path.
4
Your report shows the same figures
Whatever you build, a notebook cell, a monthly export or an alert, matches what the CrbonFree dashboard shows for the same range.

How to get started

1
Install
Python 3.8 or newer. The package is MIT licensed, depends on httpx and pydantic v2, and ships type hints.
```
pip install crbonfree
```
2
Sign in
Opens the browser, signs you in or creates an account, generates an API key and saves it to ~/.crbonfree/credentials with owner-only permissions. Run crbonfree whoami to see which account is saved and crbonfree logout to remove it.
```
crbonfree login
```
3
Read a summary
The constructor finds the saved key on its own. Every method returns a typed response model, and its data field carries the same numbers the dashboard shows.
```
from crbonfree import CrbonFree

crbon = CrbonFree()
usage = crbon.usage.get_summary(range="30d")
print(usage.data.totals.carbon_kg, "kg CO2e")
```
Prints the last 30 days of CO2e in kilograms.

The same numbers as your dashboard

The SDK reads the twelve public API operations, and what they return is what the backend has already computed for your organisation, so a figure you print from Python is the figure on screen. That makes it the right tool for a notebook, a scheduled report or a service that watches the retirement status of the current period. The sample account shows the shapes before you write against them.

Open the sample dashboard

What it does not do

The SDK is read only. It returns usage, emissions, receipts and audit packs that the backend has already computed, and it has no method for sending usage in, so it cannot meter anything on its own. It authenticates with an API key only; there is no session or bearer-token mode. The package is published as a beta, so method names are stable but the surface may still grow between minor versions. The deprecated cost field on usage totals and per-model breakdowns returns null and will be removed in the next major version. Receipts and audit packs are paid features, so a free plan receives a 402 with an upgrade link.

Who reaches for the Python SDK

Data scientist

Wants AI carbon and token figures in a notebook, next to the rest of the team’s data.

What they get: usage.get_summary and usage.get_daily return typed models that drop straight into a dataframe, with the same numbers the dashboard shows.

Finance analyst

Reconciles monthly AI usage against invoices and needs the retirement receipts.

What they get: collect_all over billing.list_receipts gathers every retirement with its serial numbers; billing.list_audit_packs does the same for the monthly packs.

Sustainability officer

Pulls a monthly Scope 3 figure into the group reporting system.

What they get: A scheduled job calls usage.export_daily with format csv and hands the rows to the reporting tool.

Which CrbonFree surface do I need?

Three of them put usage in: the dashboard through provider connections, the CLI for coding agents and the browser extension for chat sessions. The other four read the numbers back into your own code. The Python SDK is highlighted.

Surface	Meters usage	Reads numbers back	Runs	Needs	Language
Dashboard			In the browser	An account; the sample account opens without one	None
CLI		status	On your machine	An account; device code for headless machines	Node 20 or newer
Browser extension	estimates		In Chrome	Optional, per the store listing	None
TypeScript SDK			Node 18 or newer	An API key	TypeScript or JavaScript
Python SDKthis page			Python 3.8 or newer	An API key	Python
MCP server			Beside your MCP client	An API key from login	Any MCP client
REST API			Over HTTPS	An API key	Any

Questions

Questions about the Python SDK.

Short answers. The package page and the API reference have the long ones.

View on PyPI

With an API key only, sent as the X-API-Key header on every request. Running crbonfree login opens the browser, generates a key that starts with ck_live_ and writes it to ~/.crbonfree/credentials with owner-only permissions. The TypeScript SDK and the MCP server read the same file. In CI, set CRBONFREE_API_KEY or pass api_key to the constructor; an explicit key wins over the variable, and the variable wins over the file. If none of the three is present the constructor raises MissingCredentialsError.
Yes. AsyncCrbonFree has the same four sub-clients and the same twelve methods as CrbonFree, each returned as a coroutine you await, and it resolves credentials the same way. It runs on an httpx async client by default. For the paginated endpoints, auto_paginate_async and collect_all_async in crbonfree.pagination take a bound async method and walk the pages for you.
It returns what the backend has already computed for your organisation: token totals, CO2e in kilograms with upper and lower bounds, electricity in kilowatt hours, per-model and per-day breakdowns, the retirement status of the current billing period, signed receipts with their serial allocations and verification URLs, and monthly audit packs. It meters nothing and has no method for sending usage in. Metering happens elsewhere in the platform; this package only reads the results.
Only billing.list_receipts and billing.list_audit_packs paginate, with page and limit arguments and a pagination block in the response that carries page, limit, total and total_pages. The crbonfree.pagination module exports parse_page to normalise one page, auto_paginate to yield every item across pages, and collect_all to gather them into a list, each with an async twin. projects.list and telemetry.list_models return capped plain lists, and the other operations return in a single call.
The package is free and MIT licensed. Reading usage and carbon estimates works on the free plan. Receipts and audit packs are part of the paid plans, so those two billing endpoints answer a free organisation with a 402 and an upgrade link.

Goes well with

All products

DashboardEvery provider, project and coding agent in one report. The sample account opens without a login.CLIMeter your local AI coding agents automatically, synced to the dashboard every hour.Browser extensionEstimates token usage in your AI chat sessions across ChatGPT, Gemini and the Claude apps, including Claude Code. Guest mode keeps everything on your machine, and signing in keeps the history.

See your own number instead of ours.

However your team already runs AI, that is how you connect. Paste a read-only provider key, drop in an SDK, add the MCP server, install the CLI or switch on the browser extension, and the first measured tokens reach your dashboard within seconds.

Create your free account

Free plan · first tokens in seconds

Read your usage, emissions and receipts from Python.

What is the Python SDK?

Twelve reads, each with a sync and an async form

Sign in once from the terminal

Typed models generated from the API spec

Pagination helpers for receipts and audit packs

How the Python SDK moves your data

Your code calls a method

The SDK signs it

The API answers from computed data

Your report shows the same figures