Consumption Totals (Organization)

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/vehicle_consumptions/totals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/vehicle_consumptions/totals"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_quantity": 123,
  "total_spend": {},
  "spend_by_currency": {},
  "total_co2e": 123,
  "total_co2e_consumption": 123,
  "total_co2e_generation": 123,
  "count": 123,
  "quantity_by_unit": {}
}

GET

vehicle_consumptions

totals

Consumption Totals (Organization)

const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/vehicle_consumptions/totals', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v2/vehicle_consumptions/totals"

headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>"
}

response = requests.get(url, headers=headers)

print(response.text)

{
  "total_quantity": 123,
  "total_spend": {},
  "spend_by_currency": {},
  "total_co2e": 123,
  "total_co2e_consumption": 123,
  "total_co2e_generation": 123,
  "count": 123,
  "quantity_by_unit": {}
}

← Vehicles API 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.

Same filters as the list. This endpoint accepts the same query parameters as List All Vehicle Consumptions. Call it with the SAME filters you used for the list so the totals match exactly what the table shows.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

array[string]

Narrow the totals to specific vehicle UUIDs

array[string]

Filter by consumption statusAvailable values: active, success, loading, error

array[string]

Filter by fuel unit UUIDs

array[string]

Filter by the fuel UUIDs stamped on the consumption

array[string]

Filter by source file UUIDs

string

Filter by custom identifier (substring match)

string

Filter consumptions with a start date on or after this date (YYYY-MM-DD)

string

Filter consumptions with an end date on or before this date (YYYY-MM-DD)

string

Filter consumptions created on or after this datetime (ISO 8601)

string

Filter consumptions created on or before this datetime (ISO 8601)

string

Filter by CO2e calculation statusAvailable values: calculated, not_calculated

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.

string

How to combine filter_by clauses across fieldsAvailable values: any (OR), all (AND, the default)

string

Comma-separated fields whose same-field clauses combine with OR instead of AND

Response

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.

number | null

Sum of monetary amounts regardless of currency. null when none of the matching consumptions have spend data, not 0.

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.

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

number

Total CO2e (kg CO2e), scope 1 + scope 3 combined

number

CO2e from direct combustion (Scope 1)

number

CO2e from well-to-tank upstream emissions (Scope 3)

integer

Number of matching consumption records

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

Example

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}"

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)'}")

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)`);
});

Successful Response

{
  "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

{"detail": "Invalid API key", "code": "INVALID_API_KEY"}

422 Unprocessable Entity

Cause: Invalid query parameters

{
  "detail": [
    {
      "loc": ["query", "status[]"],
      "msg": "value is not a valid enumeration member; permitted: 'active', 'success', 'loading', 'error'",
      "type": "type_error.enum"
    }
  ]
}

List All Consumptions (Organization)

The records these totals aggregate

Unique Values (Organization)

Get filter dropdown values, e.g. all source files, across the organization

Vehicles API

Everything the Vehicles API covers

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​422 Unprocessable Entity

​Related Endpoints

List All Consumptions (Organization)

Unique Values (Organization)

Vehicles API

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

422 Unprocessable Entity

Related Endpoints