> ## Documentation Index
> Fetch the complete documentation index at: https://code.dcycle.io/llms.txt
> Use this file to discover all available pages before exploring further.
# List Vehicles
> Get a paginated list of vehicles in your organization's fleet
# 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
Your API key for authentication
**Example:** `sk_live_1234567890abcdef`
Your organization UUID
**Example:** `ff4adcc7-8172-45fe-9cf1-e90a6de53aa9`
Your user UUID
**Example:** `a1b2c3d4-e5f6-7890-abcd-ef1234567890`
### Query Parameters
Page number for pagination
**Example:** `1`
Number of items per page (max: 100)
**Example:** `50`
Advanced filtering criteria (format: `field:value`)
**Example:** `"country:ES"`, `"type:passenger"`, `"ownership:owned"`
Sort criteria (format: `field:asc` or `field:desc`)
**Example:** `"name:asc"`, `"created_at:desc"`, `"license_plate:asc"`
Filter by creation date start (Unix timestamp)
**Example:** `1704067200` (January 1, 2024)
Filter by creation date end (Unix timestamp)
**Example:** `1735689600` (January 1, 2025)
## Response
Current page number
Number of items per page
Total count of **active** vehicles
Total count of **archived** vehicles
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
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
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}"
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import requests
import os
api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")
user_id = os.getenv("DCYCLE_USER_ID")
headers = {
"Authorization": f"Bearer {api_key}",
"x-organization-id": org_id,
"x-user-id": user_id
}
params = {
"page": 1,
"size": 50,
"filter_by": "type:passenger"
}
response = requests.get(
"https://api.dcycle.io/api/v1/vehicles",
headers=headers,
params=params
)
vehicles = response.json()
print(f"Total active vehicles: {vehicles['total']}")
print(f"Total archived vehicles: {vehicles['total_archived']}")
for vehicle in vehicles['items']:
name = vehicle.get('name', vehicle.get('license_plate', 'Unnamed'))
print(f"- {name} ({vehicle['type']}): {vehicle['co2e']} kg CO2e")
```
```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const axios = require('axios');
const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;
const userId = process.env.DCYCLE_USER_ID;
const headers = {
'Authorization': `Bearer ${apiKey}`,
'x-organization-id': orgId,
'x-user-id': userId
};
const params = {
page: 1,
size: 50,
filter_by: 'type:passenger'
};
axios.get('https://api.dcycle.io/api/v1/vehicles', { headers, params })
.then(response => {
const vehicles = response.data;
console.log(`Total active vehicles: ${vehicles.total}`);
console.log(`Total archived vehicles: ${vehicles.total_archived}`);
vehicles.items.forEach(vehicle => {
const name = vehicle.name || vehicle.license_plate || 'Unnamed';
console.log(`- ${name} (${vehicle.type}): ${vehicle.co2e} kg CO2e`);
});
})
.catch(error => console.error(error));
```
### Successful Response
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:
```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
## Related Endpoints
Upload multiple vehicles via CSV
View your facilities
Add fuel consumption data
Learn about API authentication