Breaks

A break is a pause in the work of a resource. A lunch and a night rest are two examples. The engine places each break inside the tour it plans. A tour is the route of one resource, from its start to its end. In the solution, a tour is a list of waypoints. A break waypoint is the waypoint where the engine placed a break. This guide covers the breaks array of a resource. Each section states one rule, with a link to the API reference where the exact behavior is written. The last section shows how to check a solution against its breaks.

Three kinds of break

The breaks array of a resource accepts three types of break. You can combine them to model a realistic shift.

Type	Triggered by	Typical use
`timeWindowBreak`	A fixed clock time	A lunch break that must happen inside a specific window, regardless of workload
`workingDurationSlidingBreak`	Cumulative working time	Labor-contract rules. The duration varies by sector and collective agreement
`travelDurationSlidingBreak`	Cumulative driving time	Road-safety rules. For example, EU Regulation (EC) 561/2006 sets a minimum of 45 minutes after every 4 hours 30 minutes of driving for professional road transport

These snippets use local times. The plan you put them in needs "tz". See Dates and time zones.

{
  "id": "driver-1",
  "workingTimeWindow": { "begin": "2026-08-03 05:00", "end": "2026-08-03 20:00" },
  "breaks": [
    { "type": "workingDurationSlidingBreak", "minBreakDuration": "PT30M", "maxInterBreakDuration": "PT6H" },
    { "type": "travelDurationSlidingBreak", "minBreakDuration": "PT45M", "maxInterBreakDuration": "PT4H30M" }
  ]
}

The two figures are not equally safe to default. The driving-time figure comes from public law, and it doesn’t depend on one employer. You can apply PT45M and PT4H30M once you have established the jurisdiction. See step 4 of the agent modeling checklist. The working-time figure usually comes from a collective agreement, on top of a lower legal minimum. A single number would be wrong for many employers. Don’t copy a duration from this page for workingDurationSlidingBreak. Ask the client to confirm it. See Break for the rule.

One break for two rules

The two sliding breaks count the same break toward both of their counters. One counter is the cumulative driving time, and the other is the cumulative working time. The engine looks for one moment that satisfies both rules. In the sandbox, it didn’t schedule a separate break for each rule. For a long shift, define the driving-time rule and the working-time rule together. A sliding break of one type only covers its own counter. The earlier documentation also said that any two overlapping breaks count once. For example, it said that a timeWindowBreak that coincides with a workingDurationSlidingBreak counts for both. This claim isn’t confirmed. The Break reference states only that the two sliding types share one break.

Where a break can fall

The engine places a break only where the vehicle already stands. It never places a break in the middle of a drive. This holds for all three types. A timeWindowBreak can fall at the start of the tour or at a stop. A sliding break falls only after a stop, never at the start of the tour. What happens to a long drive depends on the type:

timeWindowBreak. A drive that covers the whole time the break could take place makes that drive impossible. The engine leaves the stops that need it unplaced. It returns no error and no violation. If every tour of the vehicle needs that drive, the vehicle isn’t used at all.
travelDurationSlidingBreak and workingDurationSlidingBreak. Currently, the engine allows a drive longer than maxInterBreakDuration. It marks the tour valid and reports no violation. It places the break at a stop, in two cases:
- When the next drive would go over the limit, the engine places a break at the stop before it.
- When the limit is already passed on arrival at a stop, and the tour goes on after that stop, the engine adds the missed breaks at that stop. This is the catch-up. To get its length, divide the driving or working time since the last break by maxInterBreakDuration. Round the result up, then multiply it by minBreakDuration. At such a stop, the catch-up is the only break placed.
The catch-up starts after the work at the stop, so the times of the stop don’t change. Everything after the stop moves later. Nothing catches up the last drive of a tour. This is the return to the depot, or the drive to the last stop when the van has no end depot. This describes the current behaviour of the engine. It explains what the sandbox showed, and it isn’t a guarantee. The only real check is to measure the gaps yourself. See Checking a sliding break. The engine plans with the catch-up included. It can change the order of the stops. It can also push a later stop out of its time window, or push the tour past maxWorkingDuration. The engine then changes the order of the stops or leaves stops unplaced, with no error.

