BetaBuild on your numbers

Give each of your customers their AI footprint.

The Partner API is for AI gateways and platforms that run AI requests for their own customers. Send the token counts of each request with your own ID for the customer, and the reply gives the carbon, energy and water of each request we cover. The API is in beta.

Check that your key works

curl -sS https://api.crbonfree.com/api/v1/partner/whoami -H "Authorization: Bearer $CRBON_PARTNER_KEY"
the quickstart’s example, with a test key

You send the usage of a request

POST/api/v1/partner/usage/events

customer_id
acct_8f2c
model
anthropic/claude-sonnet-5
usage
  • input400
  • cached input800
  • cache write0
  • output230
  • reasoning120

Token counts, a model name, a time and your own IDs. No prompt and no reply.

You read that customer’s footprint back

GET/api/v1/partner/usage/footprint

customer_id
acct_8f2c
from
2026-01-01T00:00:00Z
to
2027-01-01T00:00:00Z
group_by
day

acct_8f2c2026-11-111 requestmethodology crbonfree-v1.2

CO2e, grams
0.219063

low 0.157102high 0.281023

Energy, watt-hours
0.088611
Water, millilitres
1.539140

low 0.769570high 2.308709

3

values for each covered request: CO2e, energy and water

1,000

events in one call at most, in a body of up to 2 MB

100,000

new events a UTC day on a live account

366

days in one read of totals at most, for one customer or for all of them

What is the Partner API?

The CrbonFree Partner API is an HTTPS interface for AI gateways and platforms that run AI requests for their own customers. A partner sends the model and the token counts of each request with its own ID for the customer, and receives the CO2e, energy and water of each covered request, plus totals for each customer. It is in beta, and Crbon Labs issues each key.

Last checked against the product on 13 November 2026. Carbon figures follow methodology v1.2.

At a glance
Status
Beta, each key issued by Crbon Labs
Base URL
api.crbonfree.com/api/v1/partner
Send your key as
Authorization: Bearer <key>
Keys
cp_test_ for test data, cp_live_ for live data
Endpoints
Four, for checking a key, sending events, reading one event and reading totals
Events in one call
1 to 1,000, at most 2 MB
New events a UTC day
100,000 live, 10,000 test
A covered result holds
CO2e in grams, energy in watt-hours, water in millilitres
Test data
Deleted 30 days after we receive it
A delete you ask for
Done within two working days. Deleted records stay in our database backups until those backups expire.
Partners write to
support@crbonlabs.com

One call stores a request’s usage and returns its footprint

Send 1 to 1,000 events in one POST, at most 2 MB in all. An event is the usage of one AI request: the model that served it, its token counts, the time it ran and your own ID for the customer. A token is the unit a model counts text in. The reply holds one result for each event, in the order you sent them. The result of a covered request carries CO2e in grams, energy in watt-hours and water in millilitres, with the low and the high end of the range beside CO2e and water. CO2e means carbon dioxide equivalent, which counts each greenhouse gas as the amount of CO2 with the same warming effect. A duplicate carries the result we first gave, a conflict or an invalid event carries no values, and a request we do not cover carries null values.

Read the methodology
  • A footprint for each of your customers

    Every event carries your own ID for the customer, and totals are read by it. One GET returns the totals for all your customers or for one, over a range of up to 366 days, and group_by=day adds the totals of each UTC day. You can also read one stored event back by its ID.

  • A resend is counted once

    After a 503, a timeout or a dropped connection, send the same events again with the same IDs. After a 429, do the same once the Retry-After seconds have passed. Each event we already hold comes back with the status duplicate and the result we first gave, so it is counted once. Do not send a 400, 401, 403 or 413 again unchanged. Fix the call first.

  • Usage numbers only, with no prompts and no replies

    We take the model, the token counts, the time, your IDs and the optional provider, region, modality and cost. The body may hold only those fields. Any other field refuses the whole call with a 400, so the body has no field for prompt or reply text.

  • Test keys and live keys work on separate data

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

