Stats

Worked stats samples

The endpoint list below documents every operation’s parameters; this overlay walks the carbon analytics read the way an ESG-conscious integration actually uses it: read the tenant’s carbon figure → export it for a ledger or a ToS-respecting disclosure. Success envelopes are { data, meta }, error envelopes { error, meta } — see How to read a worked sample. The carbon metric is aggregated, not real-time — expect the poll cadence of a nightly rollup when you poll from a dashboard. Every response carries meta.request_id. Quote the request id when you report a number that drifts from what the CSV shows or a window that rounds differently than the dashboard read.

1. Read the carbon figure

GET /api/v1/stats/analytics/carbon returns your tenant’s platform-side carbon metric for the analytics window. The response is a single aggregate calculable off the same time-series the rest of the analytics stack reads — a dashboard, a BI export, and this read all agree.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/stats/analytics/carbon" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/stats/analytics/carbon",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.json());

200

{
  "data": {
    "factors_version": "2026-06-orbit-v1",
    "methodology": "Estimated footprint from platform-wide message-volume and connected-minute telemetry; indicative, order-of-magnitude figures for ESG reporting, not audited measurements.",
    "per_channel": [
      {
        "channel": "sms",
        "unit": "message",
        "quantity": 12840,
        "gco2e_per_unit": 0.014,
        "total_gco2e": 179.76
      },
      {
        "channel": "whatsapp",
        "unit": "message",
        "quantity": 4120,
        "gco2e_per_unit": 0.02,
        "total_gco2e": 82.4
      },
      {
        "channel": "voice",
        "unit": "minute",
        "quantity": 214.5,
        "gco2e_per_unit": 0.3,
        "total_gco2e": 64.35
      }
    ],
    "total_gco2e": 326.51,
    "total_kg_co2e": 0.3265,
    "period": {
      "start": "2026-08-01T00:00:00.000Z",
      "end": "2026-08-31T23:59:59.999Z"
    }
  },
  "meta": {
    "request_id": "req_stat_carbon",
    "timestamp": "2026-09-01T00:00:00.000Z"
  }
}

per_channel lists one line per channel — a message channel counts outbound messages (unit: "message"); voice counts connected minutes (unit: "minute", read from call logs, never the message table).
total_kg_co2e is the same total expressed in kilograms of CO₂-equivalent for ESG reporting; factors_version names the emission-factor set so downstream reports document provenance.

2. Export the carbon figure

GET /api/v1/stats/analytics/carbon/export returns the same report in a ledger-friendly export format (?format=csv). Use it for the annual disclosure bundle or a regulator-side CSV handoff.

curl -X GET \
  "https://api.orbit.devotel.io/api/v1/stats/analytics/carbon/export?format=csv" \
  -H "X-API-Key: dv_test_sk_YOUR_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/stats/analytics/carbon/export?format=csv",
  {
    headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
  },
);
console.log(await res.text());

200

# factors_version,2026-06-orbit-v1
# window,2026-08-01T00:00:00.000Z,2026-08-31T23:59:59.999Z
channel,unit,quantity,gco2e_per_unit,total_gco2e
sms,message,12840,0.014,179.76
whatsapp,message,4120,0.02,82.4
voice,minute,214.5,0.3,64.35
TOTAL,,,,326.51

The #-prefixed header lines carry the factor-set version and the window so the exported numbers are self-describing; the TOTAL row closes the report.

2b. The per-period rollup shape

The same window also reduces to the compact per-period rollup { data: { period, totals: { co2e_grams }, by_channel: [...] }, meta }:

200

{
  "data": {
    "period": "2026-08",
    "totals": {
      "co2e_grams": 326.5
    },
    "by_channel": [
      { "channel": "sms", "co2e_grams": 179.8 },
      { "channel": "whatsapp", "co2e_grams": 82.4 },
      { "channel": "voice", "co2e_grams": 64.4 }
    ]
  },
  "meta": {
    "request_id": "req_stat_rollup",
    "timestamp": "2026-09-01T00:00:00.000Z"
  }
}

totals.co2e_grams sums the per-channel lines (rounded to one decimal); a channel with no traffic in the period is absent rather than zero, so by_channel can legitimately be an empty array for a quiet tenant.

3. Errors

Errors follow the { error, meta } envelope. The failure every exporter hits: 422 — malformed export format. An unsupported format query value never reaches the renderer:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unsupported format; allowed values: csv.",
    "status": 422
  },
  "meta": {
    "request_id": "req_stat_err",
    "timestamp": "2026-09-01T00:00:01.000Z"
  }
}

API Reference

All Endpoints

Worked stats samples

1. Read the carbon figure

2. Export the carbon figure

2b. The per-period rollup shape

3. Errors

​Worked stats samples

​1. Read the carbon figure

​2. Export the carbon figure

​2b. The per-period rollup shape

​3. Errors

Worked stats samples

1. Read the carbon figure

2. Export the carbon figure

2b. The per-period rollup shape

3. Errors