For example, a van has a timeWindowBreak of 45 minutes in a window from 08:30 to 09:30. The van starts work at 08:00. Its only stop is a drive of 1 hour 48 minutes away. The stop only accepts the van from 09:48 to 10:00, so the van has to leave between 08:00 and 08:12. The drive then runs through the whole window. The break can’t fall before the drive, because the van leaves before the window opens. It can’t fall after the drive, because the window closed at 09:30. The engine leaves the stop unplaced. Now give the same van a travelDurationSlidingBreak of 45 minutes after 1 hour, and no timeWindowBreak. In this example, the stop has no time window, and the van has no end depot. The engine plans the same drive of 1 hour 48 minutes. It places no break, because nothing follows the stop. The tour is valid. Now give the van a return to the depot. The van reaches the stop after 1 hour 48 minutes of driving, which is two limits of 1 hour, rounded up. The engine adds 2 × 45 minutes = 1 hour 30 minutes of break at the stop. Then the van drives back with no break, because nothing catches up the last drive. The tour is still valid, and it ends 1 hour 30 minutes later. To keep a long drive within the rule, give the route a stop where each break can fall. Each drive between two stops should stay under maxInterBreakDuration. For example, a drive of 1 hour 48 minutes split into two legs of 54 minutes, with a rest stop between them, gets one break of 45 minutes at the rest stop. If the route already has a natural stop, such as a delivery, a pickup or a customs post, use it. If it has none, add a stop where the driver can rest. It is a stop like any other. It must be reachable. In production, it costs one credit. See Pricing and credits. Then check the gaps in the solution. A sliding break doesn’t report a drive that is too long. See Checking the solution. See Resource.breaks for the rule.

When a break is owed

The engine checks breaks only inside the tour it plans. It knows nothing about what the driver does before or after that tour. A break is owed only when the tour reaches the point where the rule applies.

timeWindowBreak. It is a hard rule: the engine drops stops rather than skip the break. For example, a van is busy at one stop from 11:30 to 13:30, and a 45-minute break is due between 12:00 and 14:00. The tour would end at 13:31, with only 29 minutes of the window left, so the engine leaves that stop unplaced. When a tour keeps running past the end of the window, the solution has a break waypoint.
No break when the tour ends first. The solution has no break waypoint when the whole tour ends before the window opens. For example, a tour that ends at 08:12 has no lunch break due from 12:00. The solution has no break waypoint, no violation, and no message.
A tour that ends inside the window can have no break waypoint. In the sandbox, a van waited at a stop from 08:01 to 13:00 and the tour ended at 13:11, inside a window of 12:00 to 14:00. No break appeared. The same happened when the stop opened at 12:20, so the wait covered only 20 minutes of the window. In both tours, more than 45 minutes of the window remained after the tour ended. The rule behind this isn’t confirmed, so don’t read a wait as a break.
Sliding breaks. A sliding break is not scheduled when the tour is shorter than maxInterBreakDuration. For example, a 30-minute break after 6 hours of work doesn’t appear in a tour of 12 minutes.

Keep this in mind when a driver keeps working after the tour. The engine doesn’t see that work, so it doesn’t count it toward any break. See Break for the rule.

Night rest on a multi-day trip

A workingTimeWindow that spans more than one calendar day doesn’t force any rest between working days. See the Modelling pitfall on workingTimeWindow in the API reference. You need to encode the rest in breaks.

{
  "id": "driver-1",
  "workingTimeWindow": { "begin": "2026-08-03 05:00", "end": "2026-08-04 20:00" },
  "maxWorkingDuration": "PT37H",
  "breaks": [
    { "type": "workingDurationSlidingBreak", "minBreakDuration": "PT11H", "maxInterBreakDuration": "PT13H" },
    { "type": "timeWindowBreak", "duration": "PT11H", "timeWindow": { "begin": "2026-08-03 19:00", "end": "2026-08-04 07:00" } }
  ]
}

The long workingDurationSlidingBreak asks for a full night’s rest. Here it lasts PT11H. This figure is an illustration. Confirm the convention or regulation that applies before you publish it, as for the working-time figure in the first section. Currently, the engine allows a drive longer than maxInterBreakDuration. It adds the missed breaks at a stop that the tour continues from. See Where a break can fall. This matters for a night rest. Take a workingDurationSlidingBreak of 11 hours after 13 hours of work, and no other break. A driver reaches a stop after 14 hours 38 minutes of driving, works there for 10 minutes, and the tour goes on after that stop. The engine adds 2 × 11 hours = 22 hours of break at that stop. To avoid this, give the route a stop before the limit is reached. The timeWindowBreak is the part that the engine treats as hard. It fixes the window in which the rest has to fall, for example to prevent a restart before a given hour the next day. maxWorkingDuration counts breaks and waiting too. On a vehicle that works several days, size it for the whole trip. Here, PT37H is 13 hours of work, the 11-hour rest, and 13 more hours of work. A longer trip extends workingTimeWindow and maxWorkingDuration. It also needs a stop where each night’s rest can fall. See Where a break can fall.

Checking the solution

The engine applies the rule as you wrote it, inside the tour it plans. A solution can prove some things about a break, and not others. A waypoint is one line of a tour in the solution: the start, each stop, each break, and the end. What a solution shows:

A break waypoint, with arrivalTime and departureTime, shows where and when the engine placed a break. It always follows the start of the tour or a stop.
unaffectedStopIds lists the stops that the engine left out, for example because of a timeWindowBreak.

