> ## 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 (Organization)

> Get the distinct values of a consumption field across every vehicle in the organization, to populate a filter dropdown

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

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.

<Note>
  **Two versions of this endpoint, two scopes.** This one is `/v2` and covers the whole organization. Its `/v1` sibling, [List Consumption Filter Values](/api-reference/vehicles/consumptions-unique-values), takes a `vehicle_id` in the path and covers one vehicle. Same query parameter, same response shape.
</Note>

## Request

### Headers

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization whose consumptions you are filtering.

  **Format:** UUID
</ParamField>

<ParamField header="x-api-key" type="string">
  Your API key.
</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, with licence plates as labels

  Any other value is rejected with `422`, so this is a closed list.
</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 — 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.
    </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, and do not expect a `null` bucket — there isn't one.
</Warning>

## Example

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

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

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

```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

### Filter the organization-wide consumption table

This is the endpoint behind the filter bar of [List All Vehicle Consumptions](/api-reference/vehicles/consumptions-org-list). 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.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List All Consumptions (Organization)" icon="table" href="/api-reference/vehicles/consumptions-org-list">
    The records these values filter
  </Card>

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

  <Card title="Filter Values (one vehicle)" icon="car" href="/api-reference/vehicles/consumptions-unique-values">
    The same thing scoped to a single vehicle
  </Card>

  <Card title="Vehicles API" icon="car" href="/api-reference/vehicles/overview">
    Everything the Vehicles API covers
  </Card>
</CardGroup>