Submitting a plan
submit creates the plan and starts its optimization in the same call. It returns the stored plan, with the id the server assigned and the warnings about anything the API amended. Submitting consumes credits with a production key: see Pricing and credits.
submit is never retried automatically, even after a network error: the API has no idempotency key, so a retry could create the plan twice. If a submit fails without a response, check with plans.list whether the plan exists before submitting again.
Waiting for the solution
Use the first line with a sandbox key, and the second with a production key. In TypeScript, keep thelet on the line you keep.
wait follows the plan until the optimization of its current version is over, then returns the solution:
- It reads the plan’s state every 10 seconds at first, stretching to every 60 seconds on long optimizations, and fetches the solution only once the plan is done. It doesn’t sleep through the whole
maxOptimizationDuration: the engine often stops earlier, once it stops finding improvements. - The solution’s final state says how the optimization ended:
optimized, orinterruptedorstoppedwhen it was cut short. Check it before treating the result as final. Right after a restart withstart, the run that the restart cut short reportsinterrupted.waitdoesn’t stop on that state, unless it lasts more than 60 seconds. - It fails with
KardinalOptimizationErrorwhen there’s no solution to return:NO_SOLUTION(the version ended without one),PLAN_SUPERSEDED(a newer version was submitted meanwhile), orOPTIMIZATION_STALLED(still optimizing 5 minutes past itsmaxOptimizationDuration). A plan deleted while waiting fails withKardinalNotFoundError. - The optional time limit (
timeoutin seconds in Python,timeoutMsin milliseconds in TypeScript) fails withKardinalTimeoutErroronce elapsed, after checking the state one last time. The plan keeps running on the server. To keep waiting, callwaitagain with the sameid: don’t submit the plan again.
Tracking progress without blocking
To follow a plan without waiting, read its state and fetch the solution yourself:solutions.get returns the current best solution right away, even while the engine is still improving it. Right after submit, it fails with a 404 until the engine has a first solution. Like any manual tracking, read a plan’s state no more than once every 10 seconds.
optimized means the optimization is over. interrupted and stopped mean it was cut short, and solutions.get can then fail with a 404. To handle every end state, use wait.
In the sandbox, a plan finishes in a few seconds. Call wait with a time limit of about one minute. If you write your own loop, read the state once by hand first, then stop the loop after about one minute.
Waiting in a web backend or serverless function
wait is meant for scripts, notebooks, and workers. In a request handler, don’t hold the request open while the engine runs:
- Submit the plan, store its
id, and return right away. - Read the state later — from a scheduled job, a queue worker, or the next request from your front end — and fetch the solution once the plan is done.
- A serverless function usually has a shorter time limit than an optimization: track the plan across invocations instead of waiting in one.
- Python
- TypeScript
The client is synchronous. In an
asyncio app, run blocking calls in a thread (await asyncio.to_thread(k.routing.solutions.wait, plan_id)) so they don’t block the event loop, or track the plan with get_status, as shown earlier.Re-optimizing with update
When something changes — a new order, a cancelled one, a vehicle out of service — update the plan rather than submitting a new one. The engine continues from the current solution instead of starting over: see Real-time re-optimization.
updatereplaces the whole plan: anything left out is removed. Start from the plan returned byget,submit, or a previousupdate, and modify it.- The version increments, and the plan is re-optimized, only if the content actually changed. An identical update is a free no-op that keeps the same version, which makes replaying an
updateharmless. - A field the API added after your SDK version, read by
get, is kept and sent back, so updating with an older SDK doesn’t delete it. - An archived plan refuses an update without
force, with a403whosedetailsisCannot update an archived plan, except with the 'force' query param.force=True(Python) or{ force: true }(TypeScript) unarchives it first. On an archived plan, a forced update always creates a new version and re-optimizes the plan, even if its content is identical, so every stop is billed again, as for any update or restart made more than 24 hours after the plan’s creation. On any other plan,forcehas no effect. Don’t set it by default.
Replacing a plan from your own data
update needs the plan that get returned. When you rebuild the plan from your own data instead, call replace. It takes the same input as submit, so you don’t copy id, agencyId, or version.
replacereplaces the whole plan, likeupdate. The version increments, and the plan is re-optimized, only if the content changed.- Anything you leave out is removed, even a field the API added after your SDK version. To keep such a field, use
getand thenupdate. - When two programs write the same plan, the last write wins.
- The SDKs add default values to the input, such as
priority. A plan you created from raw JSON doesn’t have them. So its firstreplacecreates one new version, even with the same content. Later identical calls keep that version. replacerefuses a plan that you read withget, before sending anything. Send that plan back withupdate.forceworks as it does forupdate.
Starting and stopping optimization
wait right after start. It then waits for the new run. The run that the restart cut short reports interrupted about a second later, and wait doesn’t stop on it. Before kardinal-ai 2.1.0 and @kardinal-ai/sdk 1.2.0, wait could return that interrupted state, with the previous run’s solution.
Both keep the plan’s content and version unchanged, and return a reference to the plan (agencyId, planId, planVersion). A restart with start is billed like an update, by the 24-hour rule of Pricing and credits, and it counts as one optimization against your agency’s daily and monthly optimization quota (see Limits and quotas). An archived plan refuses start and stop without force, with the same 403 as for update. force unarchives the plan first, for a stop too. An archived plan is more than 24 hours old, so a forced restart bills every stop again.
Listing plans
get for the full plan. Archived plans are left out by default; pass archived="included" or "only" (Python) or { archived: "included" } (TypeScript) to change that. A page past the last one returns the last page: its page field gives the page actually returned. See Paginating results.

