Job insertion (beta)

Place new jobs in a plan you hold at their cheapest positions, without re-planning the rest, and receive the plan priced with the positions to choose from.

plan.insert Beta node

How to call it

Request schema

Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.

POST /v1/plan/insert

{
    "type": "object",
    "properties": {
        "departed_at": [],
        "insert": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": [
                            "array",
                            "null"
                        ]
                    },
                    "id": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "location": {
                        "type": "object",
                        "properties": {
                            "lat": {
                                "type": "number",
                                "minimum": -90,
                                "maximum": 90
                            },
                            "lng": {
                                "type": "number",
                                "minimum": -180,
                                "maximum": 180
                            }
                        },
                        "required": [
                            "lat",
                            "lng"
                        ]
                    },
                    "service_seconds": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "minimum": 0
                    },
                    "skills": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 64
                        }
                    },
                    "time_windows": {
                        "type": [
                            "array",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "location"
                ]
            }
        },
        "jobs": {
            "type": "array",
            "maxItems": 2000,
            "items": {
                "type": "object",
                "properties": {
                    "amount": {
                        "type": [
                            "array",
                            "null"
                        ]
                    },
                    "id": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "location": {
                        "type": "array"
                    },
                    "service_seconds": {
                        "type": [
                            "integer",
                            "null"
                        ],
                        "minimum": 0
                    },
                    "skills": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 64
                        }
                    },
                    "time_windows": {
                        "type": [
                            "array",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "location"
                ]
            }
        },
        "limit": {
            "type": [
                "integer",
                "null"
            ],
            "minimum": 1,
            "maximum": 10
        },
        "matrix": {
            "type": [
                "string",
                "null"
            ],
            "maxLength": 200
        },
        "nearest": {
            "type": [
                "integer",
                "null"
            ],
            "minimum": 1,
            "maximum": 50
        },
        "objective": {
            "type": [
                "string",
                "null"
            ],
            "enum": [
                "duration",
                "distance"
            ]
        },
        "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"
            ]
        },
        "routes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
                "type": "object",
                "properties": {
                    "reverse": {
                        "type": [
                            "boolean",
                            "null"
                        ]
                    },
                    "stops": {
                        "type": "array",
                        "maxItems": 2000,
                        "items": {
                            "type": "string",
                            "maxLength": 128
                        }
                    },
                    "vehicle_id": {
                        "type": "string",
                        "maxLength": 128
                    }
                },
                "required": [
                    "vehicle_id"
                ]
            }
        },
        "vehicles": {
            "type": "array",
            "minItems": 1,
            "maxItems": 200,
            "items": {
                "type": "object",
                "properties": {
                    "capacity": {
                        "type": [
                            "array",
                            "null"
                        ]
                    },
                    "end": {
                        "type": [
                            "array",
                            "null"
                        ]
                    },
                    "id": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "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"
                        ]
                    },
                    "skills": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 64
                        }
                    },
                    "start": {
                        "type": [
                            "array",
                            "null"
                        ]
                    },
                    "time_window": {
                        "type": [
                            "array",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id"
                ]
            }
        }
    },
    "additionalProperties": false,
    "required": [
        "insert",
        "jobs",
        "routes",
        "vehicles"
    ]
}

Request example

