Route building
Kairos Graph
A generic solver for tours on graphs: visits and shipments are distributed across agents and the order is set for each agent. Capacities, skills, time windows, breaks and per-tour limits are taken into account.
A backend, not a finished solution
The service is deliberately abstract. It knows nodes, edges, agents and visits. Vehicles, drivers, parcels, coordinates, road networks and navigation do not appear. All numbers are unitless: you decide whether cost means euros or metres and whether time is counted in seconds or minutes. Duration, time windows and service duration must use the same time unit. There are no dates; time starts at 0.
Not covered: coordinates and geocoding, road networks, traffic, domain models such as driving and rest times, multi-day planning, live re-planning and asynchronous jobs. You supply the cost matrices yourself, also from another service.
Pricing
Intake fee per graph solve
Once per request. An invalid request (400) costs nothing.
- + per started solver second300Credits
Synchronous call and time limit
The request is answered synchronously: the connection stays open until the solution is ready. Set your client timeout longer than time_limit_seconds. Runs of up to 60 seconds are recommended. time_limit_seconds is an upper bound: the search ends earlier as soon as the solution stops improving. The response never arrives later than the limit.
/v1/kairos/graphBuilds tours on a graph. The call is synchronous and returns routes with times, loads and costs.
Parameter
graphGraphYesNodes and costs: either matrices per profile or edges — see the Graph section.
taskTaskYesTask of type tours: agents, visits, shipments, objective — see the Task section.
configConfigOptionalDefault:{}Time limit, early stopping, correlation ID, result offloading — see the Config section.
Request
curl -X POST "https://api.centra.dbpg.io/v1/kairos/graph" \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"graph": {
"nodes": [{ "id": "depot" }, { "id": "a" }, { "id": "b" }],
"matrices": {
"default": {
"cost": [[0, 10, 15], [10, 0, 6], [15, 6, 0]],
"duration": [[0, 600, 900], [600, 0, 300], [900, 300, 0]]
}
}
},
"task": {
"type": "tours",
"agents": [
{ "id": "agent-1", "start": "depot", "end": "depot", "capacity": [10] }
],
"visits": [
{ "id": "v1", "node": "a", "demand": [4], "service_duration": 300 },
{ "id": "v2", "node": "b", "demand": [3], "service_duration": 300 }
]
},
"config": { "time_limit_seconds": 30, "request_id": "example-1" }
}'Response
{
"status": "optimal",
"request_id": "example-1",
"result_url": "https://…/graph/3f2c9a0e8b7d4c1e9a6b5d4c3b2a1f0e.json?X-Amz-Signature=…",
"result_expires_at": "2026-10-29T19:00:00+00:00",
"totals": { "cost": 31, "penalties": 0, "objective": 31 },
"statistics": { "timing": { "total_seconds": 0.05, "solve_seconds": 0.04, "billable_seconds": 0.05, "stop_reason": "completed" } },
"warnings": [],
"diagnostics": null,
"errors": [],
"_meta": { "lambda_total_seconds": 0.06 },
"usage": {
"credits_used": 2300,
"remaining_balance": 7700
}
}Graph
Provide exactly one of matrices or edges, otherwise the service answers with 400. A graph can carry several cost sets (profiles), for example for heavy and light agents; each agent refers to one with profile. At most 8 profiles.
graph
Parameter
nodesarray<{ id, … }>YesNodes as objects with a unique id. Further attributes are allowed and ignored.
directedbooleanOptionalDefault:trueOnly with edges: false means every edge applies in both directions.
matricesobject<profile, MatrixProfile>AlternativeProfile name → matrices. Alternative to edges.
edgesarray<Edge>AlternativeList of edges. Alternative to matrices.
Form 1: matrices
One square cost matrix per profile, in the order of nodes. null means unreachable; asymmetry is allowed.
Parameter
costarray<array<number | null>>YesSquare cost matrix, values ≥ 0, null = unreachable.
durationarray<array<number | null>>OptionalSquare duration matrix of the same shape. Optional.
"matrices": {
"default": { "cost": [[0, 12.5, 9], [12, 0, 4], [9, 4.2, 0]],
"duration": [[0, 600, 450], [600, 0, 200], [450, 200, 0]] },
"heavy": { "cost": [[…]], "duration": [[…]] }
}Form 2: edges
The service computes the shortest paths per profile between all nodes used in agents, visits and shipments. Cost decides; duration is summed along the same path. The output additionally contains path for each stop.
Parameter
fromstringYesNode ID of the start.
tostringYesNode ID of the end.
costnumber ≥ 0YesCost for the default profile, ≥ 0.
durationnumber ≥ 0 | nullOptionalDuration for the default profile.
by_profileobject<profile, { cost, duration } | null>OptionalOverrides cost and duration per profile. cost: null or the whole entry null blocks the edge for that profile.
"edges": [
{ "from": "depot", "to": "a", "cost": 12.5, "duration": 600,
"by_profile": { "heavy": { "cost": 20, "duration": 900 }, "bike": null } }
]If the profile of an agent has no duration, time conditions for that agent (time_window, breaks, break_rule, max_duration) and minimize: max_route_duration are invalid. Time windows of visits and shipments require a duration in all profiles.
Task
The current and only task type is tours. At least one visit or shipment is required. IDs of visits and shipments are unique together, as are agent IDs.
task
total_cost: sum of edge costs × cost_factor, fixed costs and penalties of dropped jobs. max_route_duration: weighted objective balance_weight × longest tour duration + total_cost; totals.objective reports exactly this value.
Parameter
type"tours"YesAlways tours.
agentsarray<Agent> (1–200)YesAgents, 1 to 200.
visitsarray<Visit>OptionalDefault:[]Single visits.
shipmentsarray<Shipment>OptionalDefault:[]Pickup and delivery.
minimize"total_cost" | "max_route_duration"OptionalDefault:"total_cost"total_cost or max_route_duration.
balance_weightnumberOptionalDefault:100Only with max_route_duration: weight of the longest tour duration. 0 or ≥ 1.
Agent (agents[])
An agent drives one tour from start to end. Fixed breaks (breaks) start in one of their windows and are mandatory; if one cannot be scheduled, the agent cannot be used in that form.
Parameter
idstringYesUnique ID.
profilestringOptionalDefault:"default"Cost set of the graph; must exist.
startstringYesNode ID of the start.
endstring | nullYesNode ID of the end, or null for an open end. The key must be present.
capacityarray<number ≥ 0> | nullOptionalDefault:nullCapacity vector, same length as demand and amount of all visits and shipments. null = no limit.
skillsarray<string>OptionalDefault:[]Skills, freely assigned.
time_window[from, to] | nullOptionalDefault:nullWorking window [from, to].
breaksarray<Break>OptionalDefault:[]Fixed breaks: id, time_windows (at least one window, inside time_window) and duration.
break_rule{ max_continuous, duration } | nullOptionalDefault:nullBreak pattern with max_continuous and duration — see the Break pattern section.
max_durationnumber ≥ 0 | nullOptionalDefault:nullUpper limit of tour duration.
max_costnumber ≥ 0 | nullOptionalDefault:nullUpper limit of tour cost.
fixed_costnumber ≥ 0OptionalDefault:0Applies as soon as the agent has at least one stop.
cost_factornumber (> 0, ≤ 1000)OptionalDefault:1Multiplier on this agent's edge costs, > 0 and at most 1000.
{
"id": "agent-1", "profile": "default",
"start": "depot", "end": "depot",
"capacity": [100, 8], "skills": ["cooling"],
"time_window": [0, 28800],
"breaks": [{ "id": "lunch", "time_windows": [[14400, 18000]], "duration": 1800 }],
"break_rule": { "max_continuous": 16200, "duration": 2700 },
"fixed_cost": 0, "cost_factor": 1
}Visit (visits[])
A visit is served by exactly one agent. Several visits at the same node are allowed.
Parameter
idstringYesUnique ID.
nodestringYesNode ID.
demandarray<number ≥ 0> | nullOptionalDefault:nullOccupies capacity from the visit to the end of the tour.
skillsarray<string>OptionalDefault:[]The agent needs all of them. Empty = any agent.
time_windowsarray<[from, to]>OptionalDefault:[]Service must start inside a window. Empty = no window.
service_durationnumber ≥ 0OptionalDefault:0Service duration.
penaltynumber ≥ 0 | nullOptionalDefault:nullnull = mandatory visit. A number allows dropping the visit at that penalty.
{ "id": "v1", "node": "a", "demand": [10, 1], "skills": [],
"time_windows": [[3600, 7200], [14400, 18000]],
"service_duration": 300, "penalty": null }Shipment (shipments[])
The same agent handles pickup (first) and delivery. amount occupies capacity from pickup to delivery. A shipment is always dropped as a whole.
Parameter
idstringYesUnique ID.
amountarray<number ≥ 0> | nullOptionalDefault:nullOccupies capacity from pickup to delivery.
skillsarray<string>OptionalDefault:[]The agent needs all of them.
pickup{ node, time_windows, service_duration }YesPickup: node (required), time_windows, service_duration.
delivery{ node, time_windows, service_duration }YesDelivery: node (required), time_windows, service_duration.
penaltynumber ≥ 0 | nullOptionalDefault:nullnull = mandatory shipment, otherwise the penalty for dropping it.
{ "id": "s1", "amount": [5, 1], "skills": ["cooling"],
"pickup": { "node": "a", "time_windows": [[0, 7200]], "service_duration": 120 },
"delivery": { "node": "b", "time_windows": [[3600, 14400]], "service_duration": 120 },
"penalty": null }Time windows
Each window is [from, to] with 0 ≤ from ≤ to. Windows of one field must be sorted by start and must not overlap. Waiting before the start of a window is allowed.
Config
All fields are optional.
config
The time limit is an upper bound for the whole run: input check, matrix build, precheck, model build, search and verification. The run usually ends earlier, as soon as the solution has stopped improving for a while (early stop). The stall window is a quarter of the search time so far, at least 1 and at most 10 seconds; for larger problems it tends to be longer. Small problems therefore end after about one second. Only the seconds actually used are billed.
Parameter
time_limit_secondsnumber (1–600)OptionalDefault:60Upper bound of the whole run in seconds, as a number (a string such as "600" results in 400). Rounded up to whole seconds and capped to 1 to 600. The run usually ends earlier (early stop on stall) and is billed only for the seconds used; the value determines the reserve that is booked up front.
min_search_secondsnumber (0–time_limit_seconds)OptionalDefault:0Minimum search time in seconds, counted from receipt of the request, as a number from 0 to time_limit_seconds. Until then the search does not stop because of a stall. This is not a minimum run time: the search still ends at the time limit, and if min_search_seconds is close to it, the run is shorter than min_search_seconds. It also ends earlier if the search finishes by itself or proves unsolvability. A value above time_limit_seconds results in 400 (status invalid, error at config.min_search_seconds). Has no effect with stop_after_first_solution. A longer search increases the billed seconds.
stop_after_first_solutionbooleanOptionalDefault:falseReturn the first valid solution without improving it.
request_idstring | nullOptionalDefault:nullCorrelation ID; mirrored in the response.
offload_resultbooleanOptionalDefault:trueAlways true: for optimal and feasible the result sits behind result_url, see the Large results section. Any other value is overwritten.
result_url_expires_ininteger (60–604800)OptionalDefault:10800Desired validity of result_url in seconds. Effectively at most about 24 hours, see the Large results section.
From about 400 stops, choose a longer time_limit_seconds (up to 300). The solutions are valid, but with tight time windows they are not always close to the optimum. To use the full search time, set min_search_seconds.
Response
The response contains one route per agent used. All numbers are in your units.
Status values
All responses with a run are billed on billable_seconds; invalid costs nothing.
| status | HTTP | Billed | Meaning |
|---|---|---|---|
optimal | 200 | yes | Optimality proven. This only happens for very small problems. |
feasible | 200 | yes | Solution found, all hard conditions are met. The normal case at realistic sizes and a full result. |
infeasible | 200 | intake only | The precheck or the search proves that no solution exists. Reasons are in warnings and diagnostics.reasons. |
unknown | 200 | yes | No complete solution was found before the stall or the time limit. This does not mean none exists. |
invalid | 400 | no | The input is inconsistent, for example an unknown node. Details in errors[]. |
A mandatory job (penalty: null) never appears in dropped. If the search leaves one out, the answer is unknown.
Response fields
Parameter
status"optimal" | "feasible" | "infeasible" | "unknown" | "invalid"YesPlanning result, see status values.
request_idstring | nullOptionalMirror of config.request_id.
result_urlstringOptionalFor optimal and feasible: signed URL of the file with the full response (routes, dropped, unused_agents).
result_expires_atstring (ISO 8601)OptionalFor optimal and feasible: expiry time of result_url.
routesarray<Route>OptionalFor infeasible and unknown in the response itself; for optimal and feasible in the file behind result_url. One route per agent used, in the order of the agents in the request.
unused_agentsarray<string>OptionalIDs of agents without a stop. No fixed costs apply to them. For optimal and feasible in the file behind result_url.
droppedarray<{ type, id, penalty }>OptionalDropped optional jobs with type, id and penalty. For optimal and feasible in the file behind result_url.
totals{ cost, penalties, objective }Yescost (sum of route costs), penalties (sum of penalties) and objective (objective value).
statistics{ timing }Yestiming.total_seconds, timing.solve_seconds, timing.billable_seconds (basis of billing) and timing.stop_reason (why the run ended, see section Stop reason).
warningsarray<string>YesNotes in German; for infeasible, the reasons.
diagnostics{ stage, reasons } | nullYesFor infeasible: stage (precheck or solve) and reasons[], otherwise null.
errorsarray<{ field, message }>YesFor invalid: list of field and message, all errors at once.
usage{ credits_used, remaining_balance }Yescredits_used and remaining_balance.
Stop reason (statistics.timing.stop_reason)
The field states why the run ended.
stallEarly stop: the solution did not improve within the stall window. unknown can end this way too: the search found no better solution for at least 10 seconds, and no solution found serves all mandatory jobs.completedThe search finished by itself, before the time limit and without a stall window.time_limitThe search ran until the time limit. This also applies to unknown without a stall when no complete solution was found in time.first_solutionstop_after_first_solution was set: the first solution was returned.infeasibleThe search proved unsolvability (diagnostics.stage solve).precheckThe precheck detected unsolvability. No search ran (billable_seconds 0).invalidThe input is invalid. No search ran (billable_seconds 0).
Route and stop
Each route has agent, stops[], breaks[], cost and duration (null if the profile has no duration). A stop has type (start, visit, pickup, delivery or end), id (not for start and end), node, arrival, departure and load (occupied capacity after the stop). In edges mode, path additionally lists the intermediate nodes since the previous stop.
Billing
The price consists of the intake fee and the solver seconds.
- 2,000 + 300 × time_limit_seconds credits are booked up front as a reserve, the worst case. If the balance is too low, the service answers 402 before any work is done.
- After the response, 2,000 + 300 × rounded-up statistics.timing.billable_seconds credits stay charged, and the unused part of the reserve is refunded. The actual run time is billed, never more than the reserve.
- If the search ends through the early stop (stop_reason stall), this is often only a few seconds, even with time_limit_seconds 60. min_search_seconds extends the search and thereby increases the billed seconds.
- If the precheck detects an unsolvable request (infeasible with diagnostics.stage precheck), no search runs: only the intake fee applies.
- An invalid request (400) costs nothing.
- On service errors (5xx, timeout) everything is refunded.
- An unsolvable request that the precheck does not detect (for example too few agents for all mandatory visits) ends with unknown as soon as the search has found no better solution for 10 seconds, at the latest at the time limit. It is billed for the seconds used because the search does not prove unsolvability; measured runs took about 20 to 30 seconds with time_limit_seconds 60. For plausibility checks, choose a small time_limit_seconds.
What the precheck detects
Necessary conditions only: missing skills, demand above the capacity of every capable agent or of the whole fleet, time windows outside all working windows, and mandatory jobs that no capable agent can reach and serve in time on its own tour. The check never rejects a solvable input.
Break pattern and its limits
break_rule with max_continuous M and duration D means: work at most M at a stretch, then take a break of at least D. It is an abstract pattern, not a domain model of driving and rest times. Measurement runs from the start to the end of the tour; travel, service duration and waiting count as work, only breaks of at least D interrupt. Fixed breaks of at least D count as well.
Limitation
Rule breaks are placed only directly before or directly after a service duration, at most one per stop. Travel and waiting are not interrupted in the middle.
- A single trip or a stop with arrival and departure that would need two breaks cannot be planned for agents with a rule.
- At most two rule breaks lie between two stops.
- There is no rule break at the start of a tour; with an open end there is none after the last stop.
- Tours that could only be kept with breaks elsewhere count as not feasible. If the rule cannot be kept, the agent cannot be used.
- Mandatory jobs whose service duration exceeds max_continuous for every capable agent result in infeasible.
- Rule breaks appear in route.breaks with the IDs rule-1, rule-2 and so on. The ID prefix rule- is reserved for fixed breaks of agents with a rule.
- At most 2 different rules per request, at most 2 different profiles and 2 different combinations of profile and cost_factor among the agents. The break pattern requires a duration in the agent's profile.
Limits
Exceeding one results in status invalid (HTTP 400) with a message in errors[]. The check reports all errors at once.
| Limit | Value |
|---|---|
| Nodes with matrices | 2,000 |
| Edges with edges | 200,000 |
| Profiles | 8 |
| Agents | 200 |
| Stops (visits + 2 × shipments) | 2,000 |
| Routing nodes: stops × (1 + 2 × number of break rules) + 2 × agents | 2,500 |
| Distinct pairs of profile and cost_factor | 8 |
| With edges: needed nodes (start, end, visits, pickups, deliveries) × nodes of the network × profiles | 30,000,000 |
| Magnitude of every numeric value (finite) | ≤ 1e9 |
| time_limit_seconds | 1 to 600 |
| Request size | up to 30 MB |
A full cost and duration matrix for about 1,300 nodes fits in 25 MB; with two profiles about 900 nodes. Requests above 4 MB are accepted and handled automatically.
Large results
For optimal and feasible, the full solution always sits behind a signed URL: instead of routes, dropped and unused_agents, the response contains result_url and result_expires_at. Download the file with GET, without credentials; read routes, dropped and unused_agents from that file. Only for infeasible and unknown (and as the error response for invalid) is everything in the response itself. Offloading is always on; config.offload_result is always set to true.
File contents
The file behind result_url contains the full response including the routes. Its request_id is our internal transaction ID; your own request_id is in the endpoint's response.
curl -s "$RESULT_URL"
{
"status": "optimal",
"request_id": "…",
"routes": [{
"agent": "agent-1",
"stops": [
{ "type": "start", "node": "depot", "arrival": 0, "departure": 0, "load": [0] },
{ "type": "visit", "id": "v1", "node": "a", "arrival": 600, "departure": 900, "load": [4] },
{ "type": "visit", "id": "v2", "node": "b", "arrival": 1200, "departure": 1500, "load": [7] },
{ "type": "end", "node": "depot", "arrival": 2400, "departure": 2400, "load": [7] }
],
"breaks": [],
"cost": 31, "duration": 2400
}],
"unused_agents": [],
"dropped": [],
"totals": { "cost": 31, "penalties": 0, "objective": 31 },
"statistics": { "timing": { "total_seconds": 0.05, "solve_seconds": 0.04, "billable_seconds": 0.05, "stop_reason": "completed" } },
"warnings": [],
"diagnostics": null,
"errors": []
}result_url
The result_url is effectively valid for at most about 24 hours, regardless of result_url_expires_in, and shorter for shorter-lived sessions. Fetch results promptly. Every request gets its own file.
Errors
Invalid requests are answered with HTTP 400 and cost nothing. For schema violations and for the content check, error.errors[] contains field and message for each error, all errors at once. field is the path in the request, for example task.visits[17].node; messages are in German.
| HTTP | Case | When |
|---|---|---|
| 400 | error.errors[] | Schema violation: missing required field, wrong type, unknown field, wrong task.type or a value outside the field limits. |
| 400 | error.errors[] | Content check: unknown or duplicate IDs, matrix not square, vector lengths that do not match, time condition without duration, size limit exceeded and more. |
| 400 | bad_request | The body is not valid JSON. |
| 402 | insufficient_credits | The balance does not cover the reservation. |
| 5xx | — | Unexpected error or timeout of the service. The reservation is refunded. |