List Vehicles

Retrieve all vehicles registered in your organization’s fleet with pagination support and flexible filtering options.

This endpoint returns both known vehicles (from our database with specific make/model) and unknown vehicles (custom vehicles defined by the user).

Request

Headers

x-api-key

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

x-organization-id

string

required

Your organization UUIDExample: ff4adcc7-8172-45fe-9cf1-e90a6de53aa9

x-user-id

string

required

Your user UUIDExample: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Query Parameters

page

integer

default:"1"

Page number for paginationExample: 1

size

integer

default:"50"

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

filter_by

string

Advanced filtering criteria (format: field:value)Example: "country:ES", "type:passenger", "ownership:owned"

sort_by

string

Sort criteria (format: field:asc or field:desc)Example: "name:asc", "created_at:desc", "license_plate:asc"

start_date

integer

Filter by creation date start (Unix timestamp)Example: 1704067200 (January 1, 2024)

end_date

integer

Filter by creation date end (Unix timestamp)Example: 1735689600 (January 1, 2025)

Response

page

integer

Current page number

size

integer

Number of items per page

total

integer

Total count of active vehicles

total_archived

integer

Total count of archived vehicles

items

array

Array of vehicle objects

Vehicle Object Fields:

id (string, UUID) - Unique vehicle identifier
name (string, optional) - Vehicle name or description
license_plate (string, optional) - Vehicle license plate number
type (string) - Vehicle usage type: "passenger" or "freight"
ownership (string) - Vehicle ownership: "owned" or "rented"
country (string) - ISO 3166-1 alpha-2 country code
is_known (boolean) - Whether vehicle is from known database or custom
known_vehicle_id (string, UUID, optional) - ID if vehicle from database
unknown_vehicle_id (string, UUID, optional) - ID if custom vehicle
vehicle_fuel_id (string, UUID, optional) - Associated fuel type ID
vehicle_fuel (string, optional) - Fuel type name (e.g., “Diesel”, “Electric”)
registration_year (integer, optional) - Year vehicle was first registered
market_segment (string, optional) - Vehicle market segment
size (string, optional) - Vehicle size classification
co2e (float) - Total CO2 equivalent emissions in kg
consumptions (integer, optional) - Number of fuel consumption records
status (string) - "active", "archived", or "error"
error_messages (array of strings, optional) - Error messages if status is error
created_at (datetime) - Creation timestamp
known_vehicle (object, optional) - Details if known vehicle
- id (string) - Known vehicle database ID
- brand (string) - Vehicle manufacturer
- model (string) - Vehicle model
- country (string) - Country code
- vehicle_motor_type (string) - Motor type
- gearbox_type (string) - Transmission type
- cylinder_capacity (integer) - Engine size in cc
- vehicle_power (integer) - Engine power in kW
unknown_vehicle (object, optional) - Details if custom vehicle
- id (string) - Custom vehicle ID
- type (string) - Vehicle type
- country (string) - Country code
custom_emission_factor_id (string, UUID, optional) - Custom emission factor if specified

Example

curl -X GET "https://api.dcycle.io/api/v1/vehicles?page=1&size=50&type=passenger" \
  -H "Authorization: Bearer ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "x-user-id: ${DCYCLE_USER_ID}"

Successful Response

