List Consumption Filter Values (Organization)

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

fetch('https://api.dcycle.io/v2/vehicle_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/v2/vehicle_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

vehicle_consumptions

unique-values

List Consumption Filter Values (Organization)

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

fetch('https://api.dcycle.io/v2/vehicle_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/v2/vehicle_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 every vehicle in your organization, each with the number of records using it. This is the companion to the organization-wide consumption list: call it to build a filter that only offers values which actually exist.

Two versions of this endpoint, two scopes. This one is /v2 and covers the whole organization. Its /v1 sibling, List Consumption Filter Values, takes a vehicle_id in the path and covers one vehicle. Same query parameter, same response shape.

Request

Headers

string

required

UUID of the organization whose consumptions you are filtering.Format: UUID

string

Your API key.

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, with licence plates as labels

Any other value is rejected with 422, so this is a closed list.

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 — the file name for file_id, the licence plate for vehicle_id. Can be null when the record has no file name or the vehicle has no plate; value is still usable.

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, and do not expect a null bucket — there isn’t one.

Example

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

import requests

NO_FILE = "00000000-0000-0000-0000-000000000000"

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

for item in data["values"]:
    if item["value"] == NO_FILE:
        print(f"no source file: {item['count']} records")
    else:
        print(f"{item['label']}: {item['count']} records")

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

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

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": "00000000-0000-0000-0000-000000000000",
      "label": null,
      "count": 9
    }
  ]
}

The second entry is the nine records with no source file, not a file whose id happens to be zeros.

Common Errors

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

Filter the organization-wide consumption table

This is the endpoint behind the filter bar of List All Vehicle Consumptions. Because it returns counts, you can also show how many records sit behind each option before the user picks it.

Isolate one upload that was split across vehicles

A bulk upload usually creates consumptions on many vehicles at once. field=file_id gives you each source file with its record count in a single call — which is what you need before bulk-deleting an import that went wrong.

List All Consumptions (Organization)

The records these values filter

Bulk Delete by Filters (Organization)

Apply the filter you just built

Filter Values (one vehicle)

The same thing scoped to a single vehicle

Vehicles API

Everything the Vehicles API covers

​Request

​Headers

​Query Parameters

​Response

​Example

​Successful Response

​Common Errors

​422 Unprocessable Entity

​Use Cases

​Filter the organization-wide consumption table

​Isolate one upload that was split across vehicles

​Related Endpoints

List All Consumptions (Organization)

Bulk Delete by Filters (Organization)

Filter Values (one vehicle)

Vehicles API

Request

Headers

Query Parameters

Response

Example

Successful Response

Common Errors

422 Unprocessable Entity

Use Cases

Filter the organization-wide consumption table

Isolate one upload that was split across vehicles

Related Endpoints