What a solution doesn’t show:

How long the break lasted. A break waypoint has no duration field. It can last longer than the break, for example when it includes a wait. Don’t read the length of the break from it. See Checking a sliding break for the one case that can be a catch-up.
Why a break waypoint is absent. The solution looks the same when the tour ended before the window opened and when it ended inside the window.
That a sliding limit was respected. A drive longer than maxInterBreakDuration has no violation. See Where a break can fall.

Example plan

This plan has one van with a 45-minute lunch break due between 12:00 and 14:00. It has two stops. The morning stop has no window. The afternoon stop opens at 15:00, so the tour runs through the lunch window.

{
  "tz": "Europe/Paris",
  "maxOptimizationDuration": "PT5S",
  "resources": [
    {
      "id": "van-1",
      "vehicleProfile": { "type": "car" },
      "workingTimeWindow": { "begin": "2026-10-29 08:00", "end": "2026-10-29 20:00" },
      "departure": { "lon": 2.35, "lat": 48.85 },
      "arrival": { "lon": 2.35, "lat": 48.85 },
      "breaks": [
        {
          "type": "timeWindowBreak",
          "duration": "PT45M",
          "timeWindow": { "begin": "2026-10-29 12:00", "end": "2026-10-29 14:00" }
        }
      ]
    }
  ],
  "orders": [
    {
      "id": "order-morning",
      "stops": [
        {
          "type": "single",
          "id": "stop-morning",
          "kind": "delivery",
          "position": { "lon": 2.36, "lat": 48.855 },
          "operationDuration": "PT10M"
        }
      ]
    },
    {
      "id": "order-afternoon",
      "stops": [
        {
          "type": "single",
          "id": "stop-afternoon",
          "kind": "delivery",
          "position": { "lon": 2.34, "lat": 48.845 },
          "operationDuration": "PT10M",
          "authorizedTimeWindows": [
            { "begin": "2026-10-29 15:00", "end": "2026-10-29 16:00" }
          ]
        }
      ]
    }
  ]
}

The same plan with the SDKs:

from kardinal.routing import models
from kardinal.routing.plans import Order, PlanCreate

depot = models.Position(lon=2.35, lat=48.85)

van = models.Resource(
    id="van-1",
    vehicleProfile=models.VehicleProfileCar(type="car"),
    workingTimeWindow=models.TimeWindow(begin="2026-10-29 08:00", end="2026-10-29 20:00"),
    departure=depot,
    arrival=depot,
    breaks=[
        models.TimeWindowBreak(
            type="timeWindowBreak",
            duration="PT45M",
            timeWindow=models.TimeWindow(begin="2026-10-29 12:00", end="2026-10-29 14:00"),
        )
    ],
)

morning = models.SingleStop(
    type="single",
    id="stop-morning",
    kind="delivery",
    position=models.Position(lon=2.36, lat=48.855),
    operationDuration="PT10M",
)

afternoon = models.SingleStop(
    type="single",
    id="stop-afternoon",
    kind="delivery",
    position=models.Position(lon=2.34, lat=48.845),
    operationDuration="PT10M",
    authorizedTimeWindows=[models.TaggedTimeWindow(begin="2026-10-29 15:00", end="2026-10-29 16:00")],
)

plan = PlanCreate(
    tz="Europe/Paris",
    maxOptimizationDuration="PT5S",
    resources=[van],
    orders=[Order(id="order-morning", stops=[morning]), Order(id="order-afternoon", stops=[afternoon])],
)

import type { PlanCreateInput } from "@kardinal-ai/sdk";

const depot = { lon: 2.35, lat: 48.85 };

const plan: PlanCreateInput = {
  tz: "Europe/Paris",
  maxOptimizationDuration: "PT5S",
  resources: [
    {
      id: "van-1",
      priority: 0,
      vehicleProfile: { type: "car" },
      workingTimeWindow: { begin: "2026-10-29 08:00", end: "2026-10-29 20:00" },
      departure: depot,
      arrival: depot,
      breaks: [
        {
          type: "timeWindowBreak",
          duration: "PT45M",
          timeWindow: { begin: "2026-10-29 12:00", end: "2026-10-29 14:00" },
        },
      ],
    },
  ],
  orders: [
    {
      id: "order-morning",
      priority: 0,
      stops: [
        {
          type: "single",
          id: "stop-morning",
          kind: "delivery",
          position: { lon: 2.36, lat: 48.855 },
          operationDuration: "PT10M",
        },
      ],
    },
    {
      id: "order-afternoon",
      priority: 0,
      stops: [
        {
          type: "single",
          id: "stop-afternoon",
          kind: "delivery",
          position: { lon: 2.34, lat: 48.845 },
          operationDuration: "PT10M",
          authorizedTimeWindows: [{ begin: "2026-10-29 15:00", end: "2026-10-29 16:00" }],
        },
      ],
    },
  ],
};

