Schemas

The Problem object embedded within the main solve request.

Your identity for ownership comes from your API key (or Clerk token), never from this field, so a run is owned by the credential that submitted it — POST /user_runs returns the runs your key made regardless of what userId you send. Required only when you call without a credential: an API-key or token request may omit it (the value is then ignored), but a request with neither a key nor a token must supply a non-empty userId as a self-assigned id, or it is rejected with 400 MISSING_USER_ID. The browser app's legacy soft-auth path uses it this way.

Optional. The slug of the published example scenario this solve was loaded from (as returned by /list_examples). Published examples legitimately exceed the free tier's size limits, so sending this grants a bounded allowance sized from that example's own row counts plus a small edit margin - enough to run and tweak the demo, and never more than the named example's real size. Omit it for a user's own scenarios; an unrecognised slug is ignored.

This schema defines the problem data for an optimization Problem. The particular data objects used will depend on the problemType.

This schema defines how to interpet the input time field settings. Optimiciti allows for input times to be specified as absolute numeric values (i.e 0, 12, 60, etc.) or as date/time values (i.e. 1/1/2024, 2:24pm).

Which coordinate family this problem's locations use. geographic (the default, and what every existing payload means) uses latitude/longitude on the Earth. cartesian uses unbounded x/y on an arbitrary plane, for scenarios with positions but no addresses. It describes the DATA, not the costing, so it is set once per request rather than per cost setting - and it decides which distance/duration methods are valid.

Indicates if the request was successful

The main response payload. Can be an object, array, boolean, or string.

Internal error code

Human readable error message

Additional error context

The unique Run ID

When the run was submitted, as a Unix timestamp in seconds. An integer, the same type POST /user_runs returns for this run.

The run's lifecycle status, the same value POST /run_status reports: queued, running, succeeded, failed or cancelled. Runs from before the lifecycle field existed are all finished and read succeeded.

A compact summary of the finished run: the assignmentSummary, routeSummary and costSummary parts of the result's resultSummary, key for key (the full result, including timingSummary, is in POST /run_results_by_run_id). Empty ({}) for runs finished before 2026-09-18, which predate the summary being written; there is no backfill.

The name given with POST /update_run_name. Absent until the run has been renamed.

The unique User ID

The time unit to use for optimization. This time unit will apply, as applicable, to location open and close windows, trip open and close windows, vehicle operating times, and travel durations. Integer (default) indicates that all times are in absolute time units from an arbitrarily defined time 0. Clock indicates that times will be interpreted as literal clock times and calendar dates. Which time fields are READ depends on this: integer reads only the *TimeInt fields; clock reads only the *TimeStr fields, plus *DayInt as a day offset to them. integer is also what you get when timeSettings is omitted, so clock times such as 9:00 AM need timeSettings with timeUnit: clock at the top level of the problem (not inside problemData). A request whose time values would be ignored under the unit it declares is refused with 400 IGNORED_TIME_WINDOW.

The format to expect all time fields in. This field is only relevant when timeUnit = "clock". Formattings should match the formats described by the python pandas.Period.strftime class. For example, if the format used matches 09:32pm, then '%I:%M%p'. If null is passed, then the pandas.to_datetime function will be used to detect the format.

A boolean field indicating whether to allow the optimization time period to extend multiple days. This field is relevant only when timeUnit = "datetime".

The date unit to use for optimization. This field is only relevant when timeUnit = "clock" and multipleDays = true. If this field is integer, then days will be measured as absolute days from an arbitrarily defined day 0. Calendar indidates that dates will be interpreted as literal calendar dates.

The format to expect all dates fields in. This field is only relevant when dateUnit = "calendar", multipleDays = true, and timeUnit = "clock". Formattings should match the formats described by the python pandas.Period.strftime class. For example, if the format used matches 2024-12-31, then '%Y-%m-%d' should be passed for this parameter. If null is passed, then the pandas.to_datetime function will be used to detect the format.

A string that uniquely identifies this location.

A name for this location. Required: a request whose location has no locationName is refused with 422. It is echoed on every route stop that visits the location (RouteStop.locationName) and on unassignedLocationsFull, so a route sheet is readable without re-joining the input.

The amount of vehicle capacity this location consumes

The latitude for this location. Required only if autoCalculateDuration or autoCalculateDistance is true.

The longitude for this location. Required only if autoCalculateDuration or autoCalculateDistance is true.