How the Partner API moves your data

  1. 1

    Your gateway runs a request

    A customer of yours sends an AI request through your gateway. You know which model served it and how many tokens it used. We do not take the prompt or the reply.

  2. 2

    You send its usage with your customer ID

    One POST carries the model, the token counts, the time and your own ID for the customer, for 1 to 1,000 requests at once.

  3. 3

    The reply gives the footprint of each request

    CO2e, energy and water come back for each covered request in the same reply. Each result names the methodology version it was made under, such as crbonfree-v1.2, and says whether the model was matched by its exact name or by its family.

  4. 4

    You read the totals of each customer

    A GET with customer_id returns the totals of that customer for the range you ask for, and for each UTC day when you add group_by=day.

How to get started

  1. 1

    Ask us for access

    There is no sign-up form. Ask us for access through the contact page of this site. When we set up a partner account for you, we send a test key through a one-time secret link. Keep the key on your server, and set it once in your terminal so the next commands can read it.

    export CRBON_PARTNER_KEY="paste-your-test-key-here"
    The commands below read the key from this variable.
  2. 2

    Check that the key works

    The reply names your partner account, the environment of the key, test or live, and what the key may do.

    curl -sS https://api.crbonfree.com/api/v1/partner/whoami \
      -H "Authorization: Bearer $CRBON_PARTNER_KEY"
    The key goes in the Authorization header as a bearer token.
  3. 3

    Send your first event

    One POST stores the usage of a request and returns the footprint of a covered request 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, and 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
    Count each token once. The five counts do not overlap.
    {
      "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"
        }
      ]
    }
    The reply of a first run with a new test key: grams of CO2e, watt-hours and millilitres of water.
  4. 4

    Read the totals of one customer

    Ask for a range of up to 366 days. Add customer_id for one customer, and group_by=day for the totals of each UTC day. This example asks for the current calendar year of the customer acct_8f2c.

    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"
    The reply counts every request and says how many were matched to a model.
  5. 5

    Ask for a live key

    When your integration works, tell us, and we send you a live key the same way. The quickstart lists the fields of an event, the statuses of a result and the limits.

The results come back to your own product

Each reply carries the CO2e, energy and water of the covered requests you just sent, and the totals call returns them for one customer or for all of them. The values are decimal strings with six places, so the values of single requests add up exactly to the totals we report. A customer is identified by an ID from your own system. 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.

Open the full API reference

What it does not do

The Partner API is in beta. There is no endpoint for a new key or for a delete, and Crbon Labs does both by hand when a partner asks. Only text requests get CO2e, energy and water values. Image, video and speech requests are stored and counted as not covered, and so is a text request to a model outside our factor table. Not every version of a family is in the table, and as of 11 November 2026 some families are not in it at all, such as Llama, Mistral and Qwen. The provider and the region you send are stored and do not change the result. A new event may be at most 90 days old, so older usage cannot be stored.

Who reaches for the Partner API

Platform engineer

Works at an AI gateway and wants a carbon, energy and water value for each request it serves, without sending prompts or replies to another company.

What they get: One POST of up to 1,000 events returns a result for each event, in the order sent, and each covered request comes back with its CO2e, energy and water. The body has no field for a prompt or a reply.

Product lead

Works at a gateway or a platform and wants to show each customer the footprint of their own AI use inside the product.

What they get: The totals call returns CO2e, energy and water for one customer ID, for the range asked for and for each UTC day, as decimal strings with six places.

Sustainability lead

Works at a company that buys AI through a gateway, and needs to know how a reported footprint was made and whether it covers every model the company used.

What they get: The gateway can show them each total with a low and a high end for CO2e and water, the methodology versions behind the total, and how many requests were matched to a model and how many were not covered.

Which CrbonFree surface do I need?

The dashboard, CLI and browser extension put usage in. The SDKs, MCP server and API read the numbers back. AI Memory finds past sessions. A gateway uses the Partner API to send usage in and read it back for its own customers. The Partner API is highlighted.

