Partner API quickstart
The partner API is for AI gateways that run AI requests for their own customers. You send us the usage numbers of each request with your own ID for the customer, and the reply gives its energy, its water and its CO2e (carbon dioxide equivalent, which counts each greenhouse gas as the amount of CO2 with the same warming effect).
Base URL
https://api.crbonfree.com/api/ v1/ partner
From a key to your totals in three steps
- Get a key
Crbon Labs sends you a test key through a one-time secret link.
- Send a request
One call stores the usage of a request and returns its footprint.
- Read totals
Read back one event, or the totals of all your customers or of one.
At a glance
- Base URL
- https://api.crbonfree.com/
api/ v1/ partner - Send your key as
- Authorization: Bearer $CRBON_PARTNER_KEY
- Keys
- cp_test_ for test data, cp_live_ for live data
- Events in one call
- 1 to 1,000, at most 2 MB
- New events a UTC day
- 100,000 live, 10,000 test
- Test data
- Deleted 30 days after we receive it
- A delete you ask for
- Done within two working days
- Contact
- support@crbonlabs.com
On this page
Get a key
Crbon Labs creates your partner account and sends you each key through a one-time secret link. There is no sign-up, and there is nothing to sign in to.
Your first key is a test key. It starts with cp_test_ and works with test data only, which we delete 30 days after we receive it. When your integration works, tell us, and we send you a live key the same way. A live key starts with cp_live_ and works with live data only. A test key cannot read live data, and a live key cannot read test data.
Keep your key on your server. The examples on this page read it from the variable CRBON_PARTNER_KEY, so set it once in your terminal:
export CRBON_PARTNER_KEY="paste-your-test-key-here"Then check that the key works. The reply names your account, the environment and what the key may do:
curl -sS https://api.crbonfree.com/api/v1/partner/whoami \
-H "Authorization: Bearer $CRBON_PARTNER_KEY"{
"partner": "Example Gateway",
"environment": "test",
"scopes": [
"usage:write",
"usage:read"
]
}Send your first request
One call to POST /api/v1/partner/usage/events stores the usage of a request and returns its footprint in the same reply. This example writes the body to event.json, with an ID made from the time, so each run sends a new event. Then it sends the file:
REQUEST_ID="req_$(date -u +%Y%m%dT%H%M%SZ)"
cat > event.json <<EOF
{
"events": [
{
"id": "$REQUEST_ID",
"occurred_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"customer_id": "acct_8f2c",
"model": "anthropic/claude-sonnet-5",
"usage": {
"input_tokens": 400,
"cached_input_tokens": 800,
"cache_write_tokens": 0,
"output_tokens": 230,
"reasoning_tokens": 120
}
}
]
}
EOF
curl -sS https://api.crbonfree.com/api/v1/partner/usage/events \
-H "Authorization: Bearer $CRBON_PARTNER_KEY" \
-H "Content-Type: application/json" \
--data-binary @event.json{
"results": [
{
"id": "req_20261111T223314Z",
"status": "created",
"outcome": "estimated",
"match": "family",
"matched_model": "claude-sonnet*",
"methodology": "crbonfree-v1.2",
"factors_version": "v1.2",
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709"
}
]
}co2e_g is grams of CO2e, energy_wh is watt-hours and water_ml is millilitres of water. Each has a low and a high end of its range beside it. They are decimal strings with six places, so the values on your receipts add up exactly to the totals we report.
If a call fails, send it again
This is the only retry rule. If a call fails, times out or loses its connection, send the same events again with the same IDs. Each event we already hold comes back with status duplicate and the result we first gave, and it is not counted twice.
Try it: send the same event.json again.
curl -sS https://api.crbonfree.com/api/v1/partner/usage/events \
-H "Authorization: Bearer $CRBON_PARTNER_KEY" \
-H "Content-Type: application/json" \
--data-binary @event.json{
"results": [
{
"id": "req_20261111T223314Z",
"status": "duplicate",
"outcome": "estimated",
"match": "family",
"matched_model": "claude-sonnet*",
"methodology": "crbonfree-v1.2",
"factors_version": "v1.2",
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709"
}
]
}- Send again after a
503, a timeout or a dropped connection, and after a429once theRetry-Afterseconds have passed. - Do not send a
400,401,403or413again unchanged. Fix the call first. - The same ID with different content comes back as
conflict, and nothing changes. Give new content a new ID.
A 403 that is not JSON
403 whose body is the plain text error code: 1010 did not come from the API. It means the network in front of the API refused your HTTP client before the call reached us, as it does with the default User-Agent of Python's urllib. Send a User-Agent header such as YourGateway/1.0 that names your client.The fields of an event
The body is { "events": [ ... ] } with 1 to 1,000 events, at most 2 MB in all. Each event has these fields. A field that is not in this table, anywhere in the body, refuses the whole call with 400.
| Field | What it is |
|---|---|
| idRequired | Your own ID for the request, 1 to 128 characters. We use it to spot a resend. |
| occurred_ | When the request ran, as a date and time with a time zone, such as 2026-11-11T14:05:00Z. A new event must be at most 5 minutes ahead and at most 90 days old. |
| customer_ | Your own ID for the customer. See the note below the table. |
| modelRequired | The model that really served the request, as you name it, such as anthropic/claude-sonnet-5. |
| usageRequired for text | An object with the five token counts below. For text, at least one must be above 0. |
| usage. | Input tokens, not counting cached or cache-write tokens. |
| usage. | Input tokens read from the prompt cache. |
| usage. | Input tokens written to the prompt cache. |
| usage. | Output tokens, not counting reasoning tokens. |
| usage. | Reasoning tokens. We count them as output tokens. |
| modalityOptional | text (the default), image, video or speech. Only text gets figures. |
| providerOptional | The provider that served the request, such as anthropic. We store it. It does not change the figures. |
| regionOptional | The region the request ran in, such as us-east-1. We store it. It does not change the figures. |
| cost_ | What the request cost in US dollars, as a string such as "0.0123". We store it as you send it. |
Count each token once: the five counts do not overlap. A missing count is 0. An optional field sent as null is the same as leaving it out.
What to use as customer_id
. _ : @ -. Do not use a name, an email address or anything else that tells us who the customer is. We do not check this for you.What comes back for each event
The reply holds one result for each event, in the order you sent them. Its status says what happened:
| status | What it means |
|---|---|
| created | We stored the event. The result has its figures. |
| duplicate | We already hold this ID with the same content. This is the result we first gave, and nothing is counted twice. |
| conflict | We already hold this ID with different content, and nothing changed. Send new content under a new ID. |
| invalid | We did not store this event. The other events in the call were still processed. reason says why, as the next table shows. |
| reason | What it means |
|---|---|
| invalid_ | That field has a value we refuse, such as an occurred_at that is not a date. Fix the field. |
| no_ | A text event whose token counts are all 0. Send at least one count above 0. |
| occurred_ | A new event more than 5 minutes ahead or more than 90 days old. Check the clock that sets occurred_at. An older event cannot be stored. |
| id_ | An earlier event in the same call had this ID and different content, and was not stored. Give each event its own ID. |
| customer_ | We are deleting the records of this customer. Send the event again once the delete is done: it then starts a new, empty customer. |
A stored result has these fields:
| Field | What it is |
|---|---|
| outcome | estimated when the event has figures, not_covered when it has no figures. A not-covered event is stored and counted too. |
| reason | Only when outcome is not_covered: unknown_model or unsupported_modality. |
| match | exact, family, or null when not covered: how the model was matched, as the section on models explains. |
| matched_ | The model name or family pattern we used. |
| methodology | The methodology version the figures were made under, such as crbonfree-v1.2. |
| factors_ | The version of the factor set behind the figures, such as v1.2. |
| co2e_ | CO2e in grams, with the low and high end of its range. A decimal string, or null when not covered. |
| energy_ | Energy in watt-hours. A decimal string, or null when not covered. |
| water_ | Water in millilitres, with the low and high end of its range. A decimal string, or null when not covered. |
Read back one event or your totals
Reading needs the usage:read scope, which your first test key has. Read one stored event by its ID. The reply is the stored result without status:
curl -sS "https://api.crbonfree.com/api/v1/partner/usage/events/$REQUEST_ID" \
-H "Authorization: Bearer $CRBON_PARTNER_KEY"{
"id": "req_20261111T223314Z",
"outcome": "estimated",
"match": "family",
"matched_model": "claude-sonnet*",
"methodology": "crbonfree-v1.2",
"factors_version": "v1.2",
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709"
}Read totals for up to 366 days at a time, for all your customers. The range takes from and leaves out to. This example asks for the current calendar year:
YEAR=$(date -u +%Y)
curl -sS "https://api.crbonfree.com/api/v1/partner/usage/footprint?from=$YEAR-01-01T00:00:00Z&to=$((YEAR + 1))-01-01T00:00:00Z" \
-H "Authorization: Bearer $CRBON_PARTNER_KEY"{
"from": "2026-01-01T00:00:00Z",
"to": "2027-01-01T00:00:00Z",
"methodologies": [
"crbonfree-v1.2"
],
"totals": {
"requests": 1,
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709"
},
"coverage": {
"exact": 0,
"family": 1,
"not_covered": 0
},
"groups": []
}requests counts every event, covered or not, and coverage splits them by how the model was matched. The CO2e, energy and water totals add up the estimated events only, and are null when there are none. Here requests is 1: the event you sent twice counts once.
Add customer_id for one customer, and group_by=day for the totals of each UTC day:
YEAR=$(date -u +%Y)
curl -sS "https://api.crbonfree.com/api/v1/partner/usage/footprint?from=$YEAR-01-01T00:00:00Z&to=$((YEAR + 1))-01-01T00:00:00Z&customer_id=acct_8f2c&group_by=day" \
-H "Authorization: Bearer $CRBON_PARTNER_KEY"{
"from": "2026-01-01T00:00:00Z",
"to": "2027-01-01T00:00:00Z",
"methodologies": [
"crbonfree-v1.2"
],
"totals": {
"requests": 1,
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709"
},
"coverage": {
"exact": 0,
"family": 1,
"not_covered": 0
},
"groups": [
{
"date": "2026-11-11",
"requests": 1,
"co2e_g": "0.219063",
"co2e_g_low": "0.157102",
"co2e_g_high": "0.281023",
"energy_wh": "0.088611",
"water_ml": "1.539140",
"water_ml_low": "0.769570",
"water_ml_high": "2.308709",
"coverage": {
"exact": 0,
"family": 1,
"not_covered": 0
}
}
]
}These replies come from a first run with a new test key. Your totals grow as you send more events.
Which models we cover
We give figures for text requests to the models in our factor table. A factor is the energy, carbon and water we count for each token of a model. As of 11 November 2026, the table covers these families:
- OpenAI GPT models, and the o1, o3 and o4 reasoning models
- Anthropic Claude models
- Google Gemini and Gemma models
- Kimi, GLM and DeepSeek models
- OpenAI and Google embedding models
Not every version of a family is in the table, and some families are not in it at all, such as Llama, Mistral and Qwen. The reply tells you what we used for each event.
We first drop one prefix before a slash, so anthropic/claude-sonnet-5 is matched as claude-sonnet-5. Then match says how it was matched. exact means one model name in the table. family means a pattern for a family of models, such as claude-sonnet*, which matched_model shows.
A request we cannot match is stored and counted with outcome not_covered. Its figures are null, not zero. reason is unknown_model for a model we do not have, and unsupported_modality for image, video and speech:
curl -sS https://api.crbonfree.com/api/v1/partner/usage/events \
-H "Authorization: Bearer $CRBON_PARTNER_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<EOF
{
"events": [
{
"id": "req_$(date -u +%Y%m%dT%H%M%SZ)_llama",
"occurred_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
"customer_id": "acct_8f2c",
"model": "meta-llama/llama-4-maverick",
"usage": { "input_tokens": 400, "output_tokens": 230 }
}
]
}
EOF{
"results": [
{
"id": "req_20261111T223314Z_llama",
"status": "created",
"outcome": "not_covered",
"reason": "unknown_model",
"match": null,
"matched_model": null,
"methodology": "crbonfree-v1.2",
"factors_version": "v1.2",
"co2e_g": null,
"co2e_g_low": null,
"co2e_g_high": null,
"energy_wh": null,
"water_ml": null,
"water_ml_low": null,
"water_ml_high": null
}
]
}Each day we get the list of model names we could not match. When we add one, its new events get figures. Events we already hold keep the result they were given.
Limits
A live account can store 100,000 new events a UTC day. Only new events count: a duplicate or a resend does not. Test keys get a tenth of each live limit, with room for one full call a minute at least. Test and live are counted apart, and all the keys of one environment share its limits.
| Limit | Live | Test |
|---|---|---|
| New events a UTC day | 100,000 | 10,000 |
| Calls a minute | 600 | 60 |
| Events a minute | 6,000 | 1,000 |
| Calls a minute from one address | 1,200 | 1,200 |
| Events in one call | 1,000 | 1,000 |
Past a limit, the call gets 429 and nothing in it is stored. The Retry-After header gives the seconds to wait, and then you send the same events again. At the daily limit the reply looks like this, with resets_at at the next UTC midnight:
HTTP/1.1 429 Too Many Requests
Retry-After: 5110
{
"success": false,
"error": "DAILY_LIMIT_REACHED",
"message": "This key has reached its daily event limit",
"details": {
"limit": 100000,
"resets_at": "2026-11-12T00:00:00Z"
}
}A single call with more new events than the whole daily limit gets 400 instead, because waiting would not help.
To raise a limit, tell us the volume you expect each day. Write to support@crbonlabs.com, or reply to the person at Crbon Labs who sent your key.
How your data is kept apart
Each partner has its own account and its own keys. Nothing is shared between partners.
Every record we store carries your partner account, test or live, and your customer ID. Every read and every write is limited to your account and to the environment of your key. You cannot see the records of another partner, and another partner cannot see yours.
The records of all partners sit in one database on our hosting. They are kept apart record by record, not by separate databases or servers.
Ask for a new key or a delete
Write to support@crbonlabs.com, or reply to the person at Crbon Labs who sent your key. We do both by hand, and there is no endpoint for either.
For a new key, say test or live, and what it may do: send events (
usage:write), read them (usage:read), or both. We send it through a one-time secret link. We can also revoke a key, and it stops working at once.For a delete, give us test or live and the
customer_id. We delete the records of that customer within two working days.
From the moment a delete starts, the customer is left out of every read, and new events for that ID get customer_deleting. Once the delete is done, we no longer hold those event IDs, so an event you send again for that customer is stored as new, under a new, empty customer. Deleted records stay in our database backups until those backups expire.
We take usage numbers only
No prompts and no replies
The body may hold only the fields in the table above. Any other field refuses the whole call, so prompt or reply text cannot reach us by mistake. We do not write request bodies to our logs.
Reference and contact
Full API reference
Every field and error of the four partner endpoints is in the full API reference at api.crbonfree.com/docs.
Contact
Write to support@crbonlabs.com, or reply to the person at Crbon Labs who sent your key.

