Skip to main content
GET
/
v1
/
vehicles
List Vehicles
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v1/vehicles', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "items": {
    "id": "<string>",
    "name": {},
    "type": "<string>",
    "ownership": "<string>",
    "license_plate": "<string>",
    "country": "<string>",
    "status": "<string>",
    "co2e": 123,
    "vehicle_fuel_id": {},
    "unknown_vehicle_type": {},
    "registration_year": {},
    "market_segment": {},
    "size": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "pages": 123
}

​
List Vehicles

Retrieve a paginated list of vehicles in your organization with support for filtering, searching, and sorting.
Performance Optimized: This endpoint uses correlated subqueries for efficient CO2e calculation, computing emissions only for the paginated result set rather than all vehicles.

​
Request

​
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

​
include_children
boolean
default:"false"
Include vehicles from child organizationsExample: true
​
search
string
Search vehicles by name or license plate (partial match)Example: "Company Fleet"
​
status
array[string]
Filter by vehicle statusAvailable values: active, archived, errorExample: status=active&status=archived
​
ownership
array[string]
Filter by ownership typeAvailable values: owned, rentedExample: ownership=owned&ownership=rented
​
unknown_vehicle_id
array[uuid]
Filter by unknown vehicle type UUIDExample: unknown_vehicle_id=550e8400-e29b-41d4-a716-446655440000
​
vehicle_fuel_id
array[uuid]
Filter by fuel type UUIDExample: vehicle_fuel_id=660e8400-e29b-41d4-a716-446655440000
​
sort
array[string]
Sort results (prefix with - for descending)Available values: name, license_plate, created_at, updated_at, -name, -license_plate, -created_at, -updated_atExample: sort=name&sort=-created_at
​
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 vehicle objects
​
total
integer
Total number of vehicles matching the filter
​
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?page=1&size=50&status=active" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}"

​
Successful Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Company Fleet Car #1",
      "type": "passenger",
      "ownership": "owned",
      "license_plate": "ABC-1234",
      "country": "ES",
      "status": "active",
      "co2e": 245.5,
      "vehicle_fuel_id": "660e8400-e29b-41d4-a716-446655440000",
      "unknown_vehicle_type": null,
      "registration_year": 2022,
      "market_segment": "upper_medium",
      "size": "medium",
      "created_at": "2024-11-24T10:30:00Z",
      "updated_at": "2024-11-24T10:30:00Z"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "name": "Company Fleet Van",
      "type": "freight",
      "ownership": "owned",
      "license_plate": "XYZ-5678",
      "country": "ES",
      "status": "active",
      "co2e": 385.2,
      "vehicle_fuel_id": "760e8400-e29b-41d4-a716-446655440000",
      "unknown_vehicle_type": null,
      "registration_year": 2020,
      "market_segment": null,
      "size": "large_car",
      "created_at": "2024-11-23T14:15:00Z",
      "updated_at": "2024-11-24T09:45:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "pages": 1
}

​
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: Organization not found 
{
  "code": "ORGANIZATION_NOT_FOUND",
  "detail": "Organization with id=UUID('...') not found"
}
Solution: Verify that the x-organization-id header contains a valid organization UUID.

​
422 Validation Error

Cause: Invalid query parameters 
{
  "detail": [
    {
      "loc": ["query", "size"],
      "msg": "ensure this value is less than or equal to 100",
      "type": "value_error.number.not_le"
    }
  ]
}
Solution: Check that page size is between 1 and 100, and that filter values are valid enums.

​
Use Cases

​
Get All Active Vehicles

Retrieve only active vehicles for current fleet monitoring: 
def get_active_vehicles():
    """Get all active vehicles in the organization"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        params={"status": ["active"], "size": 100}
    )
    return response.json()["items"]

active_vehicles = get_active_vehicles()
total_co2e = sum(v["co2e"] for v in active_vehicles)
print(f"Fleet CO2e: {total_co2e} kg")

​
Search and Filter by Criteria

Find specific vehicles and get their emissions: 
def search_vehicles(search_term=None, ownership=None, fuel_type=None):
    """Search vehicles with multiple filters"""
    params = {"size": 100}
    if search_term:
        params["search"] = search_term
    if ownership:
        params["ownership"] = [ownership]
    if fuel_type:
        params["vehicle_fuel_id"] = [fuel_type]

    response = requests.get(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        params=params
    )
    return response.json()["items"]

# Find all rented diesel vehicles
rented_diesel = search_vehicles(
    ownership="rented",
    fuel_type="760e8400-e29b-41d4-a716-446655440000"
)

​
Export Fleet Data

Export vehicle data for reporting: 
def export_fleet_to_csv():
    """Export all vehicles to CSV format"""
    response = requests.get(
        "https://api.dcycle.io/v1/vehicles",
        headers=headers,
        params={"size": 100}
    )

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

    import csv
    with open("fleet.csv", "w", newline="") as f:
        writer = csv.DictWriter(
            f,
            fieldnames=["name", "license_plate", "type", "ownership", "co2e", "status"]
        )
        writer.writeheader()
        for v in vehicles:
            writer.writerow({
                "name": v.get("name", ""),
                "license_plate": v["license_plate"],
                "type": v["type"],
                "ownership": v["ownership"],
                "co2e": v["co2e"],
                "status": v["status"]
            })

​
Pagination Guide

Navigate through large vehicle lists efficiently: 
def iterate_all_vehicles(batch_size=50):
    """Iterate through all vehicles in organization"""
    page = 1
    while True:
        response = requests.get(
            "https://api.dcycle.io/v1/vehicles",
            headers=headers,
            params={"page": page, "size": batch_size}
        )
        data = response.json()

        for vehicle in data["items"]:
            yield vehicle

        if page >= data["pages"]:
            break
        page += 1

# Process all vehicles
for vehicle in iterate_all_vehicles():
    print(f"Processing {vehicle['license_plate']}: {vehicle['co2e']} kg CO2e")

Create Vehicle

Add a new vehicle to your fleet

Update Vehicle

Modify vehicle details

Delete Vehicle

Remove a vehicle from your fleet

Vehicle Consumptions

Retrieve consumption data for a specific vehicle