OptimizationResponse

The body returned by every /optimize/* endpoint (and embedded under result in AsyncJobStatus once an async job completes).

Top-level fields

Field	Type	Description
status	string	Solve outcome; see Status values below.
problem_id	string	Echo of `metadata.problem_id`.
solve_time_ms	integer	Wall-clock solve time in milliseconds.
routes	Route[]	One entry per resource that was actually used.
unserved	UnservedJob[]	Jobs/pickup/delivery steps the solver did not serve.
score	ScoreBreakdown	Present unless `output_options.include_score_breakdown=false`.
diagnostics	SolverDiagnostics	Present only when `output_options.include_diagnostics=true`.
infeasibility_report	InfeasibilityReport	Present only when `status="infeasible"`.
warnings	string[]	Non-fatal warnings (e.g. out-of-region jobs silently skipped by an adapter upstream).

Status values

status	Meaning
`optimal`	Provably best solution found within the time limit.
`feasible`	Valid solution found, optimality not proven (usually the time limit was hit first).
`infeasible`	No valid solution exists for the given constraints. Check `infeasibility_report`.
`timeout`	Time limit expired before any solution was found.
`error`	Internal error.

Route

Field	Type	Description
resource_id	string	Resource assigned to this route.
day	integer	Multi-day only: which day this route belongs to (0-indexed). `null` for single-day problems.
total_distance	integer	This vehicle's total route distance (metres), mirrored from `summary.total_distance` so it is directly accessible without drilling into `summary`.
activities	Activity[]	Ordered list of stops/events on this route.
summary	RouteSummary	Aggregate metrics for this route.
violations	RouteViolation[]	Constraint violations detected on this route, if any.

Per-vehicle vs fleet-wide distance

Use route.total_distance (or route.summary.total_distance, identical value) for a single vehicle's distance. Use score.travel_distance for the fleet-wide total across every route.

RouteViolation

Field	Type	Description
type	string	One of: `time_window`, `capacity`, `max_travel_time`, `max_distance`, `max_tasks`, `skill`.
message	string	Human-readable description.
value	float	Observed value that triggered the violation.
limit	float	Configured limit that was exceeded.

Activity

Field	Type	Description
type	string	One of the eight activity types below.
job_id	string	Set for `service` activities.
shipment_id	string	Set for `pickup`/`delivery` activities.
dump_station_id	string	Set for `reload` activities.
location_index	integer	Matrix index of this activity's location.
arrival_time / departure_time	integer	Seconds; when the resource arrives/departs.
waiting_time	integer	Time spent waiting before service began (seconds).
service_time	integer	Time spent in service (seconds).
load_on_arrival / load_on_departure	LoadSnapshot	Cumulative load state at arrival and departure.
distance_from_prev / time_from_prev	integer	Distance (metres) / time (seconds) from the previous activity.

Activity types

Type	Meaning
`start`	Route start at depot or start location.
`end`	Route end at depot or end location.
`service`	Job service stop.
`pickup`	Pickup leg of a shipment.
`delivery`	Delivery leg of a shipment.
`break`	Driver break interval.
`reload`	Capacity reset at a dump station.
`wait`	Explicit wait activity (early arrival at a time-windowed stop).

LoadSnapshot

Field	Type	Description
total	integer	Total load (single-capacity problems).
by_dimension	object	Map of dimension name to current load (multi-capacity problems).

RouteSummary

Field	Type	Description
total_distance	integer	Total route distance (metres).
total_travel_time	integer	Total travel time (seconds).
total_service_time	integer	Total service time at stops (seconds).
total_waiting_time	integer	Total waiting time (seconds).
total_time	integer	End time minus start time (seconds).
num_stops	integer	Number of service stops.
num_jobs	integer	Number of jobs served.
max_load / max_loads	integer / object	Peak load, single- or multi-capacity respectively.
cost	float	Total route cost.

UnservedJob

Field	Type	Description
id	string	Job, pickup step, or delivery step id.
type	string	`job`, `pickup`, or `delivery`.
reason	string	Machine-readable reason code; see below.
reason_detail	string	Human-readable explanation, populated by the Layer 0 feasibility analysis.

Unserved reason codes

Code	Meaning
`no_feasible_vehicle`	No resource is eligible at all (wrong skills, zone, etc.).
`time_window_infeasible`	No resource can reach the job within its time window.
`capacity_infeasible`	Demand exceeds every available capacity.
`skill_mismatch`	No resource has the required skills.
`zone_restriction`	Job is in a zone with no eligible resource.
`day_constraint`	Pinned to a day when no resource is available.
`penalty_too_low`	Solver chose to drop the job; penalty was cheaper than insertion cost.
`dropped_by_solver`	Generic: solver dropped it for optimization reasons.

ScoreBreakdown

Field	Type	Description
total	float	Total objective score (the weighted sum the solver actually optimized).
travel_distance	float	Fleet-wide distance component, summed across all routes (metres). Use this for the total-distance-across-all-vehicles figure.
travel_time	float	Fleet-wide travel time component (seconds).
fixed_vehicle_cost	float	Fixed cost for vehicles used.
penalty_dropped	float	Penalty for dropped optional jobs.
fairness_cost	float	Workload imbalance cost.
num_vehicles_used	integer	Number of resources with at least one stop.

total is not a distance

score.total is the weighted objective value the solver minimized/maximized, not a raw distance figure — it can mix distance, time, fixed costs, and penalties depending on the active objective. For raw fleet-wide distance, always read score.travel_distance.

SolverDiagnostics

Returned only when output_options.include_diagnostics=true.

Field	Type	Description
solver_status_code	integer	Raw solver status code.
num_nodes	integer	Number of routing nodes in the model.
num_vehicles_modeled	integer	Number of vehicles in the model, including virtual (multi-day) vehicles.
iterations	integer	Number of search iterations.
search_log	string[]	Verbose solver output lines, only when `options.log_search=true`.

InfeasibilityReport

Present only when status="infeasible".

Field	Type	Description
guaranteed_unservable	JobFeasibilityHint[]	Jobs statically proven unservable by any active resource (Layer 0 analysis, always runs).
diagnostic_unserved	string[]	Job ids dropped even in a relaxed solve where every job is optional (Stage 1) — the true root causes.
collective_bottleneck	string	Comma-separated constraint types found to be the minimum infeasibility set (Stage 2), when no individual job is the culprit.
collective_bottleneck_detail	string	Human-readable detail behind `collective_bottleneck`.
structural_issue	boolean	`true` when even the relaxed solve (Stage 1) found no solution at all — indicates a model-level problem, not a job-level one.
structural_hint	string	Human-readable hint accompanying `structural_issue`.

JobFeasibilityHint

Field	Type	Description
job_id	string	The job in question.
feasible_resource_count	integer	How many active resources could serve this job in isolation. `0` means guaranteed unservable.
blocked_reasons	string[]	One human-readable entry per blocking resource.

Minimal response

{
  "status": "optimal",
  "problem_id": "v2-01-basic",
  "solve_time_ms": 47,
  "routes": [
    {
      "resource_id": "truck-1",
      "day": null,
      "total_distance": 17,
      "activities": [
        { "type": "start",   "location_index": 0, "arrival_time": 0, "departure_time": 0 },
        { "type": "service", "job_id": "j1", "location_index": 1, "arrival_time": 4, "departure_time": 4 },
        { "type": "service", "job_id": "j2", "location_index": 2, "arrival_time": 9, "departure_time": 9 },
        { "type": "end",     "location_index": 0, "arrival_time": 17, "departure_time": 17 }
      ],
      "summary": {
        "total_distance": 17, "total_time": 17,
        "num_stops": 2, "num_jobs": 2,
        "cost": 0.0
      }
    }
  ],
  "unserved": [],
  "score": {
    "total": 17.0, "travel_distance": 17.0,
    "num_vehicles_used": 1
  }
}