What the solution shows

The sandbox returns these waypoints for the plan, with the offset of Europe/Paris and with seconds. The other fields are left out.

{
  "resourceId": "van-1",
  "isValid": true,
  "waitingDuration": "PT2H12M48S",
  "wayPoints": [
    { "type": "begin", "departureTime": "2026-10-29T08:00:00+01:00" },
    {
      "type": "stop",
      "stopId": "stop-morning",
      "arrivalTime": "2026-10-29T08:01:06+01:00",
      "beginTime": "2026-10-29T08:01:06+01:00",
      "departureTime": "2026-10-29T08:11:06+01:00"
    },
    {
      "type": "break",
      "arrivalTime": "2026-10-29T08:11:06+01:00",
      "departureTime": "2026-10-29T12:45:00+01:00"
    },
    {
      "type": "stop",
      "stopId": "stop-afternoon",
      "arrivalTime": "2026-10-29T12:47:12+01:00",
      "beginTime": "2026-10-29T15:00:00+01:00",
      "departureTime": "2026-10-29T15:10:00+01:00"
    },
    { "type": "end", "arrivalTime": "2026-10-29T15:11:06+01:00" }
  ]
}

The break waypoint comes right after stop-morning, not in the middle of a drive.
The waypoint lasts 4 hours 33 minutes 54 seconds, for a break of 45 minutes. It can last longer than the break, for example when it includes a wait. Here the van stands from 08:11 until the window opens at 12:00, and the break ends at 12:45.
The tour is valid, and it has no violation. The solution doesn’t say that the break was owed. You know it from the plan: the tour ends at 15:11, after the window opened.
unaffectedStopIds is empty, because both stops were planned.

A check for a `timeWindowBreak`

For a timeWindowBreak, you can check each tour against the plan. The check has two steps:

If the tour ends before the window opens, no break waypoint is expected.
If the tour keeps running past the end of the window, look for a break waypoint that overlaps the window.
If the tour ends inside the window and no break waypoint appears, the result is consistent with the sandbox tours only when at least duration of the window remains after the tour ends. Otherwise, the engine would have left the stops unplaced. The rule behind this isn’t confirmed.

The check assumes that the resource has an arrival, so that the tour has an end waypoint. It also assumes that the tour starts before the window closes: for a tour that starts after the window closes, the result isn’t confirmed. Convert every time to an instant with the tz of the plan. The overlap with the window can include a wait, so the check shows that the break could fit. It doesn’t show how long the break lasted. For the example plan, the tour ends at 15:11, after the window closes at 14:00. The break waypoint runs from 08:11 to 12:45, so it overlaps the window from 12:00 to 12:45. That is 45 minutes, so the break fits. Send an explicit offset for a time close to a clock change. See Dates and time zones.

Checking a sliding break

For a sliding break, the solution can’t tell you whether the rule was respected. You measure the gaps yourself. For each tour, walk the waypoints in order. Add up the driving time or the working time between two break waypoints, and between the start of the tour and the first break. Compare each total with your own maxInterBreakDuration. Use the tz of the plan to read the times. A break waypoint longer than minBreakDuration, right after a stop, with no later time window to wait for, can be a catch-up. The formula in Where a break can fall gives its expected length. A multiple of minBreakDuration is not a sign, because a wait can be folded into the waypoint. The measuring described here is the only real check. It isn’t confirmed whether a wait at a stop counts as a break for a sliding break. It isn’t confirmed for a timeWindowBreak either. In the sandbox, the engine added a break before a long wait and another after it. To stay safe, count a wait as work, unless a break waypoint is there.

The engine’s break is not a legal break

The engine doesn’t check a law, and this guide gives no legal advice. A break that the engine plans, or leaves out, may not match a legal break. Driving done before the tour is not seen. If the plan must prove compliance, check the result against the rule that applies to your driver and your country.

Vocabulary mapping

Before modeling

Modeling business rules

Integration

Advanced modeling

Operations

Three kinds of break

One break for two rules

Where a break can fall

When a break is owed

Night rest on a multi-day trip

Checking the solution

Example plan

What the solution shows

A check for a `timeWindowBreak`

Checking a sliding break

The engine’s break is not a legal break

​Three kinds of break

​One break for two rules

​Where a break can fall

​When a break is owed

​Night rest on a multi-day trip

​Checking the solution

​Example plan

​What the solution shows

​A check for a timeWindowBreak

​Checking a sliding break

​The engine’s break is not a legal break

Three kinds of break

One break for two rules

Where a break can fall

When a break is owed

Night rest on a multi-day trip

Checking the solution

Example plan

What the solution shows

A check for a `timeWindowBreak`

Checking a sliding break

The engine’s break is not a legal break