Twelve read operations return the numbers the backend has already computed for your organisation. Anything that can send an HTTPS request with an X-API-Key header gets the same figures your dashboard shows.
Your first call
curl -H "X-API-Key: ck_live_..." https://api.crbonfree.com/api/v1/usage/summary12
public read operations, every one a GET
100
requests a minute per organisation, with rate-limit headers
2
auth schemes: session token and API key
4,500+
SDK and MCP downloads built on this API
Crbon Labs, 2026
The CrbonFree REST API is a read-only HTTPS interface with twelve GET operations that return the usage, emissions, credit retirement receipts and audit packs the backend has already computed for your organisation. Requests carry an API key in the X-API-Key header, responses arrive as JSON, and an OpenAPI 3.1 specification describes every operation so the same figures reach any language or tool.
Last checked against the product on 5 September 2026. Carbon figures follow methodology v1.2.
Usage returns totals, a per-model breakdown, daily rows and a CSV or JSON export for a range of 7, 30, 90 or 365 days, or any custom period up to a year. Telemetry returns CO2e with upper and lower bounds, the cached and uncached token split, and every provider and model seen. Billing returns the retirement status of the current period, each receipt with its serial numbers, and the monthly audit packs. Projects lists your workspaces. Every one of them is a GET.
The signed-in dashboard sends a session token as a bearer token. Everything else sends an API key in the X-API-Key header. Keys start with ck_live_ and carry 32 more characters; an organisation admin creates one in the dashboard, where the plaintext is shown exactly once. The server keeps only a hash, and a key can never mint another key.
Every organisation gets 100 requests a minute, counted per organisation when authenticated and per IP address otherwise. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a request over the limit gets a 429 with a Retry-After header telling you how many seconds to wait.
The API is described by an OpenAPI 3.1 document that a test locks to exactly these twelve operations, so nothing internal can leak into it. The document is served live from the API host, republished under the fixed tag openapi-latest whenever a route changes, and rendered as an interactive reference. The TypeScript SDK, the Python SDK and the MCP server are all generated from it.
An admin signed in to the dashboard creates a key under Settings. It starts with ck_live_, is shown once, and only its hash is stored.
Any HTTPS client sends a GET to api.crbonfree.com with the header. No SDK is needed, and the rate-limit headers come back on every response.
Usage, emissions with bounds, receipts and audit packs the backend has already produced for your organisation. Nothing is metered on this path.
A success envelope with the payload under data, matching what the dashboard shows for the same range and project.
Sign in to the dashboard, open Settings and then API keys, and create a key. This needs a signed-in admin session; a key cannot create keys. The plaintext appears once, so store it straight away. The server keeps only its hash and cannot show it again.
X-API-Key: ck_live_<32 characters>
Any HTTPS client works. The response is a JSON envelope with success set to true and the payload under data, and the same call with range=7d, 90d or 365d, or startDate and endDate, changes the period.
curl -H "X-API-Key: ck_live_..." "https://api.crbonfree.com/api/v1/usage/summary?range=30d"
The live OpenAPI document lists the twelve operations, their query parameters and every response schema. Point a client generator at it, or browse the same document as an interactive reference.
curl -s https://api.crbonfree.com/openapi.json
The dashboard reads these twelve operations, and so do the TypeScript SDK, the Python SDK and the MCP server. A figure you fetch with curl is the figure on screen for the same range and project, because every consumer is reading what the backend already computed. The sample account shows the shapes before you write against them.
Open the sample dashboardThe public API is read only. Its twelve operations return usage, emissions, receipts and audit packs that the backend has already computed, and there is no public endpoint for sending usage in, so nothing can be metered through it. Usage reaches CrbonFree through a provider connection, the CLI or the browser extension. Creating a key needs a signed-in admin session in the dashboard; a key cannot mint keys. Every organisation is limited to 100 requests a minute. Receipts and audit packs are paid features, so a free plan receives a 402 with an upgrade link, and retirement status returns a 404 until an organisation has its first billing period.
Wants AI carbon and token figures in an internal tool written in a language that has no CrbonFree SDK.
What they get: One GET to /usage/summary with an X-API-Key header returns the totals, and X-RateLimit-Remaining tells the scheduler how often it can poll.
Reconciles monthly AI spend against the credits retired and needs each receipt on file.
What they get: /billing/receipts pages through every retirement with its serial numbers, and /billing/retirement-status shows the amount charged for the current period.
Pulls a monthly Scope 3 line into the group reporting system and keeps the evidence behind it.
What they get: /usage/export returns the month as CSV for the reporting tool, and /billing/audit-packs/{id} returns the pack that backs the figure.
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 REST API 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 SDK | Python 3.8 or newer | An API key | Python | ||
| MCP server | Beside your MCP client | An API key from login | Any MCP client | ||
| REST APIthis page | Over HTTPS | An API key | Any |
Questions
Short answers. The package page and the API reference have the long ones.
Open the API referenceWith an API key in the X-API-Key header. Keys start with ck_live_ followed by 32 characters and are created by an organisation admin in the dashboard under Settings and API keys, where the plaintext is shown once. The signed-in dashboard itself uses a session token sent as a bearer token in the Authorization header, and every public operation accepts either scheme. A key cannot be used to create more keys.
Every organisation gets 100 requests a minute across the whole API, counted per organisation when authenticated and per IP address otherwise. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Going over returns a 429 with a Retry-After header in seconds. If the limiter itself is unavailable, requests are allowed through rather than refused.
No. All twelve public operations are reads, and there is no public endpoint for pushing usage. Usage reaches CrbonFree through a provider connection in the dashboard, the CLI for coding agents or the browser extension for chat sessions, and the API returns what the backend computed from it.
The live document is served at api.crbonfree.com/openapi.json, and the same document is rendered as an interactive reference at dashboard.crbonfree.com/docs. It is OpenAPI 3.1, republished under the fixed tag openapi-latest whenever a route changes, and a test locks it to exactly the twelve public operations so nothing internal appears in it.
There is no separate charge for the API. It returns whatever your plan holds: usage, emissions, projects and retirement status on the free plan, and receipts and audit packs with the paid plans. A free plan calling a receipts or audit-pack endpoint receives a 402 with an upgrade link.
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.
Free plan · first tokens in seconds