Consecutive shifts worked

There are different techniques for managing employees' working hours.

For different scenarios see Work limits.

This guide shows you how to manage employees' hours with consecutive shifts worked per period, for instance, to limit the maximum number of consecutive shifts employees can be assigned to work.

Define consecutive shifts worked rules

Learn how to configure an API Key to run the examples in this guide:

  1. Log in to Timefold Platform: app.timefold.ai

  2. From the Dashboard, click your tenant, and from the drop-down menu select Manage tenant, then choose API Keys.

  3. Create a new API key or use an existing one. Ensure the list of models for the API key contains the Employee Shift Scheduling model.

In the examples, replace <API_KEY> with the API Key you just copied.

Consecutive shifts worked rules are defined in contracts.

{
  "contracts": [
    {
      "id": "NightShiftContract",
      "consecutiveShiftsWorkedRules": [
        {
          "id": "MaxConsecutiveNightShifts",
          "maximum": 5,
          "satisfiability": "REQUIRED",
          "sequenceDefinition": {
            "type": "MAX_MINUTES_BETWEEN_SHIFTS_STARTS",
            "triggerLimit": 2160
          },
          "condition": {
            "type": "MIN_SHIFTS_WORKED",
            "triggerLimit": 2,
            "includeShiftTags": ["Night"]
          }
        }
      ]
    }
  ]
}

A consecutiveShiftsWorkedRules must include an ID.

  • maximum defines the maximum number of consecutive shifts an employee with this contract can work.

  • sequenceDefinition defines the type of sequence and the trigger limit for the consecutive shifts worked rule. In this example, the type is MAX_MINUTES_BETWEEN_SHIFTS_STARTS and the trigger limit is 2160 minutes (36 hours). This means that if an employee works a shift that starts within 36 hours of the previous shift’s start time, it will be considered part of the same sequence of consecutive shifts.

  • condition defines the condition that triggers the consecutive shifts worked rule. In this example, the type is MIN_SHIFTS_WORKED, the trigger limit is 2, and it includes shifts with the tag Night. This means that the consecutive shifts worked rule will only be triggered if at least 2 of the consecutive shifts have the tag Night.

Filter shifts with tags

consecutiveShiftsWorkedRules can include or exclude shifts based on tags.

{
  "contracts": [
    {
      "id": "NightShiftContract",
      "consecutiveShiftsWorkedRules": [
        {
          "id": "MaxConsecutiveNightShifts",
          "maximum": 5,
          "satisfiability": "REQUIRED",
          "includeShiftTags": [
            "Night"
          ],
          "shiftTagMatches": "ALL",
          "sequenceDefinition": {
            "type": "MAX_MINUTES_BETWEEN_SHIFTS_STARTS",
            "triggerLimit": 2160
          }
        }
      ]
    }
  ]
}
Further information about including or excluding shifts with shift tags:

Shifts with specific tags can be included or excluded by the rule. Tags are defined in shifts:

{
  "shifts": [
    {
      "id": "2027-02-01",
      "start": "2027-02-01T09:00:00Z",
      "end": "2027-02-01T17:00:00Z",
      "tags": ["Part-time"]
    }
  ]
}

Use includeShiftTags to include shifts with specific tags or excludeShiftTags to exclude shifts with specific tags.

shiftTagMatches can be set to ALL or ANY. The default behavior for shiftTagMatches is ALL, and if omitted, the default ALL will be used.

The rule can define either includeShiftTags or excludeShiftTags, but not both.

