Consecutive days off per period
There are different techniques for managing employee’s time off.
This guide shows you how to include consecutive days off per period. Consecutive days off per period can be specified per week, month, or the entire schedule.
Prerequisites
Learn how to configure an API Key to run the examples in this guide:
-
Log in to Timefold Platform: app.timefold.ai
-
From the Dashboard, click your tenant, and from the drop-down menu select Tenant Settings, then choose API Keys.
-
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.
1. Define consecutive days off per period
Period rules are configured in contracts:
{
"periodRules": [
{
"id": "min3ConsecutiveDaysOff",
"period": "WEEK",
"consecutiveDaysOffLimit":
{
"consecutiveDaysOffMin": 3
},
"satisfiability": "REQUIRED"
}
]
}
periodRules
must include an ID.
period
sets the period the rule applies to, for instance, DAY
, WEEK
, MONTH
, SCHEDULE
.
Further information about period
:
DAY
spans a single day and occurs every day in the schedule.
WEEK
spans 7 days and occurs every week (including partial weeks) in the schedule.
The default start of the week is Monday, but this can be overridden to any day in the week:
{
"scheduleParameterization": {
"weekStart": "THURSDAY"
}
}
MONTH
spans the entire month.
MONTH
has a variable number of days depending on the days in the month and occurs every month (including partial months) in the schedule.
SCHEDULE
spans the entire schedule.
You can define custom periods to apply to this rule in the following way: |
{
"scheduleParameterization": {
"periods": [
{
"id": "PAY_PERIOD",
"dateSpans": [
{
"start": "2023-01-01",
"end": "2023-01-15"
}
]
}
]
}
}
The start
and end
dates are inclusive.
Learn about counting days in period rules:
By default, period rules count shifts within the defined period if the shift starts within the defined period. For instance, if you define a rule that an employee can only work 1 shift a day, a night shift that started on the previous day but ends the following morning will not be counted and another shift might be assigned on the same day as the night shift ended.
To change this behavior change the field periodShiftOverlapKind
from START_ONLY
to START_AND_END
.
{
"periodRules": [
{
"id": "Max8HoursPerDayFullTime",
"period": "DAY",
"minutesWorkedMax": 480,
"satisfiability": "REQUIRED",
"periodShiftOverlapKind": "START_AND_END"
}
}
The consecutiveDaysOffLimit
object must include consecutiveDaysOffMin
with the minimum number of consecutive days off.
The satisfiability
of the rule can be REQUIRED
or PREFERRED
.
If omitted, REQUIRED
is the default.
2. Required consecutive days off per period
When the satisfiability of the rule is REQUIRED
, the Consecutive days off per period not in required range for employee
hard constraint is invoked, which makes sure the number of consecutive days off in the period is not below the limit specified in consecutiveDaysOffMin
.
Shifts will be left unassigned if assigning them would break the Consecutive days off per period not in required range for employee
constraint.
In the following example, there are 7 shifts, but Ann’s contract has a consecutiveDaysOffMin
of 3.
She is assigned 4 shifts, 3 shift are left unassigned, and Ann has 3 consecutive days off.

-
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 days off per period example"
}
},
"modelInput": {
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "min3ConsecutiveDaysOff",
"period": "WEEK",
"consecutiveDaysOffLimit":
{
"consecutiveDaysOffMin": 3
},
"satisfiability": "REQUIRED"
}
]
}
],
"employees": [
{
"id": "Ann",
"contracts": [
"fullTimeContract"
]
}
],
"shifts": [
{
"id": "Mon",
"start": "2027-02-01T08:00:00Z",
"end": "2027-02-01T20:00:00Z"
},
{
"id": "Tue",
"start": "2027-02-02T08:00:00Z",
"end": "2027-02-02T20:00:00Z"
},
{
"id": "Wed",
"start": "2027-02-03T08:00:00Z",
"end": "2027-02-03T20:00:00Z"
},
{
"id": "Thu",
"start": "2027-02-04T08:00:00Z",
"end": "2027-02-04T20:00:00Z"
},
{
"id": "Fri",
"start": "2027-02-05T08:00:00Z",
"end": "2027-02-05T20:00:00Z"
},
{
"id": "Sat",
"start": "2027-02-06T08:00:00Z",
"end": "2027-02-06T20:00:00Z"
},
{
"id": "Sun",
"start": "2027-02-07T08:00:00Z",
"end": "2027-02-07T20: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>
{
"run": {
"id": "ID",
"name": "Required consecutive days off per period example",
"submitDateTime": "2025-05-21T05:44:56.879779049Z",
"startDateTime": "2025-05-21T05:45:10.293903708Z",
"activeDateTime": "2025-05-21T05:45:10.480841039Z",
"completeDateTime": "2025-05-21T05:45:41.356635819Z",
"shutdownDateTime": "2025-05-21T05:45:41.538578833Z",
"solverStatus": "SOLVING_COMPLETED",
"score": "0hard/-3medium/0soft",
"tags": [
"system.profile:default"
],
"validationResult": {
"summary": "OK"
}
},
"modelOutput": {
"shifts": [
{
"id": "Mon",
"employee": "Ann"
},
{
"id": "Tue",
"employee": "Ann"
},
{
"id": "Wed",
"employee": "Ann"
},
{
"id": "Thu",
"employee": "Ann"
},
{
"id": "Fri",
"employee": null
},
{
"id": "Sat",
"employee": null
},
{
"id": "Sun",
"employee": null
}
]
},
"inputMetrics": {
"employees": 1,
"shifts": 7,
"pinnedShifts": 0
},
"kpis": {
"assignedShifts": 4,
"unassignedShifts": 3,
"workingTimeFairnessPercentage": null,
"disruptionPercentage": 0.0,
"averageDurationOfEmployeesPreferencesMet": null,
"minimumDurationOfPreferencesMetAcrossEmployees": null,
"averageDurationOfEmployeesUnpreferencesViolated": null,
"maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
"activatedEmployees": 1,
"assignedMandatoryShifts": 4,
"assignedOptionalShifts": 0,
"assignedShiftGroups": null,
"unassignedShiftGroups": null,
"travelDistance": 0
}
}
modelOutput
contains the schedule with Ann assigned 4 shifts and 3 consecutive days off.
inputMetrics
provides a breakdown of the inputs in the input dataset.
KPIs
provides the KPIs for the output including:
{
"assignedShifts": 4,
"unassignedShifts": 3,
"activatedEmployees": 1,
"assignedMandatoryShifts": 4
}
3. Preferred consecutive days off per period
When the satisfiability of the rule is PREFERRED
, the Consecutive days off per period not in preferred range for employee
soft constraint is invoked.
With PREFERRED
satisfiability you can also use consecutiveDaysOffMax
to specify the maximum number of consecutive days off.
{
"periodRules": [
{
"id": "min2Max4ConsecutiveDaysOff",
"period": "WEEK",
"consecutiveDaysOffLimit":
{
"consecutiveDaysOffMin": 2,
"consecutiveDaysOffMax": 4
},
"satisfiability": "PREFERRED"
}
]
}
Ann might not get the specified number of consecutive days off if there is no alternative, but this constraint adds a soft penalty to the run score for any matches to the constraint, incentivizing Timefold to find an alternative solution.
In the following example, there are 7 shifts, but Ann’s contract has a consecutiveDaysOffMin
of 2 and a consecutiveDaysOffMax
of 4.
Ann is assigned all 7 shifts and a soft penalty is added to the run 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 days off per period example"
}
},
"modelInput": {
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "min2Max4ConsecutiveDaysOff",
"period": "WEEK",
"consecutiveDaysOffLimit":
{
"consecutiveDaysOffMin": 2,
"consecutiveDaysOffMax": 4
},
"satisfiability": "PREFERRED"
}
]
}
],
"employees": [
{
"id": "Ann",
"contracts": [
"fullTimeContract"
]
}
],
"shifts": [
{
"id": "Mon",
"start": "2027-02-01T08:00:00Z",
"end": "2027-02-01T20:00:00Z"
},
{
"id": "Tue",
"start": "2027-02-02T08:00:00Z",
"end": "2027-02-02T20:00:00Z"
},
{
"id": "Wed",
"start": "2027-02-03T08:00:00Z",
"end": "2027-02-03T20:00:00Z"
},
{
"id": "Thu",
"start": "2027-02-04T08:00:00Z",
"end": "2027-02-04T20:00:00Z"
},
{
"id": "Fri",
"start": "2027-02-05T08:00:00Z",
"end": "2027-02-05T20:00:00Z"
},
{
"id": "Sat",
"start": "2027-02-06T08:00:00Z",
"end": "2027-02-06T20:00:00Z"
},
{
"id": "Sun",
"start": "2027-02-07T08:00:00Z",
"end": "2027-02-07T20: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>
{
"run": {
"id": "ID",
"name": "Preferred consecutive days off per period example",
"submitDateTime": "2025-05-21T06:02:15.19120876Z",
"startDateTime": "2025-05-21T06:02:27.374599154Z",
"activeDateTime": "2025-05-21T06:02:27.607351296Z",
"completeDateTime": "2025-05-21T06:02:58.510711184Z",
"shutdownDateTime": "2025-05-21T06:02:58.770584101Z",
"solverStatus": "SOLVING_COMPLETED",
"score": "0hard/0medium/-1920soft",
"tags": [
"system.profile:default"
],
"validationResult": {
"summary": "OK"
}
},
"modelOutput": {
"shifts": [
{
"id": "Mon",
"employee": "Ann"
},
{
"id": "Tue",
"employee": "Ann"
},
{
"id": "Wed",
"employee": "Ann"
},
{
"id": "Thu",
"employee": "Ann"
},
{
"id": "Fri",
"employee": "Ann"
},
{
"id": "Sat",
"employee": "Ann"
},
{
"id": "Sun",
"employee": "Ann"
}
]
},
"inputMetrics": {
"employees": 1,
"shifts": 7,
"pinnedShifts": 0
},
"kpis": {
"assignedShifts": 7,
"unassignedShifts": 0,
"workingTimeFairnessPercentage": null,
"disruptionPercentage": 0.0,
"averageDurationOfEmployeesPreferencesMet": null,
"minimumDurationOfPreferencesMetAcrossEmployees": null,
"averageDurationOfEmployeesUnpreferencesViolated": null,
"maximumDurationOfUnpreferencesViolatedAcrossEmployees": null,
"activatedEmployees": 1,
"assignedMandatoryShifts": 7,
"assignedOptionalShifts": 0,
"assignedShiftGroups": null,
"unassignedShiftGroups": null,
"travelDistance": 0
}
}
modelOutput
contains the schedule with Ann assigned to all 7 shifts.
inputMetrics
provides a breakdown of the inputs in the input dataset.
KPIs
provides the KPIs for the output including:
{
"assignedShifts": 7,
"unassignedShifts": 0,
"activatedEmployees": 1,
"assignedMandatoryShifts": 7
}
Next
-
See the full API spec or try the online API.
-
Learn more about employee shift scheduling from our YouTube playlist.
-
See other options for managing employees' Time off.