SurfaceMeters usageReads numbers backRunsNeedsLanguage
DashboardIn the browserAn account; the sample account opens without oneNone
CLI statusOn your machineAn account; device code for headless machinesNode 20 or newer
Browser extension estimatesIn ChromeOptional, per the store listingNone
AI MemoryLocal CLI and browserAn account; free local features are includedCLI commands or none
TypeScript SDKNode 18 or newerAn API keyTypeScript or JavaScript
Python SDKPython 3.8 or newerAn API keyPython
MCP serverRemote MCP endpointA CrbonFree accountAny MCP client
REST APIOver HTTPSAn API keyAny
Partner APIthis pageOver HTTPSA partner key from Crbon Labs (beta)Any

Questions

Questions about the Partner API.

Short answers. The quickstart and the API reference have the long ones.

Open the quickstart
  • There is no sign-up form. Ask us for access through the contact page of this site. When we set up a partner account for you, we send a test key through a one-time secret link, and a live key the same way once your integration works. A partner who holds a key writes to support@crbonlabs.com, or replies to the person at Crbon Labs who sent the key, for a new key or to have one revoked. We do both by hand, and there is no endpoint for keys.

  • A test key starts with cp_test_ and works with test data only. A live key starts with cp_live_ and works with live data only, and neither can read the data of the other. We delete test data 30 days after we receive it. The test environment gets a tenth of each live limit, such as 10,000 new events a UTC day against 100,000, and it gets 1,000 events a minute at least, which is one full call. Test and live are counted apart.

  • We take the model, the token counts, the time of the request, your IDs for the request and the customer, and the optional provider, region, modality and cost. We do not take prompts or replies. A field outside that list, anywhere in the body, refuses the whole call with a 400, so the body has no field for prompt or reply text. We do not write request bodies to our logs.

  • One call holds 1 to 1,000 events and at most 2 MB. A live account can store 100,000 new events a UTC day, with 600 calls and 6,000 events a minute. The test environment gets a tenth of each live limit, and it gets 1,000 events a minute at least, which is one full call. That is 10,000 new events a UTC day, 60 calls a minute and 1,000 events a minute. Test and live are counted apart, and all the keys of one environment share its limits. Only new events count toward the daily limit, so a resend does not. Past a limit the call gets a 429 with a Retry-After header in seconds, and nothing in it is stored. To raise a limit, a partner writes to support@crbonlabs.com with the volume expected each day.

  • We give CO2e, energy and water values 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 OpenAI GPT models, and the o1, o3 and o4 reasoning models. It also covers Anthropic Claude models, and Google Gemini and Gemma models. The other covered families are Kimi, GLM and DeepSeek models, and OpenAI and Google embedding models. Not every version of a family is in the table. A request we cannot match is stored and counted with the outcome not_covered. Its CO2e, energy and water are null and are not zero, and every total says how many requests were not covered.

  • It depends on the status. After a 503, a timeout or a dropped connection, send the same events again with the same IDs, and after a 429 do the same once the Retry-After seconds have passed. Each event we already hold comes back with the status duplicate and the result we first gave, and it is not counted twice. Do not send a 400, 401, 403 or 413 again unchanged. Fix the call first. The same ID with different content comes back as conflict and nothing changes, so give new content a new ID.

  • Yes. A partner writes to support@crbonlabs.com with test or live and the customer ID, and 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. Deleted records stay in our database backups until those backups expire.

  • Each partner has its own account and its own keys. Every record we store carries your partner account, test or live, and your customer ID, and every read and every write is limited to your account and to the environment of your key. The records of all partners sit in one database on our hosting, kept apart record by record and not by separate databases or servers.

  • The REST API is read only. It returns the usage and emissions of your own organisation, with an API key from the dashboard sent in the X-API-Key header. The Partner API takes usage in for the customers of a gateway or a platform, and it uses a partner key sent as a bearer token. A partner key works on the partner routes only.

Ask us for access.

When we set up a partner account for you, we send a test key first. Test data stays apart from live data, and we delete it 30 days after we receive it.

Ask us for accessOpen the quickstart

Beta, each key issued by Crbon Labs