Cartesian x position on an arbitrary plane (warehouse floor, factory layout, PCB). Unbounded - deliberately NOT range-validated, unlike longitude. Use with coordinateSystem=cartesian; x is the exact counterpart of longitude (x = longitude, y = latitude), so a scenario can migrate between the two families without reordering. Supply either latitude/longitude or x/y, never both.

Cartesian y position on an arbitrary plane. Unbounded - deliberately NOT range-validated, unlike latitude. Use with coordinateSystem=cartesian; y is the exact counterpart of latitude. Supply either latitude/longitude or x/y, never both.

Whether this location serves only as a depot for vehicles (true) or if this location should be serviced.

How long service at this location takes, in the problem's time unit (minutes under timeSettings.timeUnit: clock; your integer unit otherwise). Charged at the stop; defaults to 0.

An integer value representing the earliest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and minArrivalTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the earliest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and minArrivalTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the earliest day this location can be serviced. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching minArrivalTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on arrival.

An integer value representing the latest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and maxArrivalTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the latest time this location can be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and maxArrivalTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the latest day this location can be serviced. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching maxArrivalTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on arrival.

An integer value representing the exact time this location must be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for this location, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the stop -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and exactArrivalTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the exact time this location must be serviced (time t=0 is the earliest start time). Leave empty if there are no time restrictions on arrival. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for this location, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the stop -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and exactArrivalTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the exact day this location must be serviced. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching exactArrivalTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on arrival. This is a HARD PIN: the solver must arrive at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for this location, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the stop -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins).

The color to use for this location in the output. Accepts a hex code ("#FF0000") or a CSS color name ("crimson").

The vehicleTypeIds that can service this location. These vehicleTypeIds must exist in the VehicleTypes passed in ProblemData for this problem. Leave empty if there are no restrictions on which vehicle types can service this location.

Optional. Pin this location to a specific vehicle: the solve must use this vehicle to serve this stop. The vehicleId must exist in the Vehicles passed in ProblemData. If the pin cannot be satisfied - the vehicle does not exist, or its type is excluded by this location's vehicleTypeIds - the location is returned unassigned rather than served by a different vehicle. Leave null for no pin.

A unique identifier for this trip. It must be a whole number written as a string, for example "1", with no leading zeros. Any other value (a UUID, "trip-1", "1.5") makes the run fail, and a padded one ("007") comes back as "7".

The locationId for the origin location of this trip. This locationId must exist in the Locations passed in ProblemData for this problem.

The locationId for the destination location of this trip. This locationId must exist in the Locations passed in ProblemData for this problem.

A name for this trip (optional).

The vehicleTypeIds that can be used to service this trip. These vehicleTypeIds must exist in the VehicleTypes passed in ProblemData for this problem.

Optional. Pin this trip to a specific vehicle: the solve must use this vehicle for both the pickup and the delivery. The vehicleId must exist in the Vehicles passed in ProblemData. If the pin cannot be satisfied - the vehicle does not exist, or its type is excluded by this trip's vehicleTypeIds - the trip is returned unassigned rather than served by a different vehicle. Leave null for no pin.

An integer value representing the earliest time this trip can be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and minPickupTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the earliest time this trip can be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and minPickupTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the earliest day this trip can be picked up. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching minPickupTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on pickup.

An integer value representing the latest time this trip can be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and maxPickupTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the latest time this trip can be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and maxPickupTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the latest day this trip can be picked up. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching maxPickupTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on pickup.

An integer value representing the exact time this trip must be picked up (time t=0 is the earliest start time). Leave empty if there are no time restrictions on pickup. This is a HARD PIN: the solver must pick up at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and exactPickupTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the exact time this trip must be picked up. Leave empty if there are no time restrictions on pickup. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). This is a HARD PIN: the solver must pick up at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and exactPickupTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the exact day this trip must be picked up. Leave empty if there are no restrictions on pickup. This is a HARD PIN: the solver must pick up at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is clock, as a day offset added to the matching exactPickupTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW.

An integer value representing the earliest time this trip can be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and minDeliveryTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the earliest time this trip can be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and minDeliveryTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the earliest day this trip can be delivered. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching minDeliveryTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on delivery.

An integer value representing the latest time this trip can be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and maxDeliveryTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the latest time this trip can be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and maxDeliveryTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the latest day this trip can be delivered. Read only when timeSettings.timeUnit is clock, as a day offset added to the matching maxDeliveryTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on delivery.

