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

> Get the distinct values of a recharge field, with record counts, to populate a filter dropdown

[← Logistics API](/api-reference/logistics/overview)

Get the distinct values a field takes across your organization's logistics recharges, each with the number of records using it. Call it before rendering a filter so the dropdown offers only values that exist.

<Warning>
  **`field` is free text, not a closed list** — and an unsupported value does **not** return `422`. It returns an empty array:

  ```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
  { "field": "fuel", "total_count": 0, "values": [] }
  ```

  That makes "there are no recharges" and "I misspelled the field" look identical. The three accepted values are `fuel_name`, `file_id` and `vehicle_license_plate`; check your spelling against them before concluding the organization has no data.
</Warning>

<Note>
  **Only `active` recharges are counted.** Recharges still processing, or in error, are excluded from these values. A filter built from this response therefore describes your *calculated* data, not everything you uploaded.
</Note>

## Request

### Headers

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization whose recharges 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. Three values are supported:

  * `fuel_name` — `value` is the fuel **id**, `label` is the fuel name
  * `file_id` — `value` is the file id, `label` is the file name
  * `vehicle_license_plate` — `value` and `label` are both the plate; blank and missing plates are excluded

  Anything else returns an empty array rather than an error — see the warning above.
</ParamField>

## Response

<ResponseField name="field" type="string">
  The field that was queried, echoed back verbatim — including when it is not a supported one.
</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 | null">
      The raw value to send back as a filter. `null` when the underlying field is empty — for `fuel_name` and `file_id` that is a real bucket of recharges with no fuel or no source file, with its own count.
    </ResponseField>

    <ResponseField name="label" type="string | null">
      Human-readable caption. For `fuel_name` and `file_id` it comes from an outer join, so it can be `null` even when `value` is set — a fuel or file id that no longer resolves to a row.
    </ResponseField>

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

## Example

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X GET "https://api.dcycle.io/v1/logistics/recharges/unique-values?field=fuel_name" \
    -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

  HEADERS = {
      "x-api-key": "YOUR_API_KEY",
      "x-organization-id": "YOUR_ORGANIZATION_ID",
  }

  ACCEPTED = {"fuel_name", "file_id", "vehicle_license_plate"}


  def recharge_filter_values(field):
      # The API will not tell you the field is wrong, so check it yourself
      if field not in ACCEPTED:
          raise ValueError(f"{field!r} is not one of {sorted(ACCEPTED)}")

      return requests.get(
          "https://api.dcycle.io/v1/logistics/recharges/unique-values",
          headers=HEADERS,
          params={"field": field},
          timeout=30,
      ).json()


  data = recharge_filter_values("fuel_name")
  for item in data["values"]:
      print(f"{item['label'] or '(unknown fuel)'}: {item['count']}")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const ACCEPTED = ["fuel_name", "file_id", "vehicle_license_plate"];

  async function rechargeFilterValues(field) {
    if (!ACCEPTED.includes(field)) {
      throw new Error(`${field} is not one of ${ACCEPTED.join(", ")}`);
    }

    const params = new URLSearchParams({ field });
    const response = await fetch(
      `https://api.dcycle.io/v1/logistics/recharges/unique-values?${params}`,
      {
        headers: {
          "x-api-key": "YOUR_API_KEY",
          "x-organization-id": "YOUR_ORGANIZATION_ID",
        },
      },
    );
    return response.json();
  }
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "field": "fuel_name",
  "total_count": 2,
  "values": [
    {
      "value": "7c3f1a26-8d45-4b90-a1e3-52f6b8c40d97",
      "label": "Diesel",
      "count": 412
    },
    {
      "value": null,
      "label": null,
      "count": 9
    }
  ]
}
```

The second entry is the bucket of recharges with no fuel set — nine real records, not an error.

## Common Errors

### 422 Unprocessable Entity

**Cause:** `field` is missing entirely. Note that this is the *only* thing that fails validation here — a present but unsupported `field` succeeds with an empty array.

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

## Use Cases

### Build a recharge filter that matches reality

Populate the fuel or file dropdown from this endpoint rather than from the full fuel catalogue. It also tells you how many records sit behind each option, which lets you show counts next to each choice.

### Spot recharges with no fuel assigned

A `null` value in a `fuel_name` response is the count of recharges with no fuel. Those records cannot calculate emissions, and this is the cheapest way to notice they exist.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Recharges" icon="list" href="/api-reference/logistics/list-recharges">
    The records these values filter
  </Card>

  <Card title="Bulk Delete Recharges" icon="trash" href="/api-reference/logistics/batch-delete-recharges">
    Apply the filter you just built to a bulk delete
  </Card>

  <Card title="Create Recharge" icon="plus" href="/api-reference/logistics/create-recharge">
    Add the recharges you will be filtering
  </Card>

  <Card title="Logistics API" icon="truck-fast" href="/api-reference/logistics/overview">
    Everything the Logistics API covers
  </Card>
</CardGroup>