> ## 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 Consumption Filter Values

> Get the distinct values of a consumption field, with how many records use each one, to populate a filter dropdown

[← Vehicles API](/api-reference/vehicles/overview)

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.

<Note>
  **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)](/api-reference/vehicles/consumptions-org-unique-values) — same query parameter, same response shape, no path id.
</Note>

## Request

### Headers

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization the vehicle belongs to.

  **Format:** UUID
</ParamField>

<ParamField header="x-api-key" type="string">
  Your API key.
</ParamField>

### Path Parameters

<ParamField path="vehicle_id" type="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`.
</ParamField>

### Query Parameters

<ParamField query="field" type="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.
</ParamField>

## Response

<ResponseField name="field" type="string">
  The field that was queried, echoed back.
</ResponseField>

<ResponseField name="total_count" type="integer">
  How many distinct values were found.
</ResponseField>

<ResponseField name="values" type="array[object]">
  The distinct values, each with its record count.

  <Expandable title="Value Object">
    <ResponseField name="value" type="string">
      The raw value, as a UUID string. This is what you send back as a filter.
    </ResponseField>

    <ResponseField name="label" type="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.
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of consumption records carrying this value.
    </ResponseField>
  </Expandable>
</ResponseField>

<Warning>
  **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.
</Warning>

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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,
  }));
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "detail": [
    {
      "loc": ["query", "field"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Vehicle Consumptions" icon="list" href="/api-reference/vehicles/consumptions">
    The records these values filter
  </Card>

  <Card title="Delete Consumptions by File" icon="trash" href="/api-reference/vehicles/consumptions-delete-by-file">
    Remove every record that came from one file
  </Card>

  <Card title="Bulk Delete by Filters" icon="filter" href="/api-reference/vehicles/consumptions-bulk-delete-by-filters">
    Apply the filter you just built to a bulk delete
  </Card>

  <Card title="Filter Values (Organization)" icon="table" href="/api-reference/vehicles/consumptions-org-unique-values">
    The same values across every vehicle at once
  </Card>
</CardGroup>