An integer value representing the exact time this trip must be delivered (time t=0 is the earliest start time). Leave empty if there are no time restrictions on delivery. This is a HARD PIN: the solver must deliver at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); for an exact delivery, also if it is earlier than the trip's pickup (pinned or earliest possible) plus the pickup's service time plus the travel from pickup to delivery -- when both ends are pinned the error names both times and the travel time between them; or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and exactDeliveryTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the exact time this trip must be delivered. Leave empty if there are no time restrictions on delivery. The time format should correspond to the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). This is a HARD PIN: the solver must deliver at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); for an exact delivery, also if it is earlier than the trip's pickup (pinned or earliest possible) plus the pickup's service time plus the travel from pickup to delivery -- when both ends are pinned the error names both times and the travel time between them; or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and exactDeliveryTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the exact day this trip must be delivered. Leave empty if there are no restrictions on delivery. This is a HARD PIN: the solver must deliver at exactly this time, applied as an equal min/max window. Set EITHER the exact* fields OR the min*/max* window for the same end, never both. These are checked when the run starts, not when it is submitted: POST /problem accepts the request (202), and the run then ends with status: failed, an error saying what to fix and an error_code (EXACT_ARRIVAL_CONFLICT, EXACT_ARRIVAL_INFEASIBLE or EXACT_ARRIVAL_UNSERVABLE; see RunStatus.error_code), never by silently dropping the trip -- if the exact time and a window are both set; if no vehicle can reach it in time (the error names the earliest feasible time); for an exact delivery, also if it is earlier than the trip's pickup (pinned or earliest possible) plus the pickup's service time plus the travel from pickup to delivery -- when both ends are pinned the error names both times and the travel time between them; or if it is reachable on its own but unsatisfiable with the rest of the problem (fleet size, capacity, competing pins). Read only when timeSettings.timeUnit is clock, as a day offset added to the matching exactDeliveryTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW.

The amount of vehicle capacity this trip consumes.

Maximum minutes the actual pickup->delivery transit may exceed the direct travel time for this trip (caps detours from pooling). Null = no cap.

Minutes to service the pickup (e.g. park and load) at the trip's origin. Charged at the pickup stop. Defaults to 0.

Minutes to service the drop-off (e.g. park and unload) at the trip's destination. Charged at the delivery stop. Defaults to 0.

A unique identifier for this vehicle. Any non-empty string that is unique among your vehicles works — it is not required to be a UUID and the format is not validated. It is echoed back on each route stop as vehicleId.

The vehicleTypeId for this vehicle. This vehicleTypeId must exist in the VehicleTypes passed in ProblemData for this problem.

The locationId of the depot for this vehicle type. This locationId must exist in the Locations passed in ProblemData for this problem.

A name for this vehicle (optional).

The fixed cost for using this vehicle.

An integer value representing the earliest time this vehicle can depart from its depot to begin its route(s) (time t=0 is the earliest start time). Leave empty if there are no restrictions on when the vehicle can start. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and minStartTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the earliest time this vehicle can depart from its depot to begin its route(s). Leave empty if there are no restrictions on when the vehicle can start. The time format should match the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and minStartTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the earliest day this vehicle can depart from its depot to begin its route(s). Read only when timeSettings.timeUnit is clock, as a day offset added to the matching minStartTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on when the vehicle can start.

An integer value representing the latest time this vehicle must return to its depot after completing its route(s) (time t=0 is the earliest start time). Leave empty if there are no restrictions on when the vehicle must finish. Read only when timeSettings.timeUnit is integer (the default, including when timeSettings is omitted). Under clock it is ignored and maxEndTimeStr is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

A string value representing the latest time this vehicle must return to its depot after completing its route(s). Leave empty if there are no restrictions on when the vehicle must finish. The time format should match the timeFormat field in timeSettings (at the top level of the problem, not inside problemData). Read only when timeSettings.timeUnit is clock. The default is integer, including when timeSettings is omitted, and then this field is ignored and maxEndTimeInt is read instead; a request that sets only this form there is refused with 400 IGNORED_TIME_WINDOW rather than solved without it.

