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

# Consumption Totals (Organization)

> Get aggregated consumption totals (quantity, spend, CO2e by scope) across every vehicle in your organization

[← Vehicles API](/api-reference/vehicles/overview)

Returns aggregated totals across **every vehicle** in your organization: total quantity (broken down by unit, since fuels are reported in litres, kg, kWh…), total spend, total CO2e split by scope (scope 1 direct combustion, scope 3 well-to-tank), and record count.

<Note>
  **Same filters as the list.** This endpoint accepts the same query parameters as [List All Vehicle Consumptions](/api-reference/vehicles/consumptions-org-list). Call it with the SAME filters you used for the list so the totals match exactly what the table shows.
</Note>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication

  **Example:** `sk_live_1234567890abcdef`
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  Your organization UUID

  **Example:** `a8315ef3-dd50-43f8-b7ce-d839e68d51fa`
</ParamField>

### Query Parameters

<ParamField query="vehicle_id[]" type="array[string]">
  Narrow the totals to specific vehicle UUIDs
</ParamField>

<ParamField query="status[]" type="array[string]">
  Filter by consumption status

  **Available values:** `active`, `success`, `loading`, `error`
</ParamField>

<ParamField query="unit_id[]" type="array[string]">
  Filter by fuel unit UUIDs
</ParamField>

<ParamField query="vehicle_fuel_id[]" type="array[string]">
  Filter by the fuel UUIDs stamped on the consumption
</ParamField>

<ParamField query="file_id[]" type="array[string]">
  Filter by source file UUIDs
</ParamField>

<ParamField query="custom_id" type="string">
  Filter by custom identifier (substring match)
</ParamField>

<ParamField query="start_date" type="string">
  Filter consumptions with a start date on or after this date (YYYY-MM-DD)
</ParamField>

<ParamField query="end_date" type="string">
  Filter consumptions with an end date on or before this date (YYYY-MM-DD)
</ParamField>

<ParamField query="created_at_from" type="string">
  Filter consumptions created on or after this datetime (ISO 8601)
</ParamField>

<ParamField query="created_at_to" type="string">
  Filter consumptions created on or before this datetime (ISO 8601)
</ParamField>

<ParamField query="co2e_status" type="string">
  Filter by CO2e calculation status

  **Available values:** `calculated`, `not_calculated`
</ParamField>

<ParamField query="filter_by" type="string">
  Per-column filters in the `filter_by` grammar, e.g. `license_plate:ilABC$quantity:gt100`. Same grammar and same effect as on the list endpoint, ANDed on top of the named filters above.
</ParamField>

<ParamField query="filter_match" type="string">
  How to combine `filter_by` clauses across fields

  **Available values:** `any` (OR), `all` (AND, the default)
</ParamField>

<ParamField query="filter_or_fields" type="string">
  Comma-separated fields whose same-field clauses combine with OR instead of AND
</ParamField>

## Response

<ResponseField name="total_quantity" type="number">
  Sum of quantities across all matching consumptions, regardless of unit. Consumptions can be reported in different units across fuels (litres, kg, kWh…), so this raw sum has no single unit — use `quantity_by_unit` to show a meaningful headline number.
</ResponseField>

<ResponseField name="total_spend" type="number | null">
  Sum of monetary amounts **regardless of currency**. `null` when none of the matching consumptions have spend data, not `0`.

  <Warning>
    Currency is set per consumption (`currency_unit_id`), not per organization, so this raw sum can mix euros, dollars and pounds into a figure in no currency at all. Never display it with a currency symbol — use `spend_by_currency`.
  </Warning>
</ResponseField>

<ResponseField name="spend_by_currency" type="array[object]">
  Spend broken down by each consumption's own currency, ordered by the most-used currency first (by record count, then amount). Same convention as `quantity_by_unit`. Empty when no matching consumption has spend data.

  | Field           | Type           | Description                                                                                                    |
  | --------------- | -------------- | -------------------------------------------------------------------------------------------------------------- |
  | `currency_name` | string \| null | Currency unit (e.g. `euros_(eur)`, `us_dollar_(usd)`). `null` for rows carrying an amount but no currency unit |
  | `total_spend`   | number         | Sum for this currency                                                                                          |
  | `count`         | integer        | Number of consumptions with this currency                                                                      |
</ResponseField>

<ResponseField name="total_co2e" type="number">
  Total CO2e (kg CO2e), scope 1 + scope 3 combined
