Skip to main content
GET
/
v2
/
vehicle_consumptions
List All Vehicle Consumptions (Organization)
const options = {
  method: 'GET',
  headers: {'x-api-key': '<x-api-key>', 'x-organization-id': '<x-organization-id>'}
};

fetch('https://api.dcycle.io/v2/vehicle_consumptions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "items": {
    "id": "<string>",
    "vehicle_id": "<string>",
    "license_plate": {},
    "custom_id": {},
    "quantity": 123,
    "unit": {},
    "start_date": "<string>",
    "end_date": "<string>",
    "status": "<string>",
    "file_id": {},
    "file_name": {},
    "co2e": {},
    "total_energy_kwh": {},
    "created_at": {},
    "updated_at": {}
  },
  "total": 123,
  "page": 123,
  "size": 123,
  "filter_hash": "<string>"
}

​
List All Vehicle Consumptions (Organization)

Get a paginated list of consumption records across every vehicle in your organization, instead of one vehicle at a time. This powers an “all consumptions” table view — useful when a single uploaded file was split into consumptions across many vehicles and you want to review, filter, or bulk-delete them as a group.
Organization-scoped: This endpoint only returns consumptions for vehicles owned directly by the organization in x-organization-id. It does not include consumptions from child organizations in a holding.

​
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

​
vehicle_id[]
array[string]
Narrow the results to specific vehicle UUIDs
​
status[]
array[string]
Filter by consumption statusAvailable values: active, success, loading, error
​
unit_id[]
array[string]
Filter by fuel unit UUIDs
​
file_id[]
array[string]
Filter by source file UUIDs — the primary way to isolate all consumptions created from one bulk upload, across all the vehicles it was split into
​
custom_id
string
Filter by custom identifier (substring match)
​
start_date
string
Filter consumptions with a start date on or after this date (YYYY-MM-DD)
​
end_date
string
Filter consumptions with an end date on or before this date (YYYY-MM-DD)
​
created_at_from
string
Filter consumptions created on or after this datetime (ISO 8601)
​
created_at_to
string
Filter consumptions created on or before this datetime (ISO 8601)
​
co2e_status
string
Filter by CO2e calculation statusAvailable values: calculated, not_calculated
​
sort
string
Sort field, optionally prefixed with - for descendingExample: -created_at
​
page
integer
default:"1"
Page number for pagination
​
size
integer
default:"50"
Number of items per page (max 100)

​
Response

​
items
array[object]
Array of consumption objects
​
total
integer
Total number of matching consumption records
​
page
integer
Current page number
​
size
integer
Number of items per page
​
filter_hash
string
Hash of the currently applied filters. Pass this back unchanged when calling Bulk Delete by Filters with the same filters, as a safety check against stale filter state.

​
Example

curl -X GET "https://api.dcycle.io/v2/vehicle_consumptions?file_id[]=880e8400-e29b-41d4-a716-446655440000&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",
      "license_plate": "1234-ABC",
      "custom_id": null,
      "quantity": 100.5,
      "unit": { "id": "54a709bf-79fe-4acb-ab85-5e1d7cd26eb4", "name": "litre_(l)", "type": "liquid" },
      "start_date": "2024-01-01",
      "end_date": "2024-01-31",
      "status": "success",
      "file_id": "880e8400-e29b-41d4-a716-446655440000",
      "file_name": "consumos_matriz_2024_01.csv",
      "co2e": 234.7,
      "total_energy_kwh": 987.2,
      "created_at": "2024-02-01T08:00:00Z",
      "updated_at": "2024-02-01T08:00:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "size": 50,
  "filter_hash": "b4c2d3e5f6a7b8c9"
}

​
Common Errors

​
401 Unauthorized

Cause: Missing or invalid API key 
{
  "detail": "Invalid API key",
  "code": "INVALID_API_KEY"
}

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

Unique Values (Organization)

Get filter dropdown values, e.g. all source files, across the organization

Bulk Delete (Organization)

Delete consumptions by ID, across any vehicle in the organization

Bulk Delete by Filters (Organization)

Delete every consumption matching the current filters, e.g. an entire uploaded file

Vehicle Consumptions

List consumptions for a single vehicle