Skip to content

How optimization works

~4 min read · Getting started

The API is asynchronous. Optimizing a real fleet takes compute, so you don't wait on a single request — you submit, then poll for the result.

The three steps

  1. Define the problem — fleet, jobs, objective, configuration.
  2. Submit it with POST /raas/optimization. You get back a 202 and an id almost immediately.
  3. Retrieve the result with GET /raas/optimization/{id}. You get 202 while it's still solving, then 200 with the solution.
sequenceDiagram
    participant You
    participant API
    You->>API: POST /raas/optimization (problem)
    API-->>You: 202 { id }
    loop until ready
        You->>API: GET /raas/optimization/{id}
        API-->>You: 202 (still solving)
    end
    You->>API: GET /raas/optimization/{id}
    API-->>You: 200 { solution }

Polling guidance

There is no webhook (yet), so you poll:

  • Start polling after a short delay (e.g. 1–2 seconds).
  • Poll on a steady interval (e.g. every 2 seconds), and back off for larger problems.
  • Stop when you get 200 (done) or a 4xx/5xx (error).

See Polling and backoff for a robust loop.

Why asynchronous?

A small problem solves in seconds; a large one (hundreds of vehicles, thousands of stops) takes longer. The submit-and-poll pattern means your request never hangs waiting, and the same code works whether the solve takes 2 seconds or 2 minutes.

Re-optimization uses the same pattern

Re-planning mid-day is just another POST — one that includes each vehicle's lastKnownLocation and the status of in-progress tasks. See Re-optimization.

Related: Quickstart · Polling and backoff · Status codes