{
    "departed_at": "2026-10-23T09:30:00-04:00",
    "vehicles": [
        {
            "id": "van-1",
            "start": {
                "lat": 45.5017,
                "lng": -73.5673
            },
            "return_to_start": true,
            "capacity": {
                "parcels": 10
            }
        },
        {
            "id": "van-2",
            "start": {
                "lat": 45.5017,
                "lng": -73.5673
            },
            "return_to_start": true,
            "capacity": {
                "parcels": 10
            }
        }
    ],
    "jobs": [
        {
            "id": "order-1001",
            "location": {
                "lat": 45.5088,
                "lng": -73.554
            },
            "service_seconds": 300,
            "amount": {
                "parcels": 2
            }
        },
        {
            "id": "order-1002",
            "location": {
                "lat": 45.4972,
                "lng": -73.5786
            },
            "service_seconds": 300,
            "amount": {
                "parcels": 3
            }
        },
        {
            "id": "order-1003",
            "location": {
                "lat": 45.5231,
                "lng": -73.5817
            },
            "service_seconds": 300,
            "amount": {
                "parcels": 1
            }
        },
        {
            "id": "order-1004",
            "location": {
                "lat": 45.5302,
                "lng": -73.6125
            },
            "service_seconds": 300,
            "amount": {
                "parcels": 2
            }
        }
    ],
    "routes": [
        {
            "vehicle_id": "van-1",
            "stops": [
                "order-1001",
                "order-1002",
                "order-1003"
            ]
        }
    ],
    "options": {
        "geometry": false
    },
    "matrix": "tile2.3f0c9a5e7b1d4c2a9e8f6d5c4b3a2910",
    "insert": [
        {
            "id": "order-1005",
            "location": {
                "lat": 45.5149,
                "lng": -73.5734
            },
            "service_seconds": 300,
            "amount": {
                "parcels": 1
            }
        }
    ],
    "limit": 2
}

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/plan/insert

Response schema