{
  "page": 1,
  "size": 50,
  "total": 45,
  "total_archived": 8,
  "items": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Company Van #1",
      "license_plate": "1234-ABC",
      "type": "freight",
      "ownership": "owned",
      "country": "ES",
      "is_known": true,
      "known_vehicle_id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
      "unknown_vehicle_id": null,
      "vehicle_fuel_id": "c3d4e5f6-g7h8-9012-cdef-gh3456789012",
      "vehicle_fuel": "Diesel",
      "registration_year": 2020,
      "market_segment": "lower_medium",
      "size": "medium",
      "co2e": 4532.75,
      "consumptions": 24,
      "status": "active",
      "error_messages": null,
      "created_at": "2024-01-15T10:30:00Z",
      "known_vehicle": {
        "id": "b2c3d4e5-f6g7-8901-bcde-fg2345678901",
        "brand": "Ford",
        "model": "Transit Custom",
        "country": "ES",
        "vehicle_motor_type": "Diesel",
        "gearbox_type": "Manual",
        "cylinder_capacity": 1998,
        "vehicle_power": 96
      },
      "unknown_vehicle": null,
      "custom_emission_factor_id": null
    },
    {
      "id": "d4e5f6g7-h8i9-0123-defg-hi4567890123",
      "name": "CEO Car",
      "license_plate": "9876-XYZ",
      "type": "passenger",
      "ownership": "owned",
      "country": "ES",
      "is_known": true,
      "known_vehicle_id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
      "unknown_vehicle_id": null,
      "vehicle_fuel_id": "f6g7h8i9-j0k1-2345-fghi-jk6789012345",
      "vehicle_fuel": "Electric",
      "registration_year": 2023,
      "market_segment": "executive",
      "size": "large_car",
      "co2e": 856.20,
      "consumptions": 12,
      "status": "active",
      "error_messages": null,
      "created_at": "2023-08-22T14:15:00Z",
      "known_vehicle": {
        "id": "e5f6g7h8-i9j0-1234-efgh-ij5678901234",
        "brand": "Tesla",
        "model": "Model S",
        "country": "ES",
        "vehicle_motor_type": "Electric",
        "gearbox_type": "Automatic",
        "cylinder_capacity": 0,
        "vehicle_power": 493
      },
      "unknown_vehicle": null,
      "custom_emission_factor_id": null
    },
    {
      "id": "g7h8i9j0-k1l2-3456-ghij-kl7890123456",
      "name": "Custom Delivery Truck",
      "license_plate": "5555-DEF",
      "type": "freight",
      "ownership": "rented",
      "country": "ES",
      "is_known": false,
      "known_vehicle_id": null,
      "unknown_vehicle_id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
      "vehicle_fuel_id": "i9j0k1l2-m3n4-5678-ijkl-mn9012345678",
      "vehicle_fuel": "Diesel",
      "registration_year": 2019,
      "market_segment": null,
      "size": null,
      "co2e": 8920.50,
      "consumptions": 36,
      "status": "active",
      "error_messages": null,
      "created_at": "2024-03-10T09:00:00Z",
      "known_vehicle": null,
      "unknown_vehicle": {
        "id": "h8i9j0k1-l2m3-4567-hijk-lm8901234567",
        "type": "freight",
        "country": "ES"
      },
      "custom_emission_factor_id": null
    }
  ]
}

Common Errors

400 Bad Request

Cause: Invalid query parameters or date format

{
  "detail": "Invalid date format",
  "code": "VALIDATION_ERROR"
}

Solution: Verify that dates are Unix timestamps (integers) and pagination parameters are positive integers.

403 Forbidden

Cause: Organization ID doesn’t match your API key or user doesn’t belong to organization

{
  "detail": "Not authorized",
  "code": "FORBIDDEN"
}

Solution: Verify that x-organization-id matches your API key’s organization.

Use Cases

Fleet Dashboard

Display your complete fleet with emissions breakdown:

def get_fleet_dashboard():
    """Get vehicles for dashboard display"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"page": 1, "size": 100, "sort_by": "co2e:desc"}
    )

    vehicles = response.json()

    # Calculate totals
    total_emissions = sum(v['co2e'] for v in vehicles['items'])
    passenger_count = sum(1 for v in vehicles['items'] if v['type'] == 'passenger')
    freight_count = sum(1 for v in vehicles['items'] if v['type'] == 'freight')

    return {
        'vehicles': vehicles['items'],
        'total_active': vehicles['total'],
        'total_archived': vehicles['total_archived'],
        'total_emissions': total_emissions,
        'passenger_vehicles': passenger_count,
        'freight_vehicles': freight_count
    }

Filter by Vehicle Type

Get all passenger or freight vehicles:

def get_vehicles_by_type(vehicle_type):
    """Get vehicles filtered by type (passenger or freight)"""
    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={
            "filter_by": f"type:{vehicle_type}",
            "page": 1,
            "size": 100
        }
    )

    vehicles = response.json()

    print(f"{vehicle_type.capitalize()} vehicles: {vehicles['total']}")
    for vehicle in vehicles['items']:
        name = vehicle.get('name', vehicle.get('license_plate', 'Unnamed'))
        fuel = vehicle.get('vehicle_fuel', 'Unknown fuel')
        print(f"  - {name} ({fuel}): {vehicle['co2e']:.2f} kg CO2e")

    return vehicles

# Example: Get all freight vehicles
freight_vehicles = get_vehicles_by_type("freight")

Filter by Ownership

Get owned vs rented vehicles:

def compare_owned_vs_rented():
    """Compare emissions from owned vs rented vehicles"""
    # Get owned vehicles
    owned = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"filter_by": "ownership:owned", "size": 100}
    ).json()

    # Get rented vehicles
    rented = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={"filter_by": "ownership:rented", "size": 100}
    ).json()

    owned_emissions = sum(v['co2e'] for v in owned['items'])
    rented_emissions = sum(v['co2e'] for v in rented['items'])

    print(f"Owned vehicles: {len(owned['items'])} ({owned_emissions:.2f} kg CO2e)")
    print(f"Rented vehicles: {len(rented['items'])} ({rented_emissions:.2f} kg CO2e)")

    return {
        'owned': {'count': len(owned['items']), 'emissions': owned_emissions},
        'rented': {'count': len(rented['items']), 'emissions': rented_emissions}
    }

Date Range Query

Get vehicles added within a specific time period:

from datetime import datetime, timedelta

def get_recently_added_vehicles(days=30):
    """Get vehicles added in the last N days"""
    end_date = int(datetime.now().timestamp())
    start_date = int((datetime.now() - timedelta(days=days)).timestamp())

    response = requests.get(
        "https://api.dcycle.io/api/v1/vehicles",
        headers=headers,
        params={
            "start_date": start_date,
            "end_date": end_date,
            "sort_by": "created_at:desc"
        }
    )

    vehicles = response.json()

    print(f"Vehicles added in last {days} days: {len(vehicles['items'])}")
    return vehicles

# Get vehicles from last 30 days
recent = get_recently_added_vehicles(30)

Pagination

When you have many vehicles, use pagination to retrieve all results:

def get_all_vehicles():
    """Fetch all vehicles with pagination"""
    all_vehicles = []
    page = 1

    while True:
        response = requests.get(
            "https://api.dcycle.io/api/v1/vehicles",
            headers=headers,
            params={"page": page, "size": 100}
        )

        data = response.json()
        all_vehicles.extend(data['items'])

        # Check if we've retrieved all items
        if len(all_vehicles) >= data['total']:
            break

        page += 1

    return all_vehicles

# Get all vehicles at once
all_vehicles = get_all_vehicles()
print(f"Total vehicles retrieved: {len(all_vehicles)}")

Special Notes

Known vs Unknown Vehicles

Dcycle maintains a database of known vehicles with specific make, model, and technical specifications. You can:

Use known vehicles: Select from database with accurate emission factors based on manufacturer data
Create unknown vehicles: Define custom vehicles when your specific model isn’t in our database

When a vehicle has is_known: true, the known_vehicle object contains detailed specifications. When is_known: false, the unknown_vehicle object contains basic type information.

Vehicle Types

Vehicles are classified by usage:

passenger: Personal vehicles, company cars, executive vehicles
freight: Delivery vans, trucks, commercial vehicles

This classification affects emission calculations and reporting.

Ownership Status

Track vehicle ownership for better fleet management:

owned: Vehicles owned by your organization
rented: Leased or rented vehicles

This helps distinguish between CAPEX and OPEX emissions in reporting.

Market Segments

For passenger vehicles, market segments help classify vehicle size and emissions:

mini - City cars (e.g., Smart ForTwo)
supermini - Small cars (e.g., Ford Fiesta)
lower_medium - Compact cars (e.g., VW Golf)
upper_medium - Mid-size cars (e.g., BMW 3 Series)
executive - Large cars (e.g., BMW 5 Series)
luxury - Premium cars (e.g., Mercedes S-Class)
sports - Sports cars
dual_purpose_4x4 - SUVs and 4x4 vehicles
mpv - Multi-purpose vehicles (minivans)

CO2e Field

The co2e field represents the total carbon footprint of the vehicle calculated from all fuel consumption records. A value of 0.0 means either:

No consumption records have been registered yet
All consumptions have zero emissions
Calculations are pending

Vehicle Status

Vehicles can have three statuses:

active: Vehicle is currently in use
archived: Vehicle removed from fleet but data retained for historical reporting
error: Vehicle has validation or processing errors (check error_messages field)

Bulk Upload Vehicles

Upload multiple vehicles via CSV

List Facilities

View your facilities

Create Invoice

Add fuel consumption data

Authentication

Learn about API authentication

​List Vehicles

​Request

​Headers

​Query Parameters

​Response

​Vehicle Object Fields:

​Example

​Successful Response

​Common Errors

​400 Bad Request

​403 Forbidden

​Use Cases

​Fleet Dashboard

​Filter by Vehicle Type

​Filter by Ownership

​Date Range Query

​Pagination

​Special Notes

​Known vs Unknown Vehicles

​Vehicle Types

​Ownership Status

​Market Segments

​CO2e Field

​Vehicle Status

​Related Endpoints

Bulk Upload Vehicles

List Facilities

Create Invoice

Authentication

List Vehicles

Request

Headers

Query Parameters

Response

Vehicle Object Fields:

Example

Successful Response

Common Errors

400 Bad Request

403 Forbidden

Use Cases

Fleet Dashboard

Filter by Vehicle Type

Filter by Ownership

Date Range Query

Pagination

Special Notes

Known vs Unknown Vehicles

Vehicle Types

Ownership Status

Market Segments

CO2e Field

Vehicle Status

Related Endpoints