Problem
Submit an optimization problem and follow it to completion. This is the core of the API - build your problem, submit it, poll for status, then read the optimized routes.
Submit an optimization run
Queues a vehicle-routing or pickup-delivery problem for the solver and returns immediately with 202 Accepted and a run_id — it does not wait for the solve, and it does not compute travel costs. /problem uses the problemData.travelCosts you give it, so build that matrix first: either call POST /cost_matrix and pass its travelCostResponses straight into problemData.travelCosts (that endpoint computes from coordinates by default), or supply your own travelCosts. There is no costSettings on /problem; auto-calculation happens on POST /cost_matrix. An absent or empty matrix is rejected with MISSING_TRAVEL_COSTS, and a matrix with no usable pair at all with UNCOSTED_TRAVEL_MATRIX (see the 400 response); an all-zero matrix solves fine (every stop assigned). The solver treats a null cost or duration as unreachable, so a matrix that is only partly filled is accepted and the run succeeds with the stops behind the empty pairs left unassigned. Passing these checks is a floor, not a promise that every stop is assigned: read the assigned count in the results. See the warning on POST /cost_matrix. Poll GET /problem/{problemId} (or POST /run_status) until the run is terminal, then fetch results with POST /run_results_by_run_id.
Submit an optimization run › Request Body
The Problem object embedded within the main solve request.
userIdYour 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.
exampleSlugOptional. 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.
Submit an optimization run › Responses
Accepted. The run is queued and the solver runs in the background. The body carries data.run_id — the identifier you poll and fetch results with.
successPoll a run's status (never its routes)
Returns the lifecycle status of the run identified by problemId (queued, running, succeeded, failed or cancelled) and nothing else: the routes are never in this response. Once data.status is succeeded, fetch the plan with POST /run_results_by_run_id. Poll every 2 to 5 seconds: a tight loop gains nothing and will run into the gateway's rate limit (429).
path Parameters
problemIdThe problemId of a previously submitted problem to check the status of
Poll a run's status (never its routes) › Responses
The run's current lifecycle status. data.status is queued, running, or a terminal succeeded / failed / cancelled. This response never contains the routes — once data.status is succeeded, fetch the plan with POST /run_results_by_run_id.
successThe run lifecycle status returned by GET /problem/{problemId} and POST /run_status. This is what a poller branches on. It is deliberately small — it never carries the routes; fetch those from POST /run_results_by_run_id once the run has succeeded.
Cancel the optimization run identified by the problemId parameter
Cancel the run identified by the problemId path parameter. A queued run is skipped by the worker; a running run is cancelled best-effort. If the run has already reached a terminal state (succeeded, failed, or cancelled) this has no effect. POST /cancel_run (which takes the id in the body) does the same thing; use whichever fits your client.
path Parameters
problemIdThe problemId of a previously submitted problem to cancel
Cancel the optimization run identified by the problemId parameter › Responses
The cancellation was accepted. The body is the standard envelope; data carries the run's current record, including its status after the cancel was applied.
successIndicates if the request was successful
dataThe main response payload. Can be an object, array, boolean, or string.