</ResponseField>

<ResponseField name="total_co2e_consumption" type="number">
  CO2e from direct combustion (Scope 1)
</ResponseField>

<ResponseField name="total_co2e_generation" type="number">
  CO2e from well-to-tank upstream emissions (Scope 3)
</ResponseField>

<ResponseField name="count" type="integer">
  Number of matching consumption records
</ResponseField>

<ResponseField name="quantity_by_unit" type="array[object]">
  Quantities broken down by unit, ordered by the most-used unit first (by record count, then quantity). Use `quantity_by_unit[0]` as the headline total and `quantity_by_unit.length - 1` as a "+N other units" indicator.

  | Field            | Type    | Description                                               |
  | ---------------- | ------- | --------------------------------------------------------- |
  | `unit_name`      | string  | Unit of measure (e.g. `litre_(l)`, `kilowatt_hour_(kwh)`) |
  | `total_quantity` | number  | Sum for this unit                                         |
  | `count`          | integer | Number of consumptions with this unit                     |
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v2/vehicle_consumptions/totals?start_date=2025-01-01&end_date=2025-12-31" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import os

  headers = {
      "x-api-key": os.getenv("DCYCLE_API_KEY"),
      "x-organization-id": os.getenv("DCYCLE_ORG_ID"),
  }

  response = requests.get(
      "https://api.dcycle.io/v2/vehicle_consumptions/totals",
      headers=headers,
      params={"start_date": "2025-01-01", "end_date": "2025-12-31"},
  )

  totals = response.json()
  print(f"CO2e: {totals['total_co2e']:.2f} kg CO2e ({totals['count']} consumptions)")
  print(f"  Scope 1:  {totals['total_co2e_consumption']:.2f}")
  print(f"  Scope 3:  {totals['total_co2e_generation']:.2f}")
  dominant = totals["quantity_by_unit"][0]
  print(f"Consumption: {dominant['total_quantity']} {dominant['unit_name']} (+{len(totals['quantity_by_unit']) - 1} more units)")
  for spend in totals["spend_by_currency"]:
      print(f"Spend: {spend['total_spend']:.2f} {spend['currency_name'] or '(no currency)'}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const axios = require('axios');

  const headers = {
    'x-api-key': process.env.DCYCLE_API_KEY,
    'x-organization-id': process.env.DCYCLE_ORG_ID,
  };

  axios.get('https://api.dcycle.io/v2/vehicle_consumptions/totals', {
    headers,
    params: { start_date: '2025-01-01', end_date: '2025-12-31' },
  })
  .then(response => {
    const t = response.data;
    console.log(`CO2e: ${t.total_co2e.toFixed(2)} kg CO2e (${t.count} consumptions)`);
  });
  ```
</CodeGroup>

### Successful Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "total_quantity": 1350.0,
  "total_spend": 425.5,
  "total_co2e": 375.0,
  "total_co2e_consumption": 300.0,
  "total_co2e_generation": 75.0,
  "count": 7,
  "quantity_by_unit": [
    {"unit_name": "litre_(l)", "total_quantity": 1300.0, "count": 4},
    {"unit_name": "kilowatt_hour_(kwh)", "total_quantity": 100.0, "count": 1},
    {"unit_name": "kilometre_(km)", "total_quantity": 250.0, "count": 2}
  ],
  "spend_by_currency": [
    {"currency_name": "euros_(eur)", "total_spend": 350.5, "count": 5},
    {"currency_name": "us_dollar_(usd)", "total_spend": 75.0, "count": 2}
  ]
}
```

## Common Errors

### 401 Unauthorized

**Cause:** Missing or invalid API key

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"detail": "Invalid API key", "code": "INVALID_API_KEY"}
```

### 422 Unprocessable Entity

**Cause:** Invalid query parameters

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "status[]"],
      "msg": "value is not a valid enumeration member; permitted: 'active', 'success', 'loading', 'error'",
      "type": "type_error.enum"
    }
  ]
}
```

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List All Consumptions (Organization)" icon="table" href="/api-reference/vehicles/consumptions-org-list">
    The records these totals aggregate
  </Card>

  <Card title="Unique Values (Organization)" icon="chart-bar" href="/api-reference/vehicles/consumptions-org-unique-values">
    Get filter dropdown values, e.g. all source files, across the organization
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Everything the Vehicles API covers
  </Card>
</CardGroup>