Route refinement
Re-optimize an existing plan locally or globally, keeping chosen stops frozen.
routing.refine
Stable
node
How to call it
REST
POST
/v1/routing/refine
202
GraphQL
mutation
openRoutingRefine
MCP
open_routing_refine
Re-optimize an existing plan, optionally freezing stops that must not move. Billed per node, same as optimize. Optional routing rules: ride time limits, release times, order groups, incompatible goods classes, alternative locations, deliveries before pickups, waiting cost, use all vehicles, stop merging, reload depots and loading bays, EV range, shifts, and break skip policies and places. An engine that cannot plan a rule refuses it with VALIDATION_FAILED; an approximated rule comes back as a RULE_APPROXIMATED warning. Which engine plans which rule, from which engine version, is listed as routing_rules by open_routing_presets.
Request schema
Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.
POST /v1/routing/refine
{
"type": "object",
"properties": {
"callback": {
"type": [
"object",
"null"
],
"properties": {
"events": {
"type": "array",
"items": {
"type": "string",
"maxLength": 32
}
},
"format": {
"type": [
"string",
"null"
],
"enum": [
"native",
"ce_binary",
"ce_structured"
]
},
"secret": {
"type": [
"string",
"null"
],
"minLength": 16,
"maxLength": 255,
"description": "Required when callback.signature is standard_webhooks."
},
"signature": {
"type": [
"string",
"null"
],
"enum": [
"native",
"standard_webhooks"
]
},
"url": {
"type": "string",
"maxLength": 2048,
"format": "uri",
"description": "Required when callback is present."
}
}
},
"constraints": {
"type": [
"object",
"null"
],
"properties": {
"balance": {
"type": [
"string",
"null"
],
"enum": [
"none",
"balanced",
"min_change",
"sla_protect",
"tolerance",
"zone",
"hours",
"zone_hours"
]
},
"balance_tolerance": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
},
"deliveries_before_pickups": {
"type": [
"boolean",
"null"
]
},
"incompatible_goods_classes": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 64
}
},
"maxItems": 500
},
"max_ride_seconds": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 86400
},
"merge_stops": {
"type": [
"object",
"null"
],
"properties": {
"max_stops": {
"type": [
"integer",
"null"
],
"minimum": 2,
"maximum": 50
},
"radius_meters": {
"type": "integer",
"minimum": 1,
"maximum": 1000,
"description": "Required when constraints.merge_stops is present."
},
"same_window_only": {
"type": [
"boolean",
"null"
]
}
}
},
"region_filter": {
"type": [
"boolean",
"null"
]
},
"reload": {
"type": [
"object",
"null"
],
"properties": {
"depots": {
"type": "array",
"minItems": 1,
"maxItems": 10,
"description": "Required when constraints.reload is present.",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"loading_bays": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"location": {
"type": "array"
}
}
}
},
"loading_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 14400
},
"max_reloads": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 5
},
"slot_seconds": {
"type": [
"integer",
"null"
],
"minimum": 60,
"maximum": 14400
}
}
},
"use_all_vehicles": {
"type": [
"string",
"null"
],
"enum": [
"off",
"low",
"normal",
"high"
]
},
"waiting_cost": {
"type": [
"string",
"null"
],
"enum": [
"off",
"low",
"normal",
"high"
]
}
}
},
"engine": {
"type": [
"string",
"null"
],
"enum": [
"sroute",
"sroute2",
"sroute2t",
"sroute3"
]
},
"existing_routes": {
"type": "array"
},
"freeze": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
}
},
"jobs": {
"type": "array",
"maxItems": 10000,
"items": {
"type": "object",
"properties": {
"alternatives": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"location": {
"type": "array"
},
"time_window": {
"type": [
"array",
"null"
]
}
}
},
"maxItems": 10
},
"amount": {
"type": [
"array",
"null"
]
},
"goods_class": {
"type": [
"string",
"null"
],
"maxLength": 64
},
"group": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"id": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"location": {
"type": "array",
"description": "Required when jobs is present."
},
"priority": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 100
},
"release_at": [],
"service_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"setup_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"skills": {
"type": [
"array",
"null"
]
},
"time_windows": {
"type": [
"array",
"null"
]
}
}
}
},
"mode": {
"type": [
"string",
"null"
],
"enum": [
"auto",
"sync",
"async"
]
},
"options": {
"type": [
"object",
"null"
],
"properties": {
"geometry": {
"type": [
"boolean",
"null"
]
}
}
},
"profile": {
"type": [
"string",
"null"
],
"enum": [
"car",
"van",
"truck",
"bike",
"foot",
"motorcycle"
]
},
"region": {
"type": [
"string",
"null"
],
"enum": [
"NA",
"EU",
"AU",
"ASIA",
"na",
"eu",
"au",
"asia"
]
},
"shipments": {
"type": "array",
"maxItems": 5000,
"items": {
"type": "object",
"properties": {
"delivery": {
"type": "array",
"description": "Required when shipments is present."
},
"goods_class": {
"type": [
"string",
"null"
],
"maxLength": 64
},
"group": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"id": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"max_ride_seconds": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"pickup": {
"type": "array",
"description": "Required when shipments is present."
}
}
}
},
"vehicles": {
"type": "array",
"minItems": 1,
"maxItems": 2000,
"items": {
"type": "object",
"properties": {
"breaks": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"duration_seconds": [],
"places": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"location": {
"type": "array"
}
}
},
"maxItems": 10
},
"skip_policy": {
"type": [
"string",
"null"
],
"enum": [
"if_no_intersection",
"if_route_ends_before_window_end"
]
},
"windows": []
}
},
"maxItems": 10
},
"capacity": {
"type": [
"array",
"null"
]
},
"end": {
"type": [
"array",
"null"
]
},
"ev_range_meters": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"ev_reserve_meters": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"id": {
"type": [
"string",
"null"
],
"maxLength": 128
},
"latest_departure_at": [],
"max_distance_meters": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"max_tasks": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"max_travel_time_seconds": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"return_to_start": {
"type": [
"boolean",
"null"
]
},
"shifts": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"end": {
"type": [
"array",
"null"
]
},
"from": [],
"start": {
"type": [
"array",
"null"
]
},
"to": []
}
},
"maxItems": 6
},
"skills": {
"type": "array",
"items": {
"type": "string",
"maxLength": 64
}
},
"start": {
"type": [
"array",
"null"
]
},
"time_window": {
"type": [
"array",
"null"
]
}
}
}
}
},
"additionalProperties": false,
"required": [
"existing_routes",
"vehicles"
]
}Request example
{
"vehicles": [
{
"id": "van-1",
"start": {
"lat": 45.5017,
"lng": -73.5673
},
"return_to_start": true,
"capacity": [
10
],
"time_window": [
"2026-11-02T08:00:00-05:00",
"2026-11-02T17:00:00-05:00"
]
},
{
"id": "van-2",
"start": {
"lat": 45.5017,
"lng": -73.5673
},
"return_to_start": true,
"capacity": [
10
]
}
],
"jobs": [
{
"id": "order-1001",
"location": {
"lat": 45.5088,
"lng": -73.554
},
"service_seconds": 300,
"amount": [
2
]
},
{
"id": "order-1002",
"location": {
"lat": 45.4972,
"lng": -73.5786
},
"service_seconds": 300,
"amount": [
3
],
"time_windows": [
[
"2026-11-02T09:00:00-05:00",
"2026-11-02T12:00:00-05:00"
]
]
},
{
"id": "order-1003",
"location": {
"lat": 45.5231,
"lng": -73.5817
},
"service_seconds": 240,
"amount": [
1
]
}
],
"existing_routes": [
{
"vehicle_id": "van-1",
"stops": [
{
"id": "order-1001"
},
{
"id": "order-1002"
}
]
},
{
"vehicle_id": "van-2",
"stops": [
{
"id": "order-1003"
}
]
}
]
}Response
What a successful call returns: the schema of `data` and `meta`, with a description of each field, followed by an example response from a real call.
POST /v1/routing/refine
Response schema
{
"description": "The refined plan, in the same shape as routing.optimize. Stops listed in `freeze` keep their vehicle and order; the rest may move between vehicles. Billed on the nodes the plan holds.",
"data": {
"type": "object",
"properties": {
"routes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"vehicle_id": {
"type": "string",
"description": "The caller's vehicle id."
},
"stops": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"start",
"job",
"pickup",
"delivery",
"break",
"end"
],
"description": "What happens at this stop. `start` and `end` are the vehicle's own endpoints; `pickup` and `delivery` are the two legs of a shipment."
},
"id": {
"type": "string",
"description": "The caller's id of the job or shipment served here. Absent on start, end and break."
},
"shipment_leg": {
"type": "string",
"enum": [
"pickup",
"delivery"
],
"description": "Which leg of the shipment `id` names. Present on shipment stops only."
},
"arrival": {
"type": [
"string",
"null"
],
"description": "When the vehicle arrives, ISO 8601 with offset. Null when the engine reported no time."
},
"arrival_epoch": {
"type": [
"integer",
"null"
],
"description": "`arrival` as Unix seconds."
},
"arrival_offset_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds from the route's start to this stop. Present instead of `arrival` and `arrival_epoch` only when nothing in the request carried a time: no vehicle `time_window` and no job time window."
},
"distance_meters": {
"type": [
"integer",
"null"
],
"description": "Distance driven from the route start to this stop, cumulative."
},
"duration_seconds": {
"type": [
"integer",
"null"
],
"description": "Driving time from the route start to this stop, cumulative."
},
"leg_distance_meters": {
"type": "integer",
"description": "Distance of the hop into this stop from the previous one."
},
"leg_duration_seconds": {
"type": "integer",
"description": "Driving time of the hop into this stop from the previous one."
},
"load": {
"type": "array",
"items": {
"type": "number"
},
"description": "What the vehicle carries when it leaves this stop, one figure per capacity dimension, in the order of `meta.capacity_dimensions`."
}
},
"required": [
"type"
]
},
"description": "The stops in driving order, start and end included."
},
"stop_count": {
"type": "integer",
"description": "Number of entries in `stops`."
},
"task_count": {
"type": "integer",
"description": "Jobs and shipment legs served on this route (start, end and breaks not counted)."
},
"distance_meters": {
"type": "integer",
"description": "Total distance driven."
},
"duration_seconds": {
"type": "integer",
"description": "Total driving time. Service and waiting are reported separately."
},
"service_seconds": {
"type": "integer",
"description": "Total service time at the stops."
},
"waiting_seconds": {
"type": "integer",
"description": "Total time spent waiting for time windows to open."
},
"geometry": {
"type": [
"string",
"null"
],
"description": "Encoded polyline (precision 5) of the whole route. Null unless `options.geometry` was true."
}
},
"required": [
"vehicle_id",
"stops"
]
},
"description": "One route per vehicle that received work. A vehicle left idle does not appear."
},
"unassigned": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "The caller's id of the job or shipment that no vehicle took."
},
"shipment_leg": {
"type": [
"string",
"null"
],
"enum": [
"pickup",
"delivery",
null
],
"description": "For a shipment, which leg was left over."
},
"reason": {
"type": "string",
"description": "Why it was left over, as reported by the engine; `unspecified` when the engine gave no reason."
}
}
},
"description": "Work no vehicle could take. Empty when everything was placed."
},
"summary": {
"type": "object",
"properties": {
"routes": {
"type": "integer",
"description": "Routes in the plan (vehicles with work)."
},
"assigned": {
"type": "integer",
"description": "Tasks placed on a route."
},
"unassigned": {
"type": "integer",
"description": "Tasks left in `unassigned`."
},
"distance_meters": {
"type": "integer",
"description": "Sum of every route's distance."
},
"duration_seconds": {
"type": "integer",
"description": "Sum of every route's driving time."
}
}
}
},
"required": [
"routes",
"unassigned",
"summary"
]
},
"meta": {
"type": "object",
"description": "Facts about the solve.",
"properties": {
"engine": {
"type": "string",
"enum": [
"sroute",
"sroute2",
"sroute2t",
"sroute3"
],
"description": "The engine that answered."
},
"engine_version": {
"type": "string",
"description": "That engine's version."
},
"solve_id": {
"type": "string",
"description": "The engine's id for this solve. Quote it with `request_id` when asking support about a plan."
},
"capacity_dimensions": {
"type": "array",
"items": {
"type": "string"
},
"description": "The names of the capacity dimensions, in the order `load` reports them. A list capacity is named by position (`\"0\"`, `\"1\"`, ...)."
},
"balance": {
"type": "object",
"description": "Present only when `constraints.balance` was `tolerance`, `zone`, `hours` or `zone_hours`; see the routing.optimize reference for its fields.",
"properties": {}
},
"rule_notices": {
"type": "array",
"items": {
"type": "object",
"properties": {}
},
"description": "Present only when a routing rule was approximated or adjusted; each entry is also a RULE_APPROXIMATED or RULE_ADJUSTED warning."
},
"mode": {
"type": "string",
"enum": [
"sync",
"async"
],
"description": "Present on a queued answer."
}
},
"additionalProperties": true
}
}Response example
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "routing.refine",
"billing": {
"unit": "node",
"quantity": 5,
"counted": true,
"breakdown": {
"nodes": 5,
"jobs": 3,
"shipments": 0,
"shipment_nodes": 0,
"vehicles": 2,
"vehicle_nodes": 2,
"route_stops": 0
}
},
"data": {
"routes": [
{
"vehicle_id": "van-1",
"stops": [
{
"type": "start",
"arrival": "2026-11-02T08:00:00-05:00",
"arrival_epoch": 1793624400,
"distance_meters": 0,
"duration_seconds": 0,
"load": [
3
]
},
{
"type": "job",
"arrival": "2026-11-02T08:08:01-05:00",
"arrival_epoch": 1793624881,
"distance_meters": 3635,
"duration_seconds": 481,
"leg_distance_meters": 3635,
"leg_duration_seconds": 481,
"id": "order-1003",
"load": [
2
]
},
{
"type": "job",
"arrival": "2026-11-02T08:18:34-05:00",
"arrival_epoch": 1793625514,
"distance_meters": 6563,
"duration_seconds": 874,
"leg_distance_meters": 2928,
"leg_duration_seconds": 393,
"id": "order-1001",
"load": [
0
]
},
{
"type": "end",
"arrival": "2026-11-02T08:27:15-05:00",
"arrival_epoch": 1793626035,
"distance_meters": 8356,
"duration_seconds": 1095,
"leg_distance_meters": 1793,
"leg_duration_seconds": 221,
"load": [
0
]
}
],
"stop_count": 4,
"task_count": 2,
"distance_meters": 8356,
"duration_seconds": 1095,
"service_seconds": 540,
"waiting_seconds": 0,
"geometry": null
},
{
"vehicle_id": "van-2",
"stops": [
{
"type": "start",
"arrival": "2026-11-02T08:56:13-05:00",
"arrival_epoch": 1793627773,
"distance_meters": 0,
"duration_seconds": 0,
"load": [
3
]
},
{
"type": "job",
"arrival": "2026-11-02T09:00:00-05:00",
"arrival_epoch": 1793628000,
"distance_meters": 1610,
"duration_seconds": 227,
"leg_distance_meters": 1610,
"leg_duration_seconds": 227,
"id": "order-1002",
"load": [
0
]
},
{
"type": "end",
"arrival": "2026-11-02T09:08:17-05:00",
"arrival_epoch": 1793628497,
"distance_meters": 3077,
"duration_seconds": 424,
"leg_distance_meters": 1467,
"leg_duration_seconds": 197,
"load": [
0
]
}
],
"stop_count": 3,
"task_count": 1,
"distance_meters": 3077,
"duration_seconds": 424,
"service_seconds": 300,
"waiting_seconds": 0,
"geometry": null
}
],
"unassigned": [],
"summary": {
"routes": 2,
"assigned": 3,
"unassigned": 0,
"distance_meters": 11433,
"duration_seconds": 1519
}
},
"meta": {
"engine": "sroute2",
"engine_version": "1.6.1",
"capacity_dimensions": [
"0"
]
}
}Example response when queued (202)
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "routing.refine",
"billing": {
"unit": "node",
"quantity": 5,
"counted": true,
"breakdown": {
"nodes": 5,
"jobs": 3,
"shipments": 0,
"shipment_nodes": 0,
"vehicles": 2,
"vehicle_nodes": 2,
"route_stops": 0
}
},
"data": {
"job": {
"id": "job_01k8zq4a6c8e0g2j4l6n8q0s2u",
"status": "queued",
"capability": "routing.refine",
"poll_after_ms": 1000,
"result_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/result",
"cancel_url": "/v1/jobs/job_01k8zq4a6c8e0g2j4l6n8q0s2u/cancel"
}
},
"meta": {
"mode": "async"
}
}Routing rules by engine
Which engine plans each optional routing rule, and from which engine version. A rule the chosen engine cannot plan is refused with VALIDATION_FAILED before anything is solved or billed; an approximated rule is accepted with a RULE_APPROXIMATED warning.
| Rule | Fields | sroute | sroute2 | sroute2t | sroute3 |
|---|---|---|---|---|---|
max_ride |
shipments.*.max_ride_seconds
constraints.max_ride_seconds
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
latest_departure |
vehicles.*.latest_departure_at
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
groups |
jobs.*.group
shipments.*.group
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
goods_classes |
constraints.incompatible_goods_classes
jobs.*.goods_class
shipments.*.goods_class
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
deliveries_before_pickups |
constraints.deliveries_before_pickups
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
waiting_cost |
constraints.waiting_cost
|
Not supported | Not supported | Native 1.0.19 or later | Native 1.0.0 or later |
use_all_vehicles |
constraints.use_all_vehicles
|
Not supported | Native | Native 1.0.19 or later | Native 1.0.0 or later |
merge_stops |
constraints.merge_stops
|
Not supported | Not supported | Not supported | Not supported |
reload |
constraints.reload
|
Not supported | Not supported | Native 1.0.20 or later | Native 1.0.0 or later |
loading_bays |
constraints.reload.depots.*.loading_bays
constraints.reload.slot_seconds
|
Not supported | Not supported | Native 1.0.20 or later | Native 1.0.0 or later |
ev_range |
vehicles.*.ev_range_meters
vehicles.*.ev_reserve_meters
|
Not supported | Native | Native 1.0.19 or later | Native 1.0.0 or later |
release |
jobs.*.release_at
|
Not supported | Not supported | Native 1.0.20 or later | Native 1.0.0 or later |
alternatives |
jobs.*.alternatives
|
Not supported | Not supported | Native 1.0.21 or later | Native 1.0.0 or later |
break_skip_policy |
vehicles.*.breaks.*.skip_policy
|
Not supported | Not supported | Native 1.0.21 or later | Native 1.0.0 or later |
break_places |
vehicles.*.breaks.*.places
|
Not supported | Not supported | Native 1.0.21 or later | Native 1.0.0 or later |
shifts |
vehicles.*.shifts
|
Not supported | Not supported | Not supported | Not supported |
What it costs
Every point the solver must visit or depart from, including each vehicle's start and end.
Every billable response carries a billing block with the unit, the quantity and how the quantity was derived.
Errors it can return
| Status | Code | Description |
|---|---|---|
| 401 | TOKEN_INVALID |
Unknown or revoked API token. |
| 401 | TOKEN_MISSING |
No API token. Send Authorization: Bearer <your token>. |
| 402 | QUOTA_EXHAUSTED |
The included allowance for this capability is used up for the current period. |
| 403 | CAPABILITY_NOT_ENABLED |
This capability is not enabled for your account. See :doc to enable it. |
| 403 | CAPABILITY_NOT_GRANTED_TO_KEY |
Your account has this capability, but this API key was not granted it. |
| 403 | ENGINE_NOT_ENABLED |
This routing engine is not enabled for your account. Omit `engine` or choose an engine that is. |
| 403 | OPEN_API_DISABLED |
Open Platform access is not enabled for this account. |
| 422 | CALLBACK_NOT_VERIFIED |
Verify the callback endpoint first: POST /v1/webhooks/verify and echo the challenge back. |
| 422 | CALLBACK_URL_UNSAFE |
The callback URL must be a public HTTPS endpoint. |
| 422 | SOLVE_INFEASIBLE |
No plan satisfies every constraint. Check time windows, capacities and skills. |
| 422 | UNSUPPORTED_REGION |
That routing region is not available. Use NA, EU, AU or ASIA. |
| 422 | VALIDATION_FAILED |
The request failed validation. See details. |
| 424 | ENGINE_REJECTED |
The routing engine refused this problem. Its reason is included where available. |
| 429 | CONCURRENCY_LIMIT |
Too many solves are already running for this account. Retry when one finishes. |
| 429 | RATE_LIMITED |
Too many requests. Please retry after the indicated delay. |
| 500 | INTERNAL_ERROR |
An unexpected error occurred. Quote the request_id when contacting support. |
| 502 | ENGINE_UNAVAILABLE |
The routing engine is temporarily unreachable. Please retry. |
| 504 | SOLVE_TIMEOUT |
The solve exceeded the synchronous budget. Send the same request with "mode":"async" and collect the result from the job. |