> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/using-orbit-samples). 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.orbit.devotel.io/api/v1/stats/analytics/carbon" \
    -H "X-API-Key: dv_test_sk_YOUR_KEY"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

```json 200 theme={null}
{
  "data": {
    "period": "2026-08",
    "co2_kg": 84.12,
    "co2_usd_multiple": null,
    "method": "platform-wide-message-volume-model"
  },
  "meta": {
    "request_id": "req_stat_carbon",
    "timestamp": "2026-09-01T00:00:00.000Z"
  }
}
```

* `co2_kg` is the computed carbon figure in kilograms of CO₂-equivalent.
* `method` names the derivation model 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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```typescript Node.js theme={null}
  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());
  ```
</CodeGroup>

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

```json 422 theme={null}
{
  "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"
  }
}
```