An integer value representing the latest day this vehicle must return to its depot after completing its route(s). Read only when timeSettings.timeUnit is clock, as a day offset added to the matching maxEndTimeStr time; ignored under integer or without that time, and a request that sets it where it would be ignored is refused with 400 IGNORED_TIME_WINDOW. Leave empty if there are no restrictions on when the vehicle must finish.

The locationId of the depot for this vehicle type. If null, then the startLocationId will be used as the end location. This locationId must exist in the Locations passed in ProblemData for this problem.

The color to use for this vehicle in the output. Accepts a hex code ("#FF0000") or a CSS color name ("crimson").

A unique identifier for this vehicle type.

A name for this vehicle type.

The maximum capacity of this vehicle type, in units of demand. Leave null if this vehicle type has no capacity limit.

Whether this vehicle type can be resupplied during an optimization run.

The locationId of the origin location for this travel cost. This locationId must exist in the Locations passed in ProblemData for this problem.

The locationId of the destination location for this travel cost. This locationId must exist in the Locations passed in ProblemData for this problem.

The vehicleTypeId for this travel cost. This vehicleTypeId must exist in the VehicleTypes passed in ProblemData for this problem. If null, then the travel cost will apply to all vehicle types.

The name of the vehicle type for this travel cost. This field is optional and is provided for convenience only.

The travel duration between these two locations, in the problem's time unit: minutes when timeSettings.timeUnit is clock (a value of 30 arrives half an hour later), and your own integer time unit when it is integer. The solver uses the number as-is and never rescales it, so a duration supplied in seconds under clock time makes every leg sixty times too long. POST /cost_matrix returns durations in minutes. If null, the travel duration will be calculated automatically based on the latitude and longitude of the locations.

The travel distance between these two locations. Any unit can be used, as long as it is the same for every entry: the solver never converts it, and every distance in the results (travelDistanceFromPreviousStop, totalDistanceTraveled) is reported in this same unit — there is no distance-unit setting anywhere in the problem. A matrix from POST /cost_matrix is in statute miles for geographic (latitude/longitude) coordinates and in the coordinates' own unit for cartesian (x/y) ones. If null, the travel distance will be calculated automatically based on the latitude and longitude of the locations.

The cost of travel between these two locations.

Tasks counted against this month so far: stops or trips served by runs that reached succeeded, including any run that just succeeded. Not the run being submitted, whose tasks are only known when it succeeds.

Tasks the plan includes per UTC month. null for a plan that does not meter tasks.

The UTC calendar month these numbers are for, as YYYY-MM.

When the allowance resets: the first instant of the next UTC month.

The plan tier the allowance comes from (as listed by GET /plans).

The solver's completion marker carried inside a results payload (ProblemResult.problemStatus). It is always completed: a results payload exists only for a run that finished, and the current solver writes no other value here (the other names in this enum are kept so old stored results still validate). This is not the value you poll for — the run lifecycle status returned by GET /problem/{problemId} and POST /run_status is queued/running/succeeded/failed/cancelled (see RunStatus); succeeded there and completed here describe the same finished run.

A run starts queued, becomes running, and reaches exactly one terminal state: succeeded, failed, or cancelled. Poll until the status is terminal — there is no completed value here.

The run this status is for.

Always null. The key is kept so existing clients keep parsing; the solver does not report intermediate progress, and a progress bar cannot be built from it. Poll status instead.

A human-readable reason, present only when status is failed. To act on a failure in code, branch on error_code; this wording may change.

Why the run failed, as a stable code: present when status is failed, and null otherwise. Branch on this, not on error -- the sentence is written to be read and its wording may improve; the code will not change. These conditions are found while the run is being solved, after POST /problem has already answered 202, so they never arrive as an HTTP error: poll for them here. One of: NO_FEASIBLE_SOLUTION (no plan satisfies the problem as specified -- conflicting time windows, capacities, vehicle shifts, or missing travel costs between stops that must reach each other), SOLVE_TIMEOUT (no solution was found within the maximum solve time), INVERTED_TIME_WINDOW (a location, trip or vehicle has a time window that ends before it starts), INVALID_TRAVEL_COSTS (specific pickup-delivery pairs have a missing or null travel cost), EXACT_ARRIVAL_CONFLICT (a stop or trip end sets an exact time AND a min/max window), EXACT_ARRIVAL_INFEASIBLE (an exact time no vehicle can make), EXACT_ARRIVAL_UNSERVABLE (exact times each reachable alone but unsatisfiable together), or INTERNAL_SERVER_ERROR -- the failure was ours, not your problem's; error still says what happened, and a code is always present so the absence of one never has to be read as meaning anything. A run that failed before this field existed has error_code: null.

