List Consumption Filter Values

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions/unique-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions/unique-values"

headers = {"x-organization-id": "<x-organization-id>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "field": "<string>",
  "total_count": 123,
  "values": {
    "value": "<string>",
    "label": {},
    "count": 123
  }
}

GET

vehicles

{vehicle_id}

consumptions

unique-values

List Consumption Filter Values

const options = {method: 'GET', headers: {'x-organization-id': '<x-organization-id>'}};

fetch('https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions/unique-values', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions/unique-values"

headers = {"x-organization-id": "<x-organization-id>"}

response = requests.get(url, headers=headers)

print(response.text)

{
  "field": "<string>",
  "total_count": 123,
  "values": {
    "value": "<string>",
    "label": {},
    "count": 123
  }
}

← Vehicles API Get the distinct values a field takes across one vehicle’s consumption records, each with the number of records that use it. This is what you call to build a filter dropdown that only offers values that actually exist — instead of showing every option and letting the user pick one that returns nothing.

This endpoint is scoped to a single vehicle, named in the path. To cover every vehicle at once use the organization-wide version, List Consumption Filter Values (Organization) — same query parameter, same response shape, no path id.

Request

Headers

string

required

UUID of the organization the vehicle belongs to.Format: UUID

string

Your API key.

Path Parameters

string

required

UUID of the vehicle whose consumptions you are filtering.The vehicle is resolved across the consolidated organization family — the header organization and its subsidiaries — so a holding can filter a subsidiary’s consumptions. A vehicle outside that perimeter returns 404, never 403.

Query Parameters

string

required

The field to list values for. Two values are accepted:

file_id — the source files consumptions were imported from
vehicle_id — the vehicles the records belong to

Any other value is rejected with 422, so this is a closed list rather than a free-text field.

Response

string

The field that was queried, echoed back.

integer

How many distinct values were found.

array[object]

The distinct values, each with its record count.

Show Value Object

string

The raw value, as a UUID string. This is what you send back as a filter.

string | null

Human-readable label for the value — the file name for file_id, the licence plate for vehicle_id. Show this to the user and keep value for the query. It can be null when the record has no file name or the vehicle has no plate.

integer

Number of consumption records carrying this value.

Records with no source file come back as the zero UUID, not as null. A file_id that is empty in the database is serialised as 00000000-0000-0000-0000-000000000000, with its own count. Treat that value as “no file” rather than as a real file id — there is no null bucket to guard for.

Example

curl -X GET "https://api.dcycle.io/v1/vehicles/YOUR_VEHICLE_ID/consumptions/unique-values?field=file_id" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

import requests

response = requests.get(
    f"https://api.dcycle.io/v1/vehicles/{vehicle_id}/consumptions/unique-values",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "x-organization-id": "YOUR_ORGANIZATION_ID",
    },
    params={"field": "file_id"},
    timeout=30,
)
data = response.json()

# Offer only the files that actually produced consumptions for this vehicle
for item in data["values"]:
    no_file = item["value"] == "00000000-0000-0000-0000-000000000000"
    caption = "(no source file)" if no_file else (item["label"] or item["value"])
    print(f"{caption}: {item['count']} records")

const params = new URLSearchParams({ field: "file_id" });
const response = await fetch(
  `https://api.dcycle.io/v1/vehicles/${vehicleId}/consumptions/unique-values?${params}`,
  {
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "x-organization-id": "YOUR_ORGANIZATION_ID",
    },
  },
);
const data = await response.json();

const NO_FILE = "00000000-0000-0000-0000-000000000000";

const options = data.values.map((v) => ({
  value: v.value,
  caption: v.value === NO_FILE ? "(no source file)" : (v.label ?? v.value),
  count: v.count,
}));

Successful Response

Returns 200 OK.

{
  "field": "file_id",
  "total_count": 2,
  "values": [
    {
      "value": "9f1c5a84-3b27-4d61-9e05-2a7c8f4b6d13",
      "label": "consumptions_2026_Q1.csv",
      "count": 128
    },
    {
      "value": "4d2e7b90-6c18-4a35-8f72-1b9e3c5a0d47",
      "label": "consumptions_2026_Q2.csv",
      "count": 94
    }
  ]
}

Common Errors

404 Not Found

Cause: The vehicle does not exist, or it belongs to an organization outside the one in x-organization-id. Both cases return the same 404 on purpose — the API never reveals that a vehicle exists in another organization.

422 Unprocessable Entity

Cause: field is missing.

{
  "detail": [
    {
      "loc": ["query", "field"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Cause: field is not one of the two accepted values.

{
  "detail": [
    {
      "loc": ["query", "field"],
      "msg": "value is not a valid enumeration member; permitted: 'file_id', 'vehicle_id'",
      "type": "type_error.enum",
      "ctx": {
        "enum_values": ["file_id", "vehicle_id"]
      }
    }
  ]
}

Use Cases

Build a filter that never returns nothing

Call this endpoint before rendering the filter, and offer only the values it returns. A dropdown built from the catalog of all possible files would let a user pick one that has no consumptions for this vehicle; a dropdown built from this response cannot.

Find which upload produced which records

field=file_id groups a vehicle’s consumptions by the file they came from, with counts. That is the quickest way to confirm an import landed where you expected, and the input to a delete-by-file cleanup if it did not.

List Vehicle Consumptions

The records these values filter

Delete Consumptions by File

Remove every record that came from one file

Bulk Delete by Filters

Apply the filter you just built to a bulk delete

Filter Values (Organization)

The same values across every vehicle at once

​Request

​Headers

​Path Parameters

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​404 Not Found

​422 Unprocessable Entity

​Use Cases

​Build a filter that never returns nothing

​Find which upload produced which records

​Related Endpoints

List Vehicle Consumptions

Delete Consumptions by File

Bulk Delete by Filters

Filter Values (Organization)

Request

Headers

Path Parameters

Query Parameters

Response

Example

Successful Response

Common Errors

404 Not Found

422 Unprocessable Entity

Use Cases

Build a filter that never returns nothing

Find which upload produced which records

Related Endpoints