Stop insertion (beta)
Place new jobs in a plan you hold at the positions that cost least, without resequencing the rest.
routing.insert
Beta
node
How to call it
REST
POST
/v1/routing/insert
GraphQL
query
openRoutingInsert
MCP
open_routing_insert
Place new jobs in a plan you hold (vehicles, jobs, routes with ordered stop ids) at the positions that add the least time (or distance) while the plan keeps its time windows, capacity, skills and vehicle limits. Nothing else is resequenced. Returns each placement with alternatives and the updated routes. Billed per node.
Request schema
Generated from the same validation rules the endpoint runs, so a field cannot be documented without being validated.
POST /v1/routing/insert
{
"type": "object",
"properties": {
"alternatives": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 10
},
"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"
]
}
},
"nearest": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 200
},
"objective": {
"type": [
"string",
"null"
],
"enum": [
"duration",
"distance"
]
},
"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",
"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-11-02T08:00:00-05:00",
"vehicles": [
{
"id": "van-1",
"start": {
"lat": 45.5017,
"lng": -73.5673
},
"return_to_start": true,
"capacity": {
"parcels": 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": {
"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
},
"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": {
"parcels": 1
}
}
],
"routes": [
{
"vehicle_id": "van-1",
"stops": [
"order-1001",
"order-1002"
]
},
{
"vehicle_id": "van-2",
"stops": [
"order-1003"
]
}
],
"insert": [
{
"id": "order-1004",
"location": {
"lat": 45.5155,
"lng": -73.5605
},
"service_seconds": 300,
"amount": {
"parcels": 2
}
},
{
"id": "order-1005",
"location": {
"lat": 45.492,
"lng": -73.583
},
"service_seconds": 180,
"amount": {
"parcels": 9
}
}
]
}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/insert
Response schema
{
"description": "Each new job's position with alternatives, the jobs that fit nowhere, and the updated routes. Billed per node.",
"data": {
"type": "object",
"properties": {
"placements": {
"type": "array",
"description": "The jobs placed, in the order of `insert`.",
"items": {
"type": "object",
"properties": {
"job": {
"type": "string",
"description": "The job id."
},
"vehicle_id": {
"type": "string",
"description": "The vehicle whose route takes the job."
},
"position": {
"type": "integer",
"description": "The job's place in that route's stops, from 1."
},
"after": {
"type": [
"string",
"null"
],
"description": "The stop the job follows; null when it comes first."
},
"added_distance_meters": {
"type": "integer",
"description": "Distance the route gains."
},
"added_duration_seconds": {
"type": "integer",
"description": "Driving time the route gains."
},
"added_waiting_seconds": {
"type": "integer",
"description": "Waiting the route gains (negative when the job fills time spent waiting)."
},
"arrival": {
"type": [
"string",
"null"
],
"description": "Arrival at the job, ISO 8601."
},
"waiting_seconds": {
"type": "integer",
"description": "Waiting at the job before its window opens."
},
"service_start": {
"type": [
"string",
"null"
],
"description": "When work at the job begins: arrival plus waiting."
},
"violations": {
"type": "array",
"description": "What this position breaks. Present only on a position that is not acceptable (`closest`)."
},
"alternatives": {
"type": "array",
"description": "Other acceptable positions, best first.",
"items": {
"type": "object",
"properties": {
"vehicle_id": {
"type": "string",
"description": "The vehicle whose route takes the job."
},
"position": {
"type": "integer",
"description": "The job's place in that route's stops, from 1."
},
"after": {
"type": [
"string",
"null"
],
"description": "The stop the job follows; null when it comes first."
},
"added_distance_meters": {
"type": "integer",
"description": "Distance the route gains."
},
"added_duration_seconds": {
"type": "integer",
"description": "Driving time the route gains."
},
"added_waiting_seconds": {
"type": "integer",
"description": "Waiting the route gains (negative when the job fills time spent waiting)."
},
"arrival": {
"type": [
"string",
"null"
],
"description": "Arrival at the job, ISO 8601."
},
"waiting_seconds": {
"type": "integer",
"description": "Waiting at the job before its window opens."
},
"service_start": {
"type": [
"string",
"null"
],
"description": "When work at the job begins: arrival plus waiting."
},
"violations": {
"type": "array",
"description": "What this position breaks. Present only on a position that is not acceptable (`closest`)."
}
}
}
}
}
}
},
"unplaced": {
"type": "array",
"description": "Jobs with no acceptable position.",
"items": {
"type": "object",
"properties": {
"job": {
"type": "string",
"description": "The job id."
},
"reason": {
"type": "string",
"enum": [
"no_feasible_position",
"no_vehicle"
],
"description": "`no_feasible_position`: every tried position breaks a rule; `no_vehicle`: no position could be tried."
},
"closest": {
"type": [
"object",
"null"
],
"description": "The cheapest position tried, with its `violations`.",
"properties": {
"vehicle_id": {
"type": "string",
"description": "The vehicle whose route takes the job."
},
"position": {
"type": "integer",
"description": "The job's place in that route's stops, from 1."
},
"after": {
"type": [
"string",
"null"
],
"description": "The stop the job follows; null when it comes first."
},
"added_distance_meters": {
"type": "integer",
"description": "Distance the route gains."
},
"added_duration_seconds": {
"type": "integer",
"description": "Driving time the route gains."
},
"added_waiting_seconds": {
"type": "integer",
"description": "Waiting the route gains (negative when the job fills time spent waiting)."
},
"arrival": {
"type": [
"string",
"null"
],
"description": "Arrival at the job, ISO 8601."
},
"waiting_seconds": {
"type": "integer",
"description": "Waiting at the job before its window opens."
},
"service_start": {
"type": [
"string",
"null"
],
"description": "When work at the job begins: arrival plus waiting."
},
"violations": {
"type": "array",
"description": "What this position breaks. Present only on a position that is not acceptable (`closest`)."
}
}
}
}
}
},
"routes": {
"type": "array",
"description": "The routes with the jobs in place, priced as plan re-costing prices them (without geometry)."
},
"summary": {
"type": "object",
"properties": {
"inserted": {
"type": "integer",
"description": "Jobs placed."
},
"unplaced": {
"type": "integer",
"description": "Jobs not placed."
},
"added_distance_meters": {
"type": "integer",
"description": "Distance the plan gains."
},
"added_duration_seconds": {
"type": "integer",
"description": "Driving time the plan gains."
},
"violations": {
"type": "integer",
"description": "Rule violations in the updated routes (as many as before: a placement never adds one)."
}
}
}
},
"required": [
"placements",
"unplaced",
"routes",
"summary"
]
},
"meta": {
"type": "object",
"properties": {},
"additionalProperties": true
}
}Response example
{
"request_id": "req_01k8zq3m5n7p9r1t3v5x7z9b2d",
"capability": "routing.insert",
"billing": {
"unit": "node",
"quantity": 5,
"counted": true,
"breakdown": {
"planned_stops": 3,
"new_jobs": 2
}
},
"data": {
"placements": [
{
"job": "order-1004",
"vehicle_id": "van-1",
"position": 2,
"after": "order-1001",
"added_distance_meters": 1505,
"added_duration_seconds": 213,
"added_waiting_seconds": -513,
"arrival": "2026-11-02T08:11:57-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:11:57-05:00",
"alternatives": [
{
"vehicle_id": "van-1",
"position": 1,
"after": null,
"added_distance_meters": 2345,
"added_duration_seconds": 309,
"added_waiting_seconds": -609,
"arrival": "2026-11-02T08:04:31-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:04:31-05:00"
},
{
"vehicle_id": "van-2",
"position": 1,
"after": null,
"added_distance_meters": 849,
"added_duration_seconds": 127,
"added_waiting_seconds": 0,
"arrival": "2026-11-02T08:04:31-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:04:31-05:00"
},
{
"vehicle_id": "van-2",
"position": 2,
"after": "order-1003",
"added_distance_meters": 1402,
"added_duration_seconds": 211,
"added_waiting_seconds": 0,
"arrival": "2026-11-02T08:17:27-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:17:27-05:00"
}
]
},
{
"job": "order-1005",
"vehicle_id": "van-2",
"position": 2,
"after": "order-1003",
"added_distance_meters": 3080,
"added_duration_seconds": 357,
"added_waiting_seconds": 0,
"arrival": "2026-11-02T08:21:12-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:21:12-05:00",
"alternatives": [
{
"vehicle_id": "van-2",
"position": 1,
"after": null,
"added_distance_meters": 3495,
"added_duration_seconds": 431,
"added_waiting_seconds": 0,
"arrival": "2026-11-02T08:05:14-05:00",
"waiting_seconds": 0,
"service_start": "2026-11-02T08:05:14-05:00"
}
]
}
],
"unplaced": [],
"routes": [
{
"vehicle_id": "van-1",
"stop_count": 5,
"task_count": 3,
"distance_meters": 7921,
"duration_seconds": 1045,
"service_seconds": 900,
"waiting_seconds": 2152,
"departure": "2026-11-02T08:00:00-05:00",
"completion": "2026-11-02T09:08:17-05:00",
"unreachable_legs": 0,
"violations": [],
"violation_count": 0,
"stops": [
{
"type": "start",
"departure": "2026-11-02T08:00:00-05:00"
},
{
"type": "job",
"id": "order-1001",
"sequence": 1,
"reachable": true,
"leg_distance_meters": 1840,
"leg_duration_seconds": 245,
"leg_geometry": null,
"arrival": "2026-11-02T08:04:05-05:00",
"arrival_epoch": 1793624645,
"distance_meters": 1840,
"duration_seconds": 245
},
{
"type": "job",
"id": "order-1004",
"sequence": 2,
"reachable": true,
"leg_distance_meters": 1233,
"leg_duration_seconds": 172,
"leg_geometry": null,
"arrival": "2026-11-02T08:11:57-05:00",
"arrival_epoch": 1793625117,
"distance_meters": 3073,
"duration_seconds": 417
},
{
"type": "job",
"id": "order-1002",
"sequence": 3,
"reachable": true,
"leg_distance_meters": 3380,
"leg_duration_seconds": 431,
"leg_geometry": null,
"arrival": "2026-11-02T08:24:08-05:00",
"arrival_epoch": 1793625848,
"distance_meters": 6453,
"duration_seconds": 848,
"waiting_seconds": 2152
},
{
"type": "end",
"reachable": true,
"leg_distance_meters": 1468,
"leg_duration_seconds": 197,
"leg_geometry": null,
"arrival": "2026-11-02T09:08:17-05:00",
"arrival_epoch": 1793628497,
"distance_meters": 7921,
"duration_seconds": 1045
}
]
},
{
"vehicle_id": "van-2",
"stop_count": 4,
"task_count": 2,
"distance_meters": 10224,
"duration_seconds": 1273,
"service_seconds": 420,
"waiting_seconds": 0,
"departure": "2026-11-02T08:00:00-05:00",
"completion": "2026-11-02T08:28:13-05:00",
"unreachable_legs": 0,
"violations": [],
"violation_count": 0,
"stops": [
{
"type": "start",
"departure": "2026-11-02T08:00:00-05:00"
},
{
"type": "job",
"id": "order-1003",
"sequence": 1,
"reachable": true,
"leg_distance_meters": 3635,
"leg_duration_seconds": 482,
"leg_geometry": null,
"arrival": "2026-11-02T08:08:02-05:00",
"arrival_epoch": 1793624882,
"distance_meters": 3635,
"duration_seconds": 482
},
{
"type": "job",
"id": "order-1005",
"sequence": 2,
"reachable": true,
"leg_distance_meters": 4567,
"leg_duration_seconds": 550,
"leg_geometry": null,
"arrival": "2026-11-02T08:21:12-05:00",
"arrival_epoch": 1793625672,
"distance_meters": 8202,
"duration_seconds": 1032
},
{
"type": "end",
"reachable": true,
"leg_distance_meters": 2022,
"leg_duration_seconds": 241,
"leg_geometry": null,
"arrival": "2026-11-02T08:28:13-05:00",
"arrival_epoch": 1793626093,
"distance_meters": 10224,
"duration_seconds": 1273
}
]
}
],
"summary": {
"inserted": 2,
"unplaced": 0,
"added_distance_meters": 4585,
"added_duration_seconds": 570,
"violations": 0
}
},
"meta": {
"region": "NA",
"profile": "car",
"objective": "duration",
"nearest": 25,
"legs_measured": 23
}
}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. |