Route Optimization Clustering

Cluster per Request

The clusteringLevel parameter controls how geographically tight the stops on each route are. Lower settings let the Route Optimization engine spread stops out to minimize overall cost; higher settings prefer compact, geographically clustered routes, which can slightly increase total cost/time. This field is fully optional — omitting it preserves current behavior.

Name	Type	Description
clusteringLevel	string	Optional. Only `LOW`, `MEDIUM`, and `HIGH` are accepted. They must be in capital case. Lower case such as `low` would not be accepted and will results in a 400 response.

📘
Allowed Values

LOW — minimize overall cost; no geographic-grouping preference (this is the optimizer's default behavior).

MEDIUM — moderate clustering; prefer compact routes while keeping cost increase small.

HIGH — maximize clustering; tightest geographic grouping, with no guarantee on how much cost may increase.

❗
Unacceptable Values
Any value other than LOW, MEDIUM, or HIGH is rejected. This includes things like EXTREME, lowercase high,a raw integer such as 2, null, or an empty string.

curl -X POST "https://onfleet.com/api/v2/optimizations/scheduled" \
     -u "<your_onfleet_api_key>:" \
     -d '{"tasks": [
             "atnk3APxhJrgfx9mgWaRhByQ",
             "4kA7bOH*Kz7K0YA6~NpqWDke"
           ],
           "teams": {
             "5y1jHFp7OBfFU6SekbwwwRfL": [
             "GLlLB2123ABCkXOJAHPklMPZ"
             ]
           },
           "date": 1718728193838,
           "timezone": "America/Toronto",
           "clusteringLevel": "HIGH"}'

Organization Clustering Level

An organization can set a default clusteringLevel on its route optimization profile so that it applies automatically to every scheduled optimization request that doesn't specify one directly. This setting requires Route Optimization v3 (ROv3) and is not exposed anywhere in the Onfleet dashboard — there is currently no UI to view, set, or confirm it. To enable a default clustering level for your org, contact [email protected] or your Customer Success Manager; they will configure it on the backend route optimization profile for your organization. Because there's no UI indicator, the only way to know what default (if any) is currently set for your org is to ask your CSM or Onfleet support directly.

Scope and Precedence

The per-request clusteringLevel (the field sent on the POST /optimizations/scheduled call) is the topmost — it takes precedence over everything else.
The order works like this, highest priority first:

Request-level clusteringLevel (sent in the JSON body of that specific call) — wins if present, no matter what's set at the org level.
Org-level default (the profile setting configured by support) — only applies if the request omits the field entirely.
Nothing set anywhere — unconstrained, optimizer just minimizes cost (today's behavior).

Organization profile setting is a fallback, not an override — it only kicks in when a given request doesn't specify its own value.