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

> Get the distinct values of a waste field for one facility, with record counts, to populate a filter dropdown

[← Wastes API](/api-reference/wastes/overview)

Get the distinct values a field takes across one facility's waste records, each with the number of records using it. Call it before rendering a filter so the dropdown only offers values that actually exist — a list of every LER code in the catalogue would let a user pick one that returns nothing.

<Warning>
  **The path is `/v1/waste`, singular.** The Wastes API is split across two prefixes: the records themselves live under `/v1/wastes` (plural), while this endpoint and the bulk operations live under `/v1/waste`. Calling `/v1/wastes/unique-values` does not 404 — it returns `405 Method Not Allowed`, because the plural path matches `PATCH /v1/wastes/{waste_id}` and only its method is wrong. A `405` on a `GET` is the signal that you used the plural.
</Warning>

<Warning>
  **`facility_id` is required, but one field ignores it.** Four of the five fields scope their values to the facility you name. `created_at` does not: it filters only by organization, so it returns the creation dates of **every waste record in the organization**, whichever facility they belong to.

  The parameter is still mandatory for `created_at` — it is simply not applied. Do not rely on its values to describe the facility you asked about.
</Warning>

## Request

### Headers

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

  **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. Five values are accepted:

  * `file_id` — the source files the records were imported from
  * `created_at` — the dates records were created on
  * `identification_name` — the waste identification names in use
  * `ler_code` — the European Waste Catalogue codes in use
  * `rd_code` — the recovery/disposal codes in use

  Any other value is rejected with `422`, so this is a closed list rather than free text.
</ParamField>

<ParamField query="facility_id" type="string" required>
  UUID of the facility whose records you are filtering.

  **Format:** UUID
</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 — a UUID string for `file_id`, a date string for `created_at`, the code itself for `ler_code` and `rd_code`. This is what you send back as a filter.
    </ResponseField>

    <ResponseField name="label" type="string">
      Human-readable caption. For `file_id` it is the file name; for `ler_code` and `rd_code` it repeats the code itself, so you can render `label` uniformly without special-casing.
    </ResponseField>

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

<Warning>
  **There is no `null` bucket, whatever the field.** Records with no source file come back as the zero UUID, `00000000-0000-0000-0000-000000000000`, with their own count — treat it as "no file", not as a real id. The other three optional fields exclude their empty rows entirely, so their counts do not add up to the facility's total record count.
</Warning>

## Example

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

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

  data = requests.get(
      "https://api.dcycle.io/v1/waste/unique-values",
      headers=HEADERS,
      params={"field": "ler_code", "facility_id": "YOUR_FACILITY_ID"},
      timeout=30,
  ).json()

  # Only the LER codes this facility has actually reported
  for item in data["values"]:
      no_file = item["value"] == "00000000-0000-0000-0000-000000000000"
      caption = "(no source file)" if no_file else item["label"]
      print(f"{caption}: {item['count']} records")
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const params = new URLSearchParams({
    field: "ler_code",
    facility_id: facilityId,
  });
  const response = await fetch(
    `https://api.dcycle.io/v1/waste/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,
    count: v.count,
  }));
  ```
</CodeGroup>

### Successful Response

Returns `200 OK`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "field": "ler_code",
  "total_count": 2,
  "values": [
    {
      "value": "150101",
      "label": "150101",
      "count": 34
    },
    {
      "value": "200301",
      "label": "200301",
      "count": 12
    }
  ]
}
```

## Common Errors

### 422 Unprocessable Entity

**Cause:** `field` or `facility_id` is missing. Both are required.

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

**Cause:** `field` is not one of the five 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', 'created_at', 'identification_name', 'ler_code', 'rd_code'",
      "type": "type_error.enum",
      "ctx": {
        "enum_values": ["file_id", "created_at", "identification_name", "ler_code", "rd_code"]
      }
    }
  ]
}
```

## Use Cases

### Build a filter that never comes back empty

Populate your LER or RD dropdown from this endpoint rather than from the full code catalogue. The catalogue has hundreds of codes; a given facility reports a handful, and offering the rest only produces empty result sets.

### Check what an import actually created

`field=file_id` groups a facility's waste records by the file they came from, with counts — the quickest confirmation that an upload landed where you expected, and the input to a cleanup if it did not.

## Related Endpoints

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

  <Card title="List Waste Emission Factors" icon="recycle" href="/api-reference/wastes/emission-factors">
    The LER and RD code catalogue, for creating records
  </Card>

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

  <Card title="Wastes API" icon="trash" href="/api-reference/wastes/overview">
    Everything the Wastes API covers
  </Card>
</CardGroup>