Vehicle Consumptions

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

fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}/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>",
    "status": "<string>",
    "data": {},
    "total_energy_kwh": 123,
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

GET

vehicles

{vehicle_id}

consumptions

Vehicle Consumptions

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

fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}/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>",
    "status": "<string>",
    "data": {},
    "total_energy_kwh": 123,
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

Vehicle Consumptions

Get detailed consumption records for a specific vehicle. This endpoint returns paginated consumption data including status information about data processing and tracking.

Consumption Tracking: This endpoint retrieves consumption records linked to a vehicle, showing fuel usage, mileage, and processing status over time.

Request

Path Parameters

uuid

required

The UUID of the vehicleExample: 550e8400-e29b-41d4-a716-446655440000

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]

Filter by consumption statusAvailable values: active, success, loading, errorExample: status[]=success&status[]=active

array[uuid]

Filter by unit of measurement UUIDExample: unit_id[]=550e8400-e29b-41d4-a716-446655440000

string

Filter by custom identifierExample: REF-2024-001

date

Filter consumptions starting on or after this date (inclusive)Format: YYYY-MM-DD

date

Filter consumptions ending on or before this date (inclusive)Format: YYYY-MM-DD

array[uuid]

Filter by source file UUID. Pass 00000000-0000-0000-0000-000000000000 to filter for records with no file.Example: file_id[]=3fa85f64-5717-4562-b3fc-2c963f66afa6

datetime

Filter records created on or after this timestamp (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

datetime

Filter records created on or before this timestamp (inclusive)Format: YYYY-MM-DDTHH:MM:SSZ

string

Filter by CO2e calculation statusAvailable values: calculated, not_calculated

string

Field to sort by. Prefix with - for descending order. 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: ?sort=-start_date

integer

default:"1"

Page number for paginationExample: 2

integer

default:"50"

Number of items per page (max 100)Example: 50

Response

array[object]

Array of consumption objects

Show Consumption Object

string

Unique identifier (UUID) for the consumption record

string

UUID of the associated vehicle

string

Current status: active, success, loading, or error

object

Consumption data (structure varies by consumption type)

float

Total energy consumption in kWh for the period. May be null if the energy calculation has not completed yet.

datetime

Timestamp when the consumption record was created

datetime | null

Timestamp when the record was last updated

integer

Total number of consumption records

integer

Current page number

integer

Number of items per page

string

16-character hex hash of the applied filters. Pass this to the bulk delete by filters endpoint to ensure consistency.

Example

curl -X GET "https://api.dcycle.io/v1/vehicles/550e8400-e29b-41d4-a716-446655440000/consumptions?status=success&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")
vehicle_id = "550e8400-e29b-41d4-a716-446655440000"

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

params = {
    "status": ["success"],
    "page": 1,
    "size": 50
}

response = requests.get(
    f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions",
    headers=headers,
    params=params
)