{
  "includeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s includeShiftTags attribute must be present in the shift. With shiftTagMatches set to ANY, at least one tag defined by the rule’s includeShiftTags attribute must be present in the shift.

{
  "excludeShiftTags": ["Part-time", "Weekend"],
  "shiftTagMatches": "ALL"
}

With shiftTagMatches set to ALL, all tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you want to exclude things in combination with each other. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to All, will exclude shifts that include the tags Part-time and Weekend from the rule. Shifts tagged only Part-time or only Weekend will not be excluded.

With shiftTagMatches set to ANY, any of the tags defined by the rule’s excludeShiftTags attribute cannot be present in the shift. This is useful when you need to exclude tags regardless of their relationship to other tags. For instance, excluding the shift tags Part-time and Weekend with shiftTagMatches set to ANY, will exclude any shift that includes the tags Part-time or Weekend, whether they occur together or not.

Because the consecutiveShiftsWorkedRules can define includeShiftTags and excludeShiftTags and the rule’s condition can define includeShiftTags, you should be careful not to create scenarios that will never be met. For example, if the rule excludeShiftTags defines Night, the condition defines includeShiftTags as Night, then the rule will never be triggered because no shift will be included in the condition check

{
  "contracts": [
    {
      "id": "NightShiftContract",
      "consecutiveShiftsWorkedRules": [
        {
          "id": "MaxConsecutiveNightShifts",
          "maximum": 5,
          "satisfiability": "REQUIRED",
          "excludeShiftTags": [
            "Night"
          ],
          "condition": {
            "type": "MIN_SHIFTS_WORKED",
            "triggerLimit": 2,
            "includeShiftTags": [
              "Night"
            ]
          },
          "sequenceDefinition": {
            "type": "MAX_MINUTES_BETWEEN_SHIFTS_STARTS",
            "triggerLimit": 2160
          }
        }
      ]
    }
  ]
}

Rule satisfiability

The satisfiability of the rule can be REQUIRED or PREFERRED. If omitted, REQUIRED is the default.

Required consecutive shifts worked

When the satisfiability of the rule is REQUIRED, the Consecutive shifts worked not in required range for employee hard constraint is invoked, which makes sure the number of consecutive shifts does not exceed the limit specified in maximum.

Shifts will be left unassigned if assigning them would break the Consecutive shifts worked not in required range for employee constraint.

Required consecutive shifts worked example

In the following example, there are five shifts and one employee. Beth has a contract that allows them to work a required maximum of three consecutive shifts if she works a night shift. The sequenceDefinition specifies shifts are consecutive if they start within 24 hours of each other.

Beth is assigned three consecutive shifts and one shift is left unassigned.

  • Input

  • Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]
{
  "config": {
    "run": {
      "name": "Required consecutive shifts worked example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "consecutiveShiftsWorkedRules": [
          {
            "id": "Max3ConsecutiveShiftsIfOneIsANightShift",
            "maximum": 3,
            "satisfiability": "REQUIRED",
            "sequenceDefinition": {
              "triggerLimit": 1440,
              "type": "MAX_MINUTES_BETWEEN_SHIFTS_STARTS"
            },
            "condition": {
              "type": "MIN_SHIFTS_WORKED",
              "triggerLimit": 1,
              "includeShiftTags": [
                "Night"
              ]
            }
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T20:00:00Z",
        "end": "2027-02-02T04:00:00Z",
        "tags": [
          "Night"
        ]
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z"
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z"
      }
    ]
  }
}
To request the solution, locate the ID from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>
{
  "metadata": {
    "id": "df8e6f07-f8dd-49ab-8d0c-7a2296fd3ff6",
    "originId": "df8e6f07-f8dd-49ab-8d0c-7a2296fd3ff6",
    "name": "Required consecutive shifts worked example",
    "submitDateTime": "2026-04-13T10:32:21.590421+02:00",
    "startDateTime": "2026-04-13T10:32:21.601065+02:00",
    "activeDateTime": "2026-04-13T10:32:21.601493+02:00",
    "completeDateTime": "2026-04-13T10:32:51.606807+02:00",
    "shutdownDateTime": "2026-04-13T10:32:51.606811+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      },
      {
        "id": "Tue",
        "employee": "Beth"
      },
      {
        "id": "Wed",
        "employee": "Beth"
      },
      {
        "id": "Thu"
      },
      {
        "id": "Fri",
        "employee": "Beth"
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 4,
          "durationWorked": "PT32H"
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0,
    "mandatoryShifts": 5,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 4,
    "unassignedShifts": 1,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 4
  },
  "run": {
    "id": "df8e6f07-f8dd-49ab-8d0c-7a2296fd3ff6",
    "originId": "df8e6f07-f8dd-49ab-8d0c-7a2296fd3ff6",
    "name": "Required consecutive shifts worked example",
    "submitDateTime": "2026-04-13T10:32:21.590421+02:00",
    "startDateTime": "2026-04-13T10:32:21.601065+02:00",
    "activeDateTime": "2026-04-13T10:32:21.601493+02:00",
    "completeDateTime": "2026-04-13T10:32:51.606807+02:00",
    "shutdownDateTime": "2026-04-13T10:32:51.606811+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-1medium/0soft",
    "validationResult": {
      "summary": "OK"
    }
  }
}

Preferred consecutive shifts worked

When the satisfiability of the rule is PREFERRED, the Consecutive shifts worked not in preferred range for employee soft constraint is invoked.

With a satisfiability of PREFERRED a maximum value can be provided to set the maximum number of consecutive shifts an employee can be assigned.

{
  "contracts": [
    {
      "id": "FullTimeContract",
      "consecutiveShiftsWorkedRules": [
        {
          "id": "Min2Max3ConsecutiveShifts",
          "maximum": 3,
          "satisfiability": "PREFERRED"
        }
      ]
    }
  ]
}

The Consecutive shifts worked not in preferred range for employee soft constraint is invoked when satisfiability is PREFERRED and an employee’s consecutive worked-shift sequence is more than maximum.

The constraint adds a soft penalty to the dataset score that is calculated as the number of shifts outside the preferred range multiplied by the employee priority multiplier and the contract’s priority weight, normalized to minutes, incentivizing Timefold to keep consecutive shifts worked within preferred limits.

Shifts will still be assigned even if assigning them breaks this constraint.

Every soft constraint has a weight that can be configured to change the relative importance of the constraint compared to other constraints.

Learn about constraint weights.
This rule is more likely to be satisfied for employees with a higher employee priority. See Employee priority for more details.

Preferred consecutive shifts worked example

In the following example, there are five shifts and one employee. Beth has a contract that allows them to work a preferred maximum of three consecutive shifts if she works a night shift. The sequenceDefinition specifies shifts are consecutive if they start within 24 hours of each other.

Beth is assigned all five consecutive shifts and a soft penalty is applied to the dataset score.

  • Input

  • Output

Try this example in Timefold Platform by saving this JSON into a file called sample.json and make the following API call: 
curl -X POST -H "Content-type: application/json" -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules [email protected]
{
  "config": {
    "run": {
      "name": "Preferred consecutive shifts worked example"
    }
  },
  "modelInput": {
    "contracts": [
      {
        "id": "fullTimeContract",
        "consecutiveShiftsWorkedRules": [
          {
            "id": "Max3ConsecutiveShiftsIfOneIsANightShift",
            "maximum": 3,
            "satisfiability": "PREFERRED",
            "sequenceDefinition": {
              "triggerLimit": 1440,
              "type": "MAX_MINUTES_BETWEEN_SHIFTS_STARTS"
            },
            "condition": {
              "type": "MIN_SHIFTS_WORKED",
              "triggerLimit": 1,
              "includeShiftTags": [
                "Night"
              ]
            }
          }
        ]
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "contracts": [
          "fullTimeContract"
        ]
      }
    ],
    "shifts": [
      {
        "id": "Mon",
        "start": "2027-02-01T20:00:00Z",
        "end": "2027-02-02T04:00:00Z",
        "tags": [
          "Night"
        ]
      },
      {
        "id": "Tue",
        "start": "2027-02-02T09:00:00Z",
        "end": "2027-02-02T17:00:00Z"
      },
      {
        "id": "Wed",
        "start": "2027-02-03T09:00:00Z",
        "end": "2027-02-03T17:00:00Z"
      },
      {
        "id": "Thu",
        "start": "2027-02-04T09:00:00Z",
        "end": "2027-02-04T17:00:00Z"
      },
      {
        "id": "Fri",
        "start": "2027-02-05T09:00:00Z",
        "end": "2027-02-05T17:00:00Z"
      }
    ]
  }
}
To request the solution, locate the ID from the response to the post operation and append it to the following API call: 
curl -X GET -H 'X-API-KEY: <API_KEY>' https://app.timefold.ai/api/models/employee-scheduling/v1/schedules/<ID>
{
  "metadata": {
    "id": "20159956-f814-41ab-9696-b05ccbf4daf7",
    "originId": "20159956-f814-41ab-9696-b05ccbf4daf7",
    "name": "Preferred consecutive shifts worked example",
    "submitDateTime": "2026-04-13T10:40:14.440929+02:00",
    "startDateTime": "2026-04-13T10:40:14.481294+02:00",
    "activeDateTime": "2026-04-13T10:40:14.48177+02:00",
    "completeDateTime": "2026-04-13T10:40:44.487597+02:00",
    "shutdownDateTime": "2026-04-13T10:40:44.487601+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1920soft",
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "shifts": [
      {
        "id": "Mon",
        "employee": "Beth"
      },
      {
        "id": "Tue",
        "employee": "Beth"
      },
      {
        "id": "Wed",
        "employee": "Beth"
      },
      {
        "id": "Thu",
        "employee": "Beth"
      },
      {
        "id": "Fri",
        "employee": "Beth"
      }
    ],
    "employees": [
      {
        "id": "Beth",
        "metrics": {
          "assignedShifts": 5,
          "durationWorked": "PT40H"
        }
      }
    ]
  },
  "inputMetrics": {
    "employees": 1,
    "shifts": 5,
    "pinnedShifts": 0,
    "mandatoryShifts": 5,
    "optionalShifts": 0
  },
  "kpis": {
    "assignedShifts": 5,
    "unassignedShifts": 0,
    "disruptionPercentage": 0.0,
    "activatedEmployees": 1,
    "assignedMandatoryShifts": 5
  },
  "run": {
    "id": "20159956-f814-41ab-9696-b05ccbf4daf7",
    "originId": "20159956-f814-41ab-9696-b05ccbf4daf7",
    "name": "Preferred consecutive shifts worked example",
    "submitDateTime": "2026-04-13T10:40:14.440929+02:00",
    "startDateTime": "2026-04-13T10:40:14.481294+02:00",
    "activeDateTime": "2026-04-13T10:40:14.48177+02:00",
    "completeDateTime": "2026-04-13T10:40:44.487597+02:00",
    "shutdownDateTime": "2026-04-13T10:40:44.487601+02:00",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-1920soft",
    "validationResult": {
      "summary": "OK"
    }
  }
}

Managing overtime

Rules with a satisfiability of REQUIRED put a hard limit on how much work employees can be assigned (minutes, hours, days, shifts), and doesn’t assign overtime.

A rule with a satisfiability of REQUIRED that states an employee can work a maximum of 4 consecutive shifts, will never assign the employee more than 4 consecutive shifts, even if assigning overtime would be beneficial to the overall schedule.

To allow for the possibility of overtime, use rules with a satisfiability of PREFERRED.

Set a rule with a PREFERRED satisfiability for the maximum number of consecutive shifts. Now, a rule with a satisfiability of PREFERRED that states an employee can preferably work a maximum of 4 consecutive shifts will allow the employee to be assigned more consecutive shifts (overtime) than specified by the rule when it is necessary to do so.

To place a limit on the total amount of overtime employees can be assigned, include both:

  • A rule with PREFERRED satisfiability for the maximum number of consecutive shifts that is equivalent to the employees normal consecutive shifts.

  • A rule with REQUIRED satisfiability for the maximum number of consecutive shifts (regular hours plus overtime).

The difference between the PREFERRED maximum consecutive shifts and REQUIRED maximum consecutive shifts is the total amount of overtime that can be assigned to employees.

Next