When the run was submitted, as a Unix timestamp.

The unique identifier for this optimization run.

The status of the optimization problem identified by the problemId parameter.

Metadata about the optimization problem

A compact list of the stops visited, in order. Not populated by the solver: expect null. Read the plan from routeStopsFull instead, which is the populated, self-contained version. routeStops is retained for backward compatibility and may be absent or null even on a successful run.

The optimized plan: every stop each vehicle visits, in order, with the full location and vehicle details attached. This is the field to read for the route. A run can succeed while assigning fewer than all of your stops (an over-constrained problem, or travel costs with null entries), so always check that every stop you submitted appears here (a depot appears only as a route's start and end), and treat succeeded with fewer stops served than submitted — or with all-zero distances — as an incomplete solve rather than a clean one. Unserved stops appear under unassignedLocationsFull (vehicle-routing) or unassignedTripsFull (pickup-delivery).

Not populated by the solver: expect null, even on a run that left a stop unassigned. A null here says nothing about whether stops were dropped. Read unassignedLocationsFull, which is the list the solver fills. Retained for backward compatibility.

A list of locations that were not visited by any vehicle during the optimization run, along with additional details about the location.

Not populated by the solver: expect null, even on a run that left a trip unassigned. A null here says nothing about whether trips were dropped. Read unassignedTripsFull, which is the list the solver fills. Retained for backward compatibility.

A list of trips that were not serviced by any vehicle during the optimization run, along with additional details about the trip.

Per-vehicle route geometry. Can be null. Each element's path field is a JSON-encoded string (not a nested object) — JSON.parse it before use.

A list of vehicle usage summaries for the optimization run.

The unique identifier of the vehicle.

Whether the vehicle was used (assigned at least one stop) during the optimization run.

The fixed cost incurred by this vehicle. This equals the vehicle's fixed cost if the vehicle was used, otherwise 0.

The number of vehicles assigned at least one stop.

The number of vehicles supplied in the problem (the fleet size), whether or not they were used. A vehicle that restocks and makes several trips counts once.

The number of distinct locations visited as a stop on a vehicle's route. A route's start and end (the depot) are not counted.

assigned plus everything left unassigned: the unassigned locations of a vehicle-routing problem, or the unassigned trips of a pickup-delivery problem. Depots are not counted, so this is smaller than the number of locations you submitted: a depot and two stops give total: 2. It is null, not 0, only when the problem had no stops to visit (every location a depot), which POST /problem now refuses with 400 NO_STOPS_TO_VISIT; you will see it only on runs submitted before that check.

Summary of vehicle assignment counts for an optimization run.

How many locations were served. assigned == total means nothing was left unassigned. Neither number counts depots, so neither is the number of locations you submitted.

Total distance traveled across all vehicle routes, in the same unit as the distance values in the submitted travelCosts (there is no distance-unit setting; the solver reports what it was given). When the matrix came from POST /cost_matrix that is statute miles for geographic coordinates and the coordinates' own unit for cartesian.

Total travel time in minutes across all vehicle routes.

Total travel cost across all vehicle routes.

Sum of fixed costs for all vehicles used in the solution.

Sum of distance- or time-based travel costs across all routes.

Wall-clock time in seconds taken by the solver to produce a solution.

High-level counts of vehicles and locations that were assigned during the optimization run.

Aggregate travel metrics across all vehicle routes in the optimization run.

Breakdown of fixed and variable costs for the optimization run.

Timing information for the optimization run.

The full optimization result including routes, stops, and unassigned locations.

A high-level summary of key metrics from the optimization run.

A list of travel costs between pairs of locations. Each travel cost represents the duration, distance, and cost of travel between two locations.

A list of errors encountered during the cost matrix calculation. Each error represents a problem with calculating the travel cost between two locations.

This schema defines the response for travel costs between pairs of locations.

This schema defines an error encountered during the cost matrix calculation. Each error represents a problem with calculating the travel cost between two locations.

A unique identifier for this stop, represented as a UUID.

The locationId of the stop.

The vehicleId of the vehicle that visited this stop.

The amount of time the vehicle spent servicing this stop, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The position of this stop in its vehicle's route, 0-based: index 0 is the vehicle's departure from its start depot (route_start), the first customer stop is 1, and the final return to the depot (route_end) is the last index. Consecutive within a vehicle's route; use it directly as an array index, never stopNumber - 1.

The amount of capacity served at this stop.

The tripId of the trip that visited this stop, if applicable for this problem type.

The time at which the vehicle arrived at this stop, in integer time units from the start of the run. Rounded to the nearest whole time unit.

The time at which the vehicle arrived at this stop, in the clock time format specified in the timeSettings.timeFormat field.

The time at which the vehicle departed from this stop, in integer time units. This is the number of time units from the start of the optimization run.

The time at which the vehicle departed from this stop, in the clock time format specified in the timeSettings.timeFormat field.

The cost of the leg from the previous stop to this stop (0 on route_start), in the same units as travelCostTo. Sums to routeSummary.totalTravelCost. Absent on results saved before it existed: for those, shift travelCostTo one stop later within each route.

The amount of time the vehicle waited at this stop before servicing the location, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The amount of time the vehicle waited at this stop after servicing the location, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The role this stop plays on the route: location_visit (a plain vehicle-routing visit), pickup and delivery (the two ends of a pickup-delivery trip), route_start and route_end (the depot legs that open and close a vehicle's route), break_start and break_end (a scheduled driver break), restock (a return to a depot to reload mid-route), and drop (a forced-unassigned stop the solver could not serve).

The action taken at this stop. This is a human-readable description of the action taken at this stop, such as "Pickup 5 passengers at Chicago for Trip 1" or "Deliver 10 packages to New York".

The travel duration from the previous stop to this stop, in the problem's time unit: minutes when timeSettings.timeUnit is clock, your integer time unit otherwise.

The travel distance from the previous stop to this stop, in the same unit as the distance values in the submitted travelCosts (there is no distance-unit setting; the solver reports what it was given). When the matrix came from POST /cost_matrix that is statute miles for geographic coordinates and the coordinates' own unit for cartesian.

A unique identifier for this stop, represented as a UUID.

The locationId of the stop.

The vehicleId of the vehicle that visited this stop.

The amount of time the vehicle spent servicing this stop, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The position of this stop in its vehicle's route, 0-based: index 0 is the vehicle's departure from its start depot (route_start), the first customer stop is 1, and the final return to the depot (route_end) is the last index. Consecutive within a vehicle's route; use it directly as an array index, never stopNumber - 1.

The amount of capacity served at this stop.

The name of the location for this stop.

The color associated with this stop -- the serving vehicle's color, echoed back as supplied (hex code or CSS color name).

The tripId of the trip that visited this stop, if applicable for this problem type.

The time at which the vehicle arrived at this stop, in integer time units from the start of the run. Rounded to the nearest whole time unit.

The time at which the vehicle arrived at this stop, in the clock time format specified in the timeSettings.timeFormat field.

The time at which the vehicle departed from this stop, in integer time units. This is the number of time units from the start of the optimization run.

The time at which the vehicle departed from this stop, in the clock time format specified in the timeSettings.timeFormat field.

The cost of the leg from the previous stop to this stop (0 on route_start), in the same units as travelCostTo. Sums to routeSummary.totalTravelCost. Absent on results saved before it existed: for those, shift travelCostTo one stop later within each route.

The amount of time the vehicle waited at this stop before servicing the location, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The amount of time the vehicle waited at this stop after servicing the location, in the problem's time unit (minutes under timeSettings.timeUnit: clock).

The role this stop plays on the route: location_visit (a plain vehicle-routing visit), pickup and delivery (the two ends of a pickup-delivery trip), route_start and route_end (the depot legs that open and close a vehicle's route), break_start and break_end (a scheduled driver break), restock (a return to a depot to reload mid-route), and drop (a forced-unassigned stop the solver could not serve).

The action taken at this stop. This is a human-readable description of the action taken at this stop, such as "Pickup 5 passengers at Chicago for Trip 1" or "Deliver 10 packages to New York".

The travel duration from the previous stop to this stop, in the problem's time unit: minutes when timeSettings.timeUnit is clock, your integer time unit otherwise.

The travel distance from the previous stop to this stop, in the same unit as the distance values in the submitted travelCosts (there is no distance-unit setting; the solver reports what it was given). When the matrix came from POST /cost_matrix that is statute miles for geographic coordinates and the coordinates' own unit for cartesian.

The name of the vehicle serving this stop, when the user provided one. Denormalized from the submitted vehicle (like locationName) so a route sheet is readable without re-joining the input; null when the vehicle is unnamed.

The vehicleId this stop was pinned to via the input's fixedVehicleId, or null if it was not pinned. Lets a client tell 'this vehicle was chosen by the solver' from 'this vehicle was required', without re-joining against the request.

The locationId of the unassigned location.

The amount of demand that was not served at this location.

The locationId of the unassigned location.

The amount of demand that was not served at this location.

The name of the unassigned location.

The latitude of the unassigned location.

The longitude of the unassigned location.

Whether this unassigned location serves only as a depot (true) or if this location should be serviced (false).

The tripId of the unassigned trip.

The amount of demand that was not able to be served by any vehicle for this trip.

The amount of capacity that was served for this dropped trip. This will typically be 0, but in some cases (e.g. partial deliveries) it may be greater than 0.

The tripId of the unassigned trip.

The amount of demand that was not able to be served by any vehicle for this trip.

The amount of capacity that was served for this dropped trip. This will typically be 0, but in some cases (e.g. partial deliveries) it may be greater than 0.

The name of the unassigned trip.

The name of the origin location for this trip.

The name of the destination location for this trip.

The locationId of the origin location for this trip.

The locationId of the destination location for this trip.

The latitude of the origin location for this trip.

The longitude of the origin location for this trip.

The latitude of the destination location for this trip.

The longitude of the destination location for this trip.

The type of optimization problem that was run.

The date and time when the optimization problem was submitted, in unix timestamp in seconds

The time spent in the queue before the optimization run started, in seconds.

The time taken to run the optimization, in seconds.

The locations to use for calculating the cost matrix.

The settings to use for calculating travel costs between locations. This includes the cost metric (duration or distance), cost multiplier, cost adder, and methods for calculating distances and durations.

The travel costs to use for calculating the cost matrix. If not provided, the cost matrix will be calculated automatically based on the latitude and longitude of the locations. A partial cost matrix can be provided to avoid recalculating travel durations and distances between locations.

Which coordinate family this problem's locations use. geographic (the default, and what every existing payload means) uses latitude/longitude on the Earth. cartesian uses unbounded x/y on an arbitrary plane, for scenarios with positions but no addresses. It describes the DATA, not the costing, so it is set once per request rather than per cost setting - and it decides which distance/duration methods are valid.

Required — there is no default; a costSettings without a costMetric is rejected with 422. The metric used as the base for the travel cost, before any multiplier or adder. duration bases cost on travel time, distance on travel distance, and custom uses the cost values you supply directly in travelCosts.

The cost multiplier to apply to the base cost metric (duration or distance) to calculate the final travel cost.

The cost adder to apply to the base cost metric (duration or distance) to calculate the final travel cost.

Whether POST /cost_matrix should compute travel durations from each location's coordinates. When omitted, it defaults to true if you supply no travelCosts, and to false if you do — so your own matrix is never silently recomputed. An explicit null is rejected (send true/false or omit it). The road network (driving) is used when you name driving as the durationMethod, or when an omitted durationMethod inherits driving from a driving distanceMethod because you explicitly sent autoCalculateDuration: true; the default method (geo) never calls the road network.

Whether POST /cost_matrix should compute travel distances from each location's coordinates. When omitted, it defaults to true if you supply no travelCosts, and to false if you do — so your own matrix is never silently recomputed. An explicit null is rejected (send true/false or omit it). The road network (driving) is used only when you name driving as the distanceMethod; the default method (geo) never calls the road network.

The method for calculating distances. geo (the default) is the ellipsoidal geodesic distance on the WGS84 ellipsoid, reported in statute miles; driving uses OpenRouteService for real road distances. euclidean is the planar straight-line distance and manhattan the right-angle (grid) distance. euclidean is accepted only for cartesian (x/y) coordinates: on geographic coordinates it would treat degrees as planar units, so the request is refused with 400 INVALID_METHOD_FOR_COORDINATE_SYSTEM — the straight-line method on the globe is geo. manhattan works for both: on the plane it is |dx| + |dy| in the coordinates' unit; on geographic coordinates it is the sum of the two geodesic legs (the north–south and east–west separations), in statute miles. driving is likewise geographic-only.

The method to use for calculating durations between locations. geo derives a duration from the ellipsoidal geodesic (WGS84) distance; driving uses OpenRouteService for real road durations; manhattan/euclidean derive it from the planar (cartesian) or, for geographic coordinates, geodesic distance. There is no fixed default — if you omit durationMethod it is inherited from distanceMethod so the two stay consistent (do not rely on a geo default: an SDK that fills one would break a cartesian request). An omitted durationMethod inherits driving from distanceMethod only when you explicitly send autoCalculateDuration: true; otherwise it falls back to geo.

Average travel speed used to turn a computed DISTANCE into a DURATION for the non-driving methods (geo, manhattan, euclidean), in distance units per hour. Ignored when durationMethod is "driving", where the road network supplies real durations.

This exists because a straight-line distance is not a time. Before it, geo durations were the distance number itself, which meant every vehicle travelled at exactly 60 mph between adjacent stops. The default of 30 suits urban and suburban work; raise it for long inter-city legs, lower it for dense city centres or mountain roads.

Multiplier applied to a straight-line distance when deriving DURATION, to account for roads not running as the crow flies. Affects duration only - the reported distance stays the true geodesic value the method name promises. 1.25 is a common urban rule of thumb; use 1.0 to model travel that really is direct.

Whether the cost multiplier should depend on the vehicle type. If true, then the cost multiplier will be applied separately for each vehicle type. If false, then the cost multiplier will be applied based on the first vehicle type in the VehicleTypes list.

The multiplier to apply to the base cost metric (duration or distance) to calculate the final travel cost.

Whether the cost adder should depend on the vehicle type. If true, then the cost adder will be applied separately for each vehicle type. If false, then the cost adder will be applied based on the first vehicle type in the VehicleTypes list.

The adder to apply to the base cost metric (duration or distance) to calculate the final travel cost.

Maximum number of rows allowed for this table

Limits for locations table

Limits for trips table

Limits for vehicles table

Limits for vehicle types table

Maximum saved scenarios (null for unlimited)

Days of run history retention (null for unlimited)

Maximum number of solves (queued + running) the user may have in flight at once

Optimization tasks included per month on this plan (null for tiers that do not meter tasks, i.e. the web tiers). A billable task is one stop or trip served by a SUCCEEDED solve; unassigned stops, and failed or cancelled runs, cost nothing.

Stable internal tier key (never changes), e.g. "free" or "professional".

Customer-facing display name as configured in the Clerk dashboard, e.g. "Professional".

Resolved per-tier limits.

Capability flags keyed by feature; absent keys default to allowed.

Unique id of the stored scenario behind this example. To load the example, use slug with GET /example_scenario/{slug}.

Stable, URL-safe unique key ([a-z0-9-]).

Full display name of the scenario.

Model type, e.g. "pickup-delivery" or "vehicle-routing".

Short card heading (may be empty).

1-3 sentence blurb shown under the title.

Card image URL; empty when none is set.

Key constraints shown as bullets.

Tags for gallery filtering and card chips.

Small stat objects, e.g. [{"Locations":17},{"Trips":12}].

Industry/vertical for gallery filtering, e.g. "healthcare", "transportation" (empty when not set).

Additional industries this example also belongs to, beside the primary industry. A gallery filter should treat an example as matching if the requested industry is the primary OR appears here. Optional and additive: an absent or empty array behaves exactly as a card with only industry set, so clients that ignore it are unaffected. Exists because some scenarios genuinely sit in two verticals - special-needs school transport is education and healthcare; roll-off container swaps are public-works and logistics - and forcing one label makes an industry page look emptier than the library actually is.

Where an example scenario is set, for gallery filtering.

Derived instance size bucket: "small", "medium", or "large" (empty when not set).

Constraint-shape tags for gallery filtering (e.g. "time windows", "vehicle types"), distinct from industry.

Which fact this example's per-location colours encode. The same light-to-dark ramp means time of day on one example and demand on another, so a legend must read this rather than infer meaning from the swatches. "none" means the example's stops are uniform and are deliberately left uncoloured.

Display name for colorDimension, rendered verbatim as a legend title. Null when colorDimension is "none".

How to render the legend: "categorical" for a swatch per group, "ramp" for an ordered light-to-dark strip. Null when colorDimension is "none".

Only the colours this example actually uses, in scale order, so a legend shows the two steps in play rather than every step of the scale. Empty when colorDimension is "none".