Node.js Carbon and Energy Tracking Docs

Getting Started

Codensity shows which features of your software use the most energy and produce the most carbon. Wrap a feature in one line of code, and Codensity estimates the energy and CO₂e behind it from then on.

Everything you track is organised in three levels:

Projects: One per app or service, such as my-api or data-pipeline.
Environments: The stages of a project, such as development and production. Each has its own SDK keys.
Features: A piece of your code you want to measure, named by a key such as checkout-flow.

Prerequisites

Node.js 18+ (or any runtime with fetch support)
A Codensity account (sign up at getcodensity.com)
A project created in the Codensity dashboard
An SDK key issued for your target environment

Installation @codensity/node

terminal

npm install @codensity/node
# or
pnpm add @codensity/node
# or
yarn add @codensity/node

.env

CODENSITY_KEY=cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx@api.getcodensity.com

Never commit keys to source control.

Quick Start

codensity.ts

import { CodensityClient } from "@codensity/node";
import type { RequestHandler } from "express";

export const codensity = new CodensityClient({
  key: process.env.CODENSITY_KEY,  // cds_live_...@host or cds_test_...@host
  environment: "production",
});

export const trackFeature = (featureKey: string) =>
  codensity.trackFlow(featureKey) as unknown as RequestHandler;

server.ts

import express from "express";
import { trackFeature } from "./codensity";

const app = express();

// Add the middleware to a route to track it under a feature key.
app.post("/checkout", trackFeature("checkout-flow"), checkoutHandler);

app.listen(3000);

API Reference

https://api.getcodensity.com/api/v1/…

Authentication

x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Use the part of your key before the @. The part after it is the host to call. Each key is tied to one environment, and the key is shown once, when you create it. Revoke and rotate keys from the Environments tab of your project.

Batch Ingest

POST/api/v1/ingest/batch

Required

Request body

Field	Type	Description
`sdkVersion` (required)	string	Version of the SDK or client sending the events (e.g. "1.0.0").
`appVersion`	string	Version of your application.
`events` (required)	array	Between 1 and 500 event objects.

Event fields

Field	Type	Description
`eventId` (required)	string	A unique ID you generate for each event, such as a UUID. Send the same ID again when you retry, so the event is only counted once.
`featureKey` (required)	string	The feature this event belongs to (e.g. "checkout-flow"). Lowercase letters, numbers, dashes and underscores, up to 100 characters. A new key creates the feature in your project automatically.
`executionTimeMs` (required)	number	How long the feature ran, in milliseconds. Up to 3,600,000 (one hour).
`timestamp` (required)	string	When the event happened, as an ISO 8601 time in UTC ending in "Z" (e.g. "2026-04-15T10:00:00.000Z").
`memoryBytes`	integer	Memory the feature used, in bytes, up to 256 GiB. Recommended: it improves the energy and carbon estimate.
`cpuPercent`	number	CPU utilisation while the feature ran, from 0 to 100.
`callCount`	integer	How many calls this event stands for, from 1 to 1,000,000. Defaults to 1.
`metadata`	object	Extra context as key/value pairs. Values can be strings, numbers or booleans.

Response

{
  "success": true,
  "data": {
    "accepted": 2,
    "rejected": [
      {
        "index": 2,
        "featureKey": "Old Search",
        "reason": "Invalid feature key format"
      }
    ],
    "autoCreated": ["search-index"]
  },
  "requestId": "1042",
  "timestamp": "2026-04-15T10:00:00.412Z"
}

Status codes

Status	Meaning	Retry
202Accepted	The batch was received. Check `rejected` for events that were skipped.	No
400Bad Request	The payload failed validation. Nothing in the batch was stored.	No
401Unauthorized	The `x-api-key` header is missing, invalid or revoked.	No
403Forbidden	The workspace can't accept events, for example after reaching its monthly event limit.	No
429Too Many Requests	Too many requests in a short time. The SDK backs off for you.	Yes, with backoff
5xxServer error	A temporary problem on our side.	Yes, with backoff

Health Check

GET/api/v1/ingest/health

{
  "success": true,
  "data": {
    "status": "ok",
    "projectId": "1b7d8c4e-2a10-4c3a-9f2e-5f0c2a9e6d1b",
    "environmentId": "9e2d6c41-7a3b-4f80-b5d2-0c8e1f4a7b39"
  },
  "requestId": "1043",
  "timestamp": "2026-04-15T10:00:00.118Z"
}

SDK Examples

terminal

curl https://api.getcodensity.com/api/v1/ingest/health \
  -H "x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# eventId: any unique string per event; reuse it when you retry
curl -X POST https://api.getcodensity.com/api/v1/ingest/batch \
  -H "Content-Type: application/json" \
  -H "x-api-key: cds_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "sdkVersion": "1.0.0",
    "events": [
      {
        "eventId": "5f0c2a9e-6d1b-4c3a-9f2e-1b7d8c4e2a10",
        "featureKey": "checkout-flow",
        "executionTimeMs": 145,
        "memoryBytes": 268435456,
        "timestamp": "2026-04-15T10:00:00.000Z"
      },
      {
        "eventId": "0c8e1f4a-7b39-4f80-b5d2-9e2d6c417a3b",
        "featureKey": "search-index",
        "executionTimeMs": 32,
        "timestamp": "2026-04-15T10:00:01.000Z",
        "metadata": { "results": 120 }
      }
    ]
  }'