Skip to main content
GET
/
v1
/
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));
{
  "items": {
    "id": "<string>",
    "vehicle_id": "<string>",
    "status": "<string>",
    "data": {},
    "total_energy_kwh": 123,
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "pages": 123
}

​
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

​
vehicle_id
uuid
required
The UUID of the vehicleExample: 550e8400-e29b-41d4-a716-446655440000

​
Headers

​
x-api-key
string
required
Your API key for authenticationExample: sk_live_1234567890abcdef
​
x-organization-id
string
required
Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

​
Query Parameters

​
status
array[string]
Filter by consumption statusAvailable values: active, success, loading, errorExample: status=success&status=active
​
page
integer
default:"1"
Page number for paginationExample: 2
​
size
integer
default:"50"
Number of items per page (max 100)Example: 50

​
Response

​
items
array[object]
Array of consumption objects
​
total
integer
Total number of consumption records
​
page
integer
Current page number
​
size
integer
Number of items per page
​
pages
integer
Total number of pages

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

​
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,
  "pages": 1
}

​
Consumption Status Reference

StatusDescriptionAction
activeConsumption record is currently active and being trackedMonitor for completion
successConsumption data has been successfully processedData is ready to use
loadingConsumption data is being processedWait for completion
errorAn error occurred during processingReview 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")
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