List All Vehicle Consumptions (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', 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"

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

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

print(response.text)

{
  "items": {
    "id": "<string>",
    "vehicle_id": "<string>",
    "license_plate": {},
    "custom_id": {},
    "quantity": 123,
    "unit": {},
    "start_date": "<string>",
    "end_date": "<string>",
    "status": "<string>",
    "file_id": {},
    "file_name": {},
    "co2e": {},
    "total_energy_kwh": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

GET

vehicle_consumptions

List All Vehicle Consumptions (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', 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"

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

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

print(response.text)

{
  "items": {
    "id": "<string>",
    "vehicle_id": "<string>",
    "license_plate": {},
    "custom_id": {},
    "quantity": 123,
    "unit": {},
    "start_date": "<string>",
    "end_date": "<string>",
    "status": "<string>",
    "file_id": {},
    "file_name": {},
    "co2e": {},
    "total_energy_kwh": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>",
  "select_all_matching_enabled": true
}

← Vehicles API Get a paginated list of consumption records across every vehicle in your organization, instead of one vehicle at a time. This powers an “all consumptions” table view — useful when a single uploaded file was split into consumptions across many vehicles and you want to review, filter, or bulk-delete them as a group.

Organization-scoped: This endpoint only returns consumptions for vehicles owned directly by the organization in x-organization-id. It does not include consumptions from child organizations in a holding.

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 results 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 — the primary way to isolate all consumptions created from one bulk upload, across all the vehicles it was split into

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

Sort field, optionally prefixed with - for descending. Unrecognized values fall back to the default order (-created_at).Available values: custom_id, quantity, start_date, end_date, status, created_at, updated_at, base_total_spendExample: -created_at

integer

default:"1"

Page number for pagination

integer

default:"50"

Number of items per page (max 100)

Response

array[object]

Array of consumption objects

Show Consumption Object

string

Unique identifier (UUID) for the consumption record

string

UUID of the vehicle this consumption belongs to

string | null

License plate of the owning vehicle — the only way to identify which vehicle a row belongs to in this cross-vehicle list

string | null

Custom identifier for the record, if set

float

Fuel/energy quantity consumed

object

The unit of measurement (id, name, type)

date

Start date of the consumption period

date

End date of the consumption period

string

Current status: active, success, loading, or error

string | null

UUID of the file this consumption was bulk-uploaded from, if any

string | null

Name of the source file, if any

float | null

Total calculated CO2e emissions

float | null

Total energy consumption in kWh for the period

datetime

Timestamp when the consumption record was created

datetime | null

Timestamp when the record was last updated

integer

Total number of matching consumption records

integer

Current page number

integer

Number of items per page

string

Hash of the currently applied filters. Pass this back unchanged when calling Bulk Delete by Filters with the same filters, as a safety check against stale filter state.

boolean

Capability flag: true means this backend exposes the bulk-*-by-filters endpoint for this list, so the client may offer “select all matching”. false on a backend that only supports bulk delete by explicit ids.

Example

curl -X GET "https://api.dcycle.io/v2/vehicle_consumptions?file_id[]=880e8400-e29b-41d4-a716-446655440000&page=1&size=50" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id
}

params = {
    "file_id[]": ["880e8400-e29b-41d4-a716-446655440000"],
    "page": 1,
    "size": 50
}

response = requests.get(
    "https://api.dcycle.io/v2/vehicle_consumptions",
    headers=headers,
    params=params
)

result = response.json()
for consumption in result["items"]:
    print(f"{consumption['license_plate']}: {consumption['quantity']} ({consumption['status']})")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId
};

const params = {
  'file_id[]': ['880e8400-e29b-41d4-a716-446655440000'],
  page: 1,
  size: 50
};

axios.get(
  'https://api.dcycle.io/v2/vehicle_consumptions',
  { headers, params }
)
.then(response => {
  response.data.items.forEach(consumption => {
    console.log(`${consumption.license_plate}: ${consumption.quantity} (${consumption.status})`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
      "license_plate": "1234-ABC",
      "custom_id": null,
      "quantity": 100.5,
      "unit": { "id": "54a709bf-79fe-4acb-ab85-5e1d7cd26eb4", "name": "litre_(l)", "type": "liquid" },
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "status": "success",
      "file_id": "880e8400-e29b-41d4-a716-446655440000",
      "file_name": "consumos_matriz_2024_01.csv",
      "co2e": 234.7,
      "total_energy_kwh": 987.2,
      "created_at": "2024-02-01T08:00:00Z",
      "updated_at": "2024-02-01T08:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 50,
  "filter_hash": "b4c2d3e5f6a7b8c9"
}

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

422 Validation Error

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

Consumption Totals (Organization)

Aggregated quantity, spend and CO2e for these SAME filters

Unique Values (Organization)

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

Bulk Delete (Organization)

Delete consumptions by ID, across any vehicle in the organization

Bulk Delete by Filters (Organization)

Delete every consumption matching the current filters, e.g. an entire uploaded file

Vehicle Consumptions

List consumptions for a single vehicle

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​422 Validation Error

​Related Endpoints

Consumption Totals (Organization)

Unique Values (Organization)

Bulk Delete (Organization)

Bulk Delete by Filters (Organization)

Vehicle Consumptions

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

422 Validation Error

Related Endpoints