result = response.json()
for consumption in result["items"]:
    print(f"Consumption ID: {consumption['id']}, Status: {consumption['status']}")
    print(f"Created: {consumption['created_at']}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const vehicleId = "550e8400-e29b-41d4-a716-446655440000";

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

const params = {
  status: ['success'],
  page: 1,
  size: 50
};

axios.get(
  `https://api.dcycle.io/v1/vehicles/${vehicleId}/consumptions`,
  { headers, params }
)
.then(response => {
  response.data.items.forEach(consumption => {
    console.log(`Consumption ID: ${consumption.id}, Status: ${consumption.status}`);
    console.log(`Created: ${consumption.created_at}`);
  });
})
.catch(error => console.error(error));

Successful Response

{
  "items": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "success",
      "data": {
        "fuel_consumed": 45.5,
        "distance_km": 450,
        "fuel_efficiency": 10.1,
        "period": "2024-11-01 to 2024-11-30"
      },
      "total_energy_kwh": 1500.00,
      "created_at": "2024-11-01T08:00:00Z",
      "updated_at": "2024-11-01T08:00:00Z"
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "vehicle_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "success",
      "data": {
        "fuel_consumed": 52.3,
        "distance_km": 520,
        "fuel_efficiency": 9.9,
        "period": "2024-10-01 to 2024-10-31"
      },
      "created_at": "2024-10-01T08:00:00Z",
      "updated_at": "2024-10-01T08:00:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "size": 50,
  "filter_hash": "a1b2c3d4e5f67890"
}

Consumption Status Reference

Status	Description	Action
active	Consumption record is currently active and being tracked	Monitor for completion
success	Consumption data has been successfully processed	Data is ready to use
loading	Consumption data is being processed	Wait for completion
error	An error occurred during processing	Review logs or retry

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

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

Solution: Verify your API key is valid and active. Get a new one from Settings → API.

404 Not Found

Cause: Vehicle not found in organization

{
  "code": "VEHICLE_NOT_FOUND",
  "detail": "Vehicle with id=UUID('...') not found"
}

Solution: Verify that the vehicle ID is correct and belongs to your organization. Use the List Vehicles endpoint to get valid IDs.

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

Solution: Check that status values are valid. Use only active, success, loading, or error.

Use Cases

Get Successful Consumption Records

Retrieve only successfully processed consumption data:

def get_successful_consumptions(vehicle_id):
    """Get all successfully processed consumption records"""
    response = requests.get(
        f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions",
        headers=headers,
        params={"status": ["success"], "size": 100}
    )

    return response.json()["items"]

# Get consumptions
consumptions = get_successful_consumptions(
    "550e8400-e29b-41d4-a716-446655440000"
)

total_fuel = sum(c["data"]["fuel_consumed"] for c in consumptions)
total_distance = sum(c["data"]["distance_km"] for c in consumptions)

print(f"Total fuel: {total_fuel} liters")
print(f"Total distance: {total_distance} km")
print(f"Average efficiency: {total_distance / total_fuel:.2f} km/l")

Monitor Consumption Processing

Track consumption records that are being processed:

def check_consumption_status(vehicle_id):
    """Check status of all consumption records"""
    response = requests.get(
        f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions",
        headers=headers,
        params={"size": 100}
    )

    consumptions = response.json()["items"]
    status_summary = {
        "active": 0,
        "success": 0,
        "loading": 0,
        "error": 0
    }

    for consumption in consumptions:
        status = consumption["status"]
        status_summary[status] += 1

    return status_summary

# Check status
summary = check_consumption_status(
    "550e8400-e29b-41d4-a716-446655440000"
)

print("Consumption Status Summary:")
for status, count in summary.items():
    print(f"  {status}: {count}")

Export Consumption Data

Export consumption records for analysis:

def export_consumption_data(vehicle_id):
    """Export all consumption data to CSV"""
    response = requests.get(
        f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions",
        headers=headers,
        params={"status": ["success"], "size": 100}
    )

    consumptions = response.json()["items"]

    import csv
    with open(f"consumption_{vehicle_id}.csv", "w", newline="") as f:
        writer = csv.DictWriter(
            f,
            fieldnames=["date", "fuel_consumed", "distance_km", "efficiency"]
        )
        writer.writeheader()

        for c in consumptions:
            data = c["data"]
            writer.writerow({
                "date": c["created_at"],
                "fuel_consumed": data.get("fuel_consumed"),
                "distance_km": data.get("distance_km"),
                "efficiency": data.get("fuel_efficiency")
            })

    print(f"Exported {len(consumptions)} records")

# Export data
export_consumption_data("550e8400-e29b-41d4-a716-446655440000")

Analyze Fuel Efficiency Trends

Track fuel efficiency changes over time:

def analyze_efficiency_trends(vehicle_id):
    """Analyze fuel efficiency trends for a vehicle"""
    response = requests.get(
        f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions",
        headers=headers,
        params={"status": ["success"], "size": 100}
    )

    consumptions = response.json()["items"]
    consumptions.sort(key=lambda x: x["created_at"])

    efficiencies = [
        {
            "date": c["created_at"],
            "efficiency": c["data"].get("fuel_efficiency")
        }
        for c in consumptions
        if c["data"].get("fuel_efficiency")
    ]

    if efficiencies:
        avg_efficiency = sum(e["efficiency"] for e in efficiencies) / len(efficiencies)
        min_efficiency = min(e["efficiency"] for e in efficiencies)
        max_efficiency = max(e["efficiency"] for e in efficiencies)

        print(f"Average efficiency: {avg_efficiency:.2f} km/l")
        print(f"Min efficiency: {min_efficiency:.2f} km/l")
        print(f"Max efficiency: {max_efficiency:.2f} km/l")

    return efficiencies

# Analyze trends
trends = analyze_efficiency_trends("550e8400-e29b-41d4-a716-446655440000")

List Vehicles

Retrieve all vehicles

Create Vehicle

Add a new vehicle to your fleet

Vehicle Overview

Learn about the Vehicles API

Logistics API

Calculate emissions for shipments

List Vehicle Consumptions (Organization)

List consumptions across every vehicle in the organization, not just one

​Vehicle Consumptions

​Request

​Path Parameters

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Consumption Status Reference

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Get Successful Consumption Records

​Monitor Consumption Processing

​Export Consumption Data

​Analyze Fuel Efficiency Trends

​Related Endpoints

List Vehicles

Create Vehicle

Vehicle Overview

Logistics API

List Vehicle Consumptions (Organization)

Vehicle Consumptions

Request

Path Parameters

Headers

Query Parameters

Response

Example

Successful Response

Consumption Status Reference

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Get Successful Consumption Records

Monitor Consumption Processing

Export Consumption Data

Analyze Fuel Efficiency Trends

Related Endpoints