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

> Get the distinct values of a shipment 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 requests (shipments), each with the number of shipments using it. Call it before rendering a filter so the dropdown offers only values that exist: the vehicle types your shipments actually use, the files they came from, the people who uploaded them.

<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": "toc", "total_count": 0, "values": [] }
  ```

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

<Note>
  **Only `active` shipments are counted.** Shipments in any other status (such as `error`) are excluded from these values. A filter built from this response therefore matches what [List Logistics Requests](/api-reference/logistics/list-requests) returns by default (`trip_status` unset).
</Note>

## Request

### Headers

<ParamField header="x-organization-id" type="string" required>
  UUID of the organization whose shipments 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:

  * `vehicle_type` — `value` and `label` are both the TOC name, `<vehicle>_<type>` (e.g. `van_3.5_t_diesel`). It is the exact string the `vehicle_type[]` and `filter_by=vehicle_type:in[...]` filters of [List Logistics Requests](/api-reference/logistics/list-requests) take. Shipments without a TOC are excluded. Sorted by name.
  * `file_id` — `value` is the id of the source file, `label` is the file name. Shipments created one by one or through the API have no file: they come back as one bucket whose `value` is the all-zero UUID `00000000-0000-0000-0000-000000000000`.
  * `uploaded_by` — `value` is the id of the user who uploaded the shipments, `label` is that user's first and last name. Shipments with no uploader are excluded.

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

<ParamField query="project_id" type="string">
  Only used with `field=vehicle_type`: narrows the list to the TOCs of the shipments linked to this project. Ignored for `file_id` and `uploaded_by`. A project with no shipments returns an empty list, not an error.

  **Format:** UUID
</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 shipment count.

  <Expandable title="Value Object">
    <ResponseField name="value" type="string">
      The raw value to send back as a filter: a TOC name, a file id (or the all-zero UUID for shipments with no file), or a user id.
    </ResponseField>

    <ResponseField name="label" type="string | null">
      Human-readable caption. For `vehicle_type` it repeats `value`, untranslated. For `file_id` it is `null` on the no-file bucket. For `uploaded_by` it is `null` when the user has no name or no longer resolves to a user.
    </ResponseField>

    <ResponseField name="count" type="integer">
      Number of active shipments carrying this value. An estimate for large organizations — see below.
    </ResponseField>
  </Expandable>
</ResponseField>

### Large organizations

When an organization has more than **250,000** active shipments, grouping every row would take minutes, so the values come from smaller sources and the counts become approximations:

* **`count` is a PostgreSQL planner estimate**, not an exact count. Use it to rank options, not to report totals.
* **`file_id`** lists the organization's file uploads that were not deleted, newest first, and `count` is the number of rows the file had when it was uploaded: shipments deleted later are not subtracted. The no-file bucket is added at the end when the estimate finds any.
* **`uploaded_by`** lists every member of the organization, sorted by name. Members who never uploaded a shipment can appear: filtering by them returns no rows.
* **`vehicle_type`** lists the TOCs the organization's active shipments use, with estimated counts. With `project_id`, the threshold applies to the shipments linked to the project: a project above 250,000 gets the organization's TOCs, a superset of the project's. It never offers a TOC the organization does not use.

Below the threshold every value and count is exact.

## Example

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

  ACCEPTED = {"file_id", "uploaded_by", "vehicle_type"}


  def shipment_filter_values(field, project_id=None):
      # 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)}")

      params = {"field": field}
      if project_id:
          params["project_id"] = project_id

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


  data = shipment_filter_values("vehicle_type", project_id="YOUR_PROJECT_ID")
  for item in data["values"]:
      print(f"{item['label']}: {item['count']}")
  ```

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

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

    const params = new URLSearchParams({ field });
    if (projectId) params.set("project_id", projectId);

    const response = await fetch(
      `https://api.dcycle.io/v1/logistics/requests/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": "vehicle_type",
  "total_count": 3,
  "values": [
    {
      "value": "artic_truck_up_to_40_t_gvw_average_diesel",
      "label": "artic_truck_up_to_40_t_gvw_average_diesel",
      "count": 18240
    },
    {
      "value": "rigid_truck_7.5_12_t_gvw_average_diesel",
      "label": "rigid_truck_7.5_12_t_gvw_average_diesel",
      "count": 5312
    },
    {
      "value": "van_3.5_t_diesel",
      "label": "van_3.5_t_diesel",
      "count": 977
    }
  ]
}
```

A TOC name can cover several TOCs (one per region); their shipments are added into a single entry, because the filters take the name.

## Common Errors

### 422 Unprocessable Entity

**Cause:** `field` is missing entirely, or `project_id` is not a valid UUID. A present but unsupported `field` does not fail: it succeeds with an empty array.

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

## Use Cases

### Offer only the vehicle types a list uses

The TOC catalogue has hundreds of entries, and an organization's shipments use a handful. Populate the vehicle type dropdown from `field=vehicle_type` (with the `project_id` of the list you are showing, if any) so every option returns rows, then send the chosen names back to [List Logistics Requests](/api-reference/logistics/list-requests):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G "https://api.dcycle.io/v1/logistics/requests" \
  --data-urlencode "vehicle_type[]=van_3.5_t_diesel" \
  --data-urlencode "vehicle_type[]=rigid_truck_7.5_12_t_gvw_average_diesel" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"
```

### Find the shipments created without a file

The `file_id` bucket with the all-zero UUID counts the shipments created one by one or through the API. To list them, pass that value in a column filter, which reads it as "no file": `filter_by=file_id:in["00000000-0000-0000-0000-000000000000"]`. The `file_id[]` parameter compares it literally and matches nothing.

## Related Endpoints

<CardGroup cols={2}>
  <Card title="List Logistics Requests" icon="list" href="/api-reference/logistics/list-requests">
    The shipments these values filter
  </Card>

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

  <Card title="List Available Vehicle Types" icon="truck" href="/api-reference/logistics/list-tocs">
    The full TOC catalogue, used or not
  </Card>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.