For AI gatewaysv1Beta

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

  1. Get a key

    Crbon Labs sends you a test key through a one-time secret link.

  2. Send a request

    One call stores the usage of a request and returns its footprint.

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

Command
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:

Command
curl -sS https://api.crbonfree.com/api/v1/partner/whoami \
  -H "Authorization: Bearer $CRBON_PARTNER_KEY"
Reply
{
  "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:

Command
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
Reply
{
  "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.

Command
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
Reply
{
  "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 a 429 once the Retry-After seconds have passed.
  • 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. Give new content a new ID.

A 403 that is not JSON

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

The fields of an event
FieldWhat it is
idRequiredYour own ID for the request, 1 to 128 characters. We use it to spot a resend.
occurred_atRequiredWhen 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_idRequiredYour own ID for the customer. See the note below the table.
modelRequiredThe model that really served the request, as you name it, such as anthropic/claude-sonnet-5.
usageRequired for textAn object with the five token counts below. For text, at least one must be above 0.
usage.input_tokensOptionalInput tokens, not counting cached or cache-write tokens.
usage.cached_input_tokensOptionalInput tokens read from the prompt cache.
usage.cache_write_tokensOptionalInput tokens written to the prompt cache.
usage.output_tokensOptionalOutput tokens, not counting reasoning tokens.
usage.reasoning_tokensOptionalReasoning tokens. We count them as output tokens.
modalityOptionaltext (the default), image, video or speech. Only text gets figures.
providerOptionalThe provider that served the request, such as anthropic. We store it. It does not change the figures.
regionOptionalThe region the request ran in, such as us-east-1. We store it. It does not change the figures.
cost_usdOptionalWhat 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

Use an ID from your own system that you can look up on your side, such as your account ID for that customer. It must stay the same for the same customer, because totals are read by it. Use 1 to 128 letters, digits and . _ : @ -. 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:

Result statuses
statusWhat it means
createdWe stored the event. The result has its figures.
duplicateWe already hold this ID with the same content. This is the result we first gave, and nothing is counted twice.
conflictWe already hold this ID with different content, and nothing changed. Send new content under a new ID.
invalidWe did not store this event. The other events in the call were still processed. reason says why, as the next table shows.
Reasons an event is invalid
reasonWhat it means
invalid_field:<name>That field has a value we refuse, such as an occurred_at that is not a date. Fix the field.
no_usageA text event whose token counts are all 0. Send at least one count above 0.
occurred_at_out_of_rangeA 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_repeated_in_callAn earlier event in the same call had this ID and different content, and was not stored. Give each event its own ID.
customer_deletingWe 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:

The fields of a result
FieldWhat it is
outcomeestimated when the event has figures, not_covered when it has no figures. A not-covered event is stored and counted too.
reasonOnly when outcome is not_covered: unknown_model or unsupported_modality.
matchexact, family, or null when not covered: how the model was matched, as the section on models explains.
matched_modelThe model name or family pattern we used.
methodologyThe methodology version the figures were made under, such as crbonfree-v1.2.
factors_versionThe version of the factor set behind the figures, such as v1.2.
co2e_gco2e_g_lowco2e_g_highCO2e in grams, with the low and high end of its range. A decimal string, or null when not covered.
energy_whEnergy in watt-hours. A decimal string, or null when not covered.
water_mlwater_ml_lowwater_ml_highWater 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:

Command
curl -sS "https://api.crbonfree.com/api/v1/partner/usage/events/$REQUEST_ID" \
  -H "Authorization: Bearer $CRBON_PARTNER_KEY"
Reply
{
  "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:

Command
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"
Reply
{
  "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:

Command
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"
Reply
{
  "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:

Command
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
Reply
{
  "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.

Limits for live and test keys
LimitLiveTest
New events a UTC day100,00010,000
Calls a minute60060
Events a minute6,0001,000
Calls a minute from one address1,2001,200
Events in one call1,0001,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:

Reply
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

We take the model, the token counts, the time, your IDs and the optional provider, region, modality and cost. We do not take prompts or 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.