{
    "description": "The plan with the new jobs placed, priced and judged as plan re-costing prices it, the plan itself in `plan`, and per new job the positions found, each measured on the road.",
    "data": {
        "type": "object",
        "properties": {
            "routes": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "vehicle_id": {
                            "type": "string"
                        },
                        "stop_count": {
                            "type": "integer",
                            "description": "Stops including start and end."
                        },
                        "task_count": {
                            "type": "integer",
                            "description": "Jobs on the route."
                        },
                        "distance_meters": {
                            "type": "integer"
                        },
                        "duration_seconds": {
                            "type": "integer",
                            "description": "Driving time."
                        },
                        "service_seconds": {
                            "type": "integer"
                        },
                        "waiting_seconds": {
                            "type": "integer"
                        },
                        "departure": {
                            "type": "string",
                            "description": "ISO 8601 with offset."
                        },
                        "completion": {
                            "type": "string",
                            "description": "When the last stop (or the end) is reached. ISO 8601 with offset."
                        },
                        "unreachable_legs": {
                            "type": "integer"
                        },
                        "violations": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "description": "A route-level breach. Which fields are present depends on `rule`.",
                                "properties": {
                                    "rule": {
                                        "type": "string",
                                        "enum": [
                                            "capacity",
                                            "max_tasks",
                                            "max_distance",
                                            "max_travel_time",
                                            "vehicle_time_window"
                                        ]
                                    },
                                    "message": {
                                        "type": "string"
                                    },
                                    "dimension": {
                                        "type": "string",
                                        "description": "capacity: the capacity dimension that overflows."
                                    },
                                    "load": {
                                        "type": "number",
                                        "description": "capacity: what the stops load."
                                    },
                                    "capacity": {
                                        "type": "number",
                                        "description": "capacity: what the vehicle carries."
                                    },
                                    "tasks": {
                                        "type": "integer",
                                        "description": "max_tasks: stops on the route."
                                    },
                                    "distance_meters": {
                                        "type": "integer",
                                        "description": "max_distance: distance of the route."
                                    },
                                    "duration_seconds": {
                                        "type": "integer",
                                        "description": "max_travel_time: driving time of the route."
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "description": "max_tasks, max_distance, max_travel_time: the vehicle's limit."
                                    },
                                    "late_seconds": {
                                        "type": "integer",
                                        "description": "vehicle_time_window: how far past the working window the route ends."
                                    },
                                    "window_end": {
                                        "type": "string",
                                        "description": "vehicle_time_window: when the working window ends. ISO 8601 with offset."
                                    }
                                }
                            },
                            "description": "Route-level breaches."
                        },
                        "violation_count": {
                            "type": "integer",
                            "description": "Route and stop breaches on this route."
                        },
                        "stops": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "type": {
                                        "type": "string",
                                        "enum": [
                                            "start",
                                            "job",
                                            "end"
                                        ]
                                    },
                                    "id": {
                                        "type": "string",
                                        "description": "The caller's job id. Jobs only."
                                    },
                                    "sequence": {
                                        "type": "integer",
                                        "description": "Position of the job on the route, from 1."
                                    },
                                    "reachable": {
                                        "type": "boolean",
                                        "description": "Whether the hop into this stop could be routed. An unreachable hop has no distance or time and is counted in `unreachable_legs`."
                                    },
                                    "departure": {
                                        "type": "string",
                                        "description": "Start only: when the vehicle leaves. ISO 8601 with offset."
                                    },
                                    "waiting_seconds": {
                                        "type": "integer",
                                        "description": "Start only, when the vehicle must wait for its working window to open."
                                    },
                                    "arrival": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "description": "ISO 8601 with offset. Null after an unreachable hop."
                                    },
                                    "arrival_epoch": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "description": "`arrival` as Unix seconds."
                                    },
                                    "leg_distance_meters": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "description": "Distance of the hop into this stop."
                                    },
                                    "leg_duration_seconds": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "description": "Driving time of the hop into this stop."
                                    },
                                    "leg_geometry": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "description": "Encoded polyline (precision 5) of the hop into this stop. Present when `options.geometry` is true (the default)."
                                    },
                                    "distance_meters": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "description": "Cumulative distance from the start."
                                    },
                                    "duration_seconds": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "description": "Cumulative driving time from the start."
                                    },
                                    "violations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "rule": {
                                                    "type": "string",
                                                    "enum": [
                                                        "skills",
                                                        "time_window"
                                                    ]
                                                },
                                                "message": {
                                                    "type": "string"
                                                },
                                                "missing": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    },
                                                    "description": "skills: the skills the vehicle lacks."
                                                },
                                                "late_seconds": {
                                                    "type": "integer",
                                                    "description": "time_window: how late the arrival is."
                                                },
                                                "window": {
                                                    "type": "object",
                                                    "description": "time_window: the window that was missed.",
                                                    "properties": {
                                                        "from": {
                                                            "type": "string",
                                                            "description": "ISO 8601 with offset."
                                                        },
                                                        "to": {
                                                            "type": "string",
                                                            "description": "ISO 8601 with offset."
                                                        }
                                                    }
                                                }
                                            }
                                        },
                                        "description": "Constraints this stop breaks. Present only when it breaks one."
                                    }
                                },
                                "required": [
                                    "type"
                                ]
                            }
                        }
                    }
                },
                "description": "The edited plan's routes priced and judged exactly as plan re-costing prices them."
            },
            "summary": {
                "type": "object",
                "properties": {
                    "routes": {
                        "type": "integer"
                    },
                    "tasks": {
                        "type": "integer",
                        "description": "Jobs across all routes."
                    },
                    "distance_meters": {
                        "type": "integer"
                    },
                    "duration_seconds": {
                        "type": "integer",
                        "description": "Driving time across all routes."
                    },
                    "unreachable_legs": {
                        "type": "integer",
                        "description": "Hops that could not be routed."
                    },
                    "violations": {
                        "type": "integer",
                        "description": "Breaches across all routes and stops."
                    }
                }
            },
            "plan": {
                "type": "object",
                "description": "The edited plan in the shape it is sent: put it in place of your own. Routes keep your order; a vehicle that received its first stops is added last. Stops are in driving order, so a route sent with `reverse` comes back already reversed.",
                "properties": {
                    "routes": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "vehicle_id": {
                                    "type": "string"
                                },
                                "stops": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    }
                                }
                            },
                            "required": [
                                "vehicle_id",
                                "stops"
                            ]
                        }
                    },
                    "unassigned": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Every job of the plan that is on no route."
                    }
                },
                "required": [
                    "routes",
                    "unassigned"
                ]
            },
            "insert": {
                "type": "array",
                "description": "One entry per new job, in the order placed.",
                "items": {
                    "type": "object",
                    "properties": {
                        "job": {
                            "type": "string"
                        },
                        "placed": {
                            "type": "boolean",
                            "description": "Whether the job was placed; a job no position can take stays in `plan.unassigned`."
                        },
                        "reason": {
                            "type": "string",
                            "enum": [
                                "no_vehicle",
                                "no_feasible_position"
                            ],
                            "description": "Why the job was not placed. Present only when `placed` is false."
                        },
                        "choices": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "feasible": {
                                        "type": "boolean",
                                        "description": "Whether the plan keeps every stated rule with the job here."
                                    },
                                    "vehicle_id": {
                                        "type": "string"
                                    },
                                    "position": {
                                        "type": "integer",
                                        "description": "Where the job goes in the route, from 1, in driving order."
                                    },
                                    "after": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "description": "The stop the job follows; null right after the start."
                                    },
                                    "added_distance_meters": {
                                        "type": "integer",
                                        "description": "Distance the route gains, measured on the road."
                                    },
                                    "added_duration_seconds": {
                                        "type": "integer",
                                        "description": "Driving time the route gains."
                                    },
                                    "added_waiting_seconds": {
                                        "type": "integer",
                                        "description": "Waiting time the route gains."
                                    },
                                    "arrival": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "description": "When the job is reached. ISO 8601 with offset."
                                    },
                                    "waiting_seconds": {
                                        "type": "integer",
                                        "description": "Waiting at the job before its time window opens."
                                    },
                                    "service_start": {
                                        "type": [
                                            "string",
                                            "null"
                                        ],
                                        "description": "When work at the job begins: arrival plus waiting. ISO 8601 with offset."
                                    },
                                    "violations": {
                                        "type": "array",
                                        "items": {
                                            "type": "object"
                                        },
                                        "description": "What the plan breaks with the job here. Present only when `feasible` is false."
                                    }
                                },
                                "required": [
                                    "feasible",
                                    "vehicle_id",
                                    "position",
                                    "added_distance_meters",
                                    "added_duration_seconds"
                                ]
                            },
                            "description": "Up to `limit` positions, best first: the first is where the job was placed."
                        }
                    },
                    "required": [
                        "job",
                        "placed",
                        "choices"
                    ]
                }
            }
        },
        "required": [
            "routes",
            "summary",
            "plan",
            "insert"
        ]
    },
    "meta": {
        "type": "object",
        "properties": {
            "region": {
                "type": "string",
                "description": "The engine region used."
            },
            "profile": {
                "type": "string",
                "description": "The vehicle profile used."
            },
            "geometry": {
                "type": "boolean",
                "description": "Whether leg geometry was returned."
            },
            "geometry_format": {
                "type": [
                    "string",
                    "null"
                ],
                "description": "`polyline` when geometry was returned."
            },
            "departed_at": {
                "type": "string",
                "description": "The departure time the plan was timed from: `departed_at`, else the current time. ISO 8601 with offset."
            },
            "objective": {
                "type": "string",
                "description": "`duration` or `distance`."
            },
            "limit": {
                "type": "integer",
                "description": "Choices returned per job."
            }
        },
        "additionalProperties": true
    }
}

