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));

import requests

url = "https://api.dcycle.io/v1/vehicles"

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>",
    "name": {},
    "type": "<string>",
    "ownership": "<string>",
    "license_plate": "<string>",
    "country": "<string>",
    "status": "<string>",
    "co2e": 123,
    "vehicle_fuel_id": {},
    "vehicle_fuel": {},
    "vehicle_fuel_units": {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    },
    "unknown_vehicle_id": {},
    "unknown_vehicle_type": {},
    "custom_emission_factor_id": {},
    "registration_year": {},
    "market_segment": {},
    "size": {},
    "error_messages": {},
    "file_id": {},
    "file_name": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

GET

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));

import requests

url = "https://api.dcycle.io/v1/vehicles"

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>",
    "name": {},
    "type": "<string>",
    "ownership": "<string>",
    "license_plate": "<string>",
    "country": "<string>",
    "status": "<string>",
    "co2e": 123,
    "vehicle_fuel_id": {},
    "vehicle_fuel": {},
    "vehicle_fuel_units": {
      "id": "<string>",
      "name": "<string>",
      "type": "<string>"
    },
    "unknown_vehicle_id": {},
    "unknown_vehicle_type": {},
    "custom_emission_factor_id": {},
    "registration_year": {},
    "market_segment": {},
    "size": {},
    "error_messages": {},
    "file_id": {},
    "file_name": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

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

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Query Parameters

boolean

default:"false"

Include vehicles from child organizationsExample: true

string

Search vehicles by name or license plate (partial match)Example: "Company Fleet"

array[string]

Filter by vehicle statusAvailable values: active, archived, errorExample: status[]=active&status[]=archived

array[string]

Filter by ownership typeAvailable values: owned, rentedExample: ownership[]=owned

array[uuid]

Filter by unknown vehicle type UUIDExample: unknown_vehicle_id[]=550e8400-e29b-41d4-a716-446655440000

array[uuid]

Filter by fuel type UUIDExample: vehicle_fuel_id[]=660e8400-e29b-41d4-a716-446655440000

array[uuid]

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

datetime

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

datetime

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

integer

Filter by reporting period start year (inclusive)Example: 2024

integer

Filter by reporting period end year (inclusive)Example: 2024

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

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 vehicle objects

Show Vehicle Object

string

Unique identifier (UUID)

string | null

Custom name or alias for the vehicle

string

Type of vehicle usage: passenger or freight

string

Ownership type: owned or rented

string

Vehicle registration/license plate number

string

ISO 3166-1 country code

string

Current status: active, archived, or error

number

Calculated CO2 equivalent emissions in kg CO2e

string | null

UUID of the fuel type (for known vehicles)

string | null

Human-readable label for the fuel type

array[object] | null

Available fuel units for this vehicle’s fuel type

Show Fuel Unit Object

string

Unit UUID

string

Unit name (e.g. litre_(l), kilogram_(kg))

string

Unit category

string | null

UUID of the unknown vehicle type

string | null

String representation of unknown vehicle type

string | null

UUID of a custom emission factor applied to this vehicle, if any

integer | null

Year of vehicle registration (YYYY format)

string | null

Vehicle market segment classification

string | null

Vehicle size category

array[string] | null

List of error codes when status is error

string | null

UUID of the source bulk-upload file, if any

string | null

Name of the source file, if any

datetime

Timestamp when the vehicle was created

datetime | null

Timestamp when the vehicle was last updated

integer

Total number of vehicles matching the filter

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?page=1&size=50&status[]=active" \
  -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 = {
    "page": 1,
    "size": 50,
    "status[]": ["active"],
    "sort": ["name"]
}

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

result = response.json()
for vehicle in result["items"]:
    print(f"{vehicle['name'] or vehicle['license_plate']}: {vehicle['co2e']} kg CO2e")

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 = {
  page: 1,
  size: 50,
  'status[]': ['active'],
  sort: ['name']
};

axios.get(
  'https://api.dcycle.io/v1/vehicles',
  { headers, params }
)
.then(response => {
  response.data.items.forEach(vehicle => {
    console.log(`${vehicle.name || vehicle.license_plate}: ${vehicle.co2e} kg CO2e`);
  });
})
.catch(error => console.error(error));

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",
      "vehicle_fuel": "Diesel",
      "unknown_vehicle_id": null,
      "unknown_vehicle_type": null,
      "custom_emission_factor_id": null,
      "registration_year": 2022,
      "market_segment": "upper_medium",
      "size": "medium",
      "error_messages": null,
      "file_id": null,
      "file_name": null,
      "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",
      "vehicle_fuel": "Petrol",
      "unknown_vehicle_id": null,
      "unknown_vehicle_type": null,
      "custom_emission_factor_id": null,
      "registration_year": 2020,
      "market_segment": null,
      "size": "large_car",
      "error_messages": null,
      "file_id": null,
      "file_name": null,
      "created_at": "2024-11-23T14:15:00Z",
      "updated_at": "2024-11-24T09:45:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 50,
  "filter_hash": "a1b2c3d4e5f67890"
}

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 len(data["items"]) < batch_size:
            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

​List Vehicles

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​404 Not Found

​422 Validation Error

​Use Cases

​Get All Active Vehicles

​Search and Filter by Criteria

​Export Fleet Data

​Pagination Guide

​Related Endpoints

Create Vehicle

Update Vehicle

Delete Vehicle

Vehicle Consumptions

List Vehicles

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

401 Unauthorized

404 Not Found

422 Validation Error

Use Cases

Get All Active Vehicles

Search and Filter by Criteria

Export Fleet Data

Pagination Guide

Related Endpoints