Response example

{
    "request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
    "capability": "plan.insert",
    "billing": {
        "unit": "node",
        "quantity": 4,
        "counted": true,
        "breakdown": {
            "planned_stops": 3,
            "new_jobs": 1
        }
    },
    "data": {
        "routes": [
            {
                "vehicle_id": "van-1",
                "stop_count": 6,
                "task_count": 4,
                "distance_meters": 12865,
                "duration_seconds": 1664,
                "service_seconds": 1200,
                "waiting_seconds": 0,
                "departure": "2026-10-23T09:30:00-04:00",
                "completion": "2026-10-23T10:17:44-04:00",
                "unreachable_legs": 0,
                "violations": [],
                "violation_count": 0,
                "stops": [
                    {
                        "type": "start",
                        "departure": "2026-10-23T09:30:00-04:00"
                    },
                    {
                        "type": "job",
                        "id": "order-1001",
                        "sequence": 1,
                        "reachable": true,
                        "leg_distance_meters": 1840,
                        "leg_duration_seconds": 245,
                        "leg_geometry": null,
                        "arrival": "2026-10-23T09:34:05-04:00",
                        "arrival_epoch": 1792762445,
                        "distance_meters": 1840,
                        "duration_seconds": 245
                    },
                    {
                        "type": "job",
                        "id": "order-1002",
                        "sequence": 2,
                        "reachable": true,
                        "leg_distance_meters": 3108,
                        "leg_duration_seconds": 390,
                        "leg_geometry": null,
                        "arrival": "2026-10-23T09:45:35-04:00",
                        "arrival_epoch": 1792763135,
                        "distance_meters": 4948,
                        "duration_seconds": 635
                    },
                    {
                        "type": "job",
                        "id": "order-1003",
                        "sequence": 3,
                        "reachable": true,
                        "leg_distance_meters": 4326,
                        "leg_duration_seconds": 551,
                        "leg_geometry": null,
                        "arrival": "2026-10-23T09:59:46-04:00",
                        "arrival_epoch": 1792763986,
                        "distance_meters": 9274,
                        "duration_seconds": 1186
                    },
                    {
                        "type": "job",
                        "id": "order-1005",
                        "sequence": 4,
                        "reachable": true,
                        "leg_distance_meters": 1512,
                        "leg_duration_seconds": 218,
                        "leg_geometry": null,
                        "arrival": "2026-10-23T10:08:24-04:00",
                        "arrival_epoch": 1792764504,
                        "distance_meters": 10786,
                        "duration_seconds": 1404
                    },
                    {
                        "type": "end",
                        "reachable": true,
                        "leg_distance_meters": 2079,
                        "leg_duration_seconds": 260,
                        "leg_geometry": null,
                        "arrival": "2026-10-23T10:17:44-04:00",
                        "arrival_epoch": 1792765064,
                        "distance_meters": 12865,
                        "duration_seconds": 1664
                    }
                ]
            }
        ],
        "summary": {
            "routes": 1,
            "tasks": 4,
            "distance_meters": 12865,
            "duration_seconds": 1664,
            "unreachable_legs": 0,
            "violations": 0
        },
        "plan": {
            "routes": [
                {
                    "vehicle_id": "van-1",
                    "stops": [
                        "order-1001",
                        "order-1002",
                        "order-1003",
                        "order-1005"
                    ]
                }
            ],
            "unassigned": [
                "order-1004"
            ]
        },
        "insert": [
            {
                "job": "order-1005",
                "placed": true,
                "choices": [
                    {
                        "feasible": true,
                        "vehicle_id": "van-1",
                        "position": 4,
                        "after": "order-1003",
                        "added_distance_meters": 82,
                        "added_duration_seconds": 44,
                        "added_waiting_seconds": 0,
                        "arrival": "2026-10-23T10:08:24-04:00",
                        "waiting_seconds": 0,
                        "service_start": "2026-10-23T10:08:24-04:00"
                    },
                    {
                        "feasible": true,
                        "vehicle_id": "van-1",
                        "position": 3,
                        "after": "order-1002",
                        "added_distance_meters": 766,
                        "added_duration_seconds": 118,
                        "added_waiting_seconds": 0,
                        "arrival": "2026-10-23T09:56:57-04:00",
                        "waiting_seconds": 0,
                        "service_start": "2026-10-23T09:56:57-04:00"
                    }
                ]
            }
        ]
    },
    "meta": {
        "region": "NA",
        "profile": "car",
        "geometry": false,
        "geometry_format": null,
        "departed_at": "2026-10-23T09:30:00-04:00",
        "objective": "duration",
        "limit": 2,
        "mode": "sync"
    }
}

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