Weekends worked per period
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 weekends worked per period. This puts a limit on how many weekends employees can work in a period, for instance, if employees should only work one weekend throughout a period of one month.
Period rules for weekends can be defined for a 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 weekends worked per period
Period rules are defined in contracts:
{
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "Max1WeekendPerMonth",
"period": "MONTH",
"weekendsLimit":
{
"weekendsWorkedMax": 1
},
"satisfiability": "REQUIRED"
}
]
}
]
}
Period rules can define how many weekends employees work in a given period, for instance, 1 weekend per month.
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.
weekendsLimit rules can only be defined for periods MONTH or SCHEDULE .
|
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 weekendsLimit
object must include weekendsWorkedMax
with the maximum number of weekend worked per period.
periodRules
can include or exclude shifts based on shift tags.
{
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "Max1WeekendPerMonth",
"period": "MONTH",
"includeShiftTags": ["Part-time"],
"shiftTagMatches": "ALL",
"weekendsLimit":
{
"weekendsWorkedMax": 1
},
"satisfiability": "REQUIRED"
}
]
}
]
}
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.
Each employee must specify which contracts apply to them:
{
"employees": [
{
"id": "Ann",
"contracts": [
"fullTimeContract"
]
}
]
}
The satisfiability
can be REQUIRED
or PREFERRED
.
If omitted, REQUIRED
is the default.
2. Required weekends worked per period
When the satisfiability of the rule is REQUIRED
, the Weekends worked per period not in required range for employee
hard constraint is invoked, which makes sure the number of weekends worked per period does not exceed the limit specified in weekendsWorkedMax
.
Shifts will be left unassigned if assigning them would break the Weekends worked per period not in required range for employee
constraint.
In the following example, there are 8 shifts, 1 employee, and a rule with a required satisfiability that specifies the employee can work at most 1 weekend per month.
Only the weekend shifts are shown in the example. |
2 shifts on 1 weekend are assigned and 6 shifts are left unassigned to avoid breaking the Weekends worked per period not in required range for employee
hard constraint.

-
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 weekends worked per period example"
}
},
"modelInput": {
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "Max1WeekendPerMonth",
"period": "MONTH",
"weekendsLimit":
{
"weekendsWorkedMax": 1
},
"satisfiability": "REQUIRED"
}
]
}
],
"employees": [
{
"id": "Ann",
"contracts": [
"fullTimeContract"
]
}
],
"shifts": [
{
"id": "Sat 6",
"start": "2027-02-06T09:00:00Z",
"end": "2027-02-06T17:00:00Z"
},
{
"id": "Sun 7",
"start": "2027-02-07T09:00:00Z",
"end": "2027-02-07T17:00:00Z"
},
{
"id": "Sat 13",
"start": "2027-02-13T09:00:00Z",
"end": "2027-02-13T17:00:00Z"
},
{
"id": "Sun 14",
"start": "2027-02-14T09:00:00Z",
"end": "2027-02-14T17:00:00Z"
},
{
"id": "Sat 20",
"start": "2027-02-20T09:00:00Z",
"end": "2027-02-20T17:00:00Z"
},
{
"id": "Sun 21",
"start": "2027-02-21T09:00:00Z",
"end": "2027-02-21T17:00:00Z"
},
{
"id": "Sat 27",
"start": "2027-02-27T09:00:00Z",
"end": "2027-02-27T17:00:00Z"
},
{
"id": "Sun 28",
"start": "2027-02-28T09:00:00Z",
"end": "2027-02-28T17: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 weekends worked per period example",
"submitDateTime": "2025-06-13T05:45:08.168062776Z",
"startDateTime": "2025-06-13T05:45:26.111472225Z",
"activeDateTime": "2025-06-13T05:45:26.258624032Z",
"completeDateTime": "2025-06-13T05:45:57.168793571Z",
"shutdownDateTime": "2025-06-13T05:45:57.405050134Z",
"solverStatus": "SOLVING_COMPLETED",
"score": "0hard/-6medium/0soft",
"tags": [
"system.profile:default"
],
"validationResult": {
"summary": "OK"
}
},
"modelOutput": {
"shifts": [
{
"id": "Sat 6",
"employee": "Ann"
},
{
"id": "Sun 7",
"employee": "Ann"
},
{
"id": "Sat 13"
},
{
"id": "Sun 14"
},
{
"id": "Sat 20"
},
{
"id": "Sun 21"
},
{
"id": "Sat 27"
},
{
"id": "Sun 28"
}
]
},
"inputMetrics": {
"employees": 1,
"shifts": 8,
"pinnedShifts": 0
},
"kpis": {
"assignedShifts": 2,
"unassignedShifts": 6,
"disruptionPercentage": 0.0,
"activatedEmployees": 1,
"assignedMandatoryShifts": 2,
"assignedOptionalShifts": 0,
"travelDistance": 0
}
}
modelOutput
contains the schedule with 2 shifts assigned on 1 weekend and 6 shifts unassigned.
inputMetrics
provides a breakdown of the inputs in the input dataset.
KPIs
provides the KPIs for the output including:
{
"assignedShifts": 2,
"unassignedShifts": 6,
"activatedEmployees": 1,
"assignedMandatoryShifts": 2
}
3. Preferred weekends worked per period
When the satisfiability of the rule is PREFERRED
, the Weekends worked per period not in preferred range for employee
soft constraint is invoked.
{
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "Max1WeekendPerMonth",
"period": "MONTH",
"weekendsLimit":
{
"weekendsWorkedMax": 1
},
"satisfiability": "PREFERRED"
}
]
}
]
}
Shifts will be assigned to employees even if the shifts take the employee’s weekends worked over the limit specified by weekendsWorkedMax
, however, 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 8 shifts, 1 employee, and a rule with a preferred satisfiability that specifies the employee should work at most 1 weekend per month.
All 8 shifts are assigned, and a soft penalty is applied to the score run.

-
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 weekends worked per period example"
}
},
"modelInput": {
"contracts": [
{
"id": "fullTimeContract",
"periodRules": [
{
"id": "Max1WeekendPerMonth",
"period": "MONTH",
"weekendsLimit":
{
"weekendsWorkedMax": 1
},
"satisfiability": "PREFERRED"
}
]
}
],
"employees": [
{
"id": "Ann",
"contracts": [
"fullTimeContract"
]
}
],
"shifts": [
{
"id": "Sat 6",
"start": "2027-02-06T09:00:00Z",
"end": "2027-02-06T17:00:00Z"
},
{
"id": "Sun 7",
"start": "2027-02-07T09:00:00Z",
"end": "2027-02-07T17:00:00Z"
},
{
"id": "Sat 13",
"start": "2027-02-13T09:00:00Z",
"end": "2027-02-13T17:00:00Z"
},
{
"id": "Sun 14",
"start": "2027-02-14T09:00:00Z",
"end": "2027-02-14T17:00:00Z"
},
{
"id": "Sat 20",
"start": "2027-02-20T09:00:00Z",
"end": "2027-02-20T17:00:00Z"
},
{
"id": "Sun 21",
"start": "2027-02-21T09:00:00Z",
"end": "2027-02-21T17:00:00Z"
},
{
"id": "Sat 27",
"start": "2027-02-27T09:00:00Z",
"end": "2027-02-27T17:00:00Z"
},
{
"id": "Sun 28",
"start": "2027-02-28T09:00:00Z",
"end": "2027-02-28T17: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 weekends worked per period example",
"submitDateTime": "2025-06-13T06:02:11.439168397Z",
"startDateTime": "2025-06-13T06:02:29.693348694Z",
"activeDateTime": "2025-06-13T06:02:29.876484365Z",
"completeDateTime": "2025-06-13T06:03:00.924300437Z",
"shutdownDateTime": "2025-06-13T06:03:01.193540069Z",
"solverStatus": "SOLVING_COMPLETED",
"score": "0hard/0medium/-2880soft",
"tags": [
"system.profile:default"
],
"validationResult": {
"summary": "OK"
}
},
"modelOutput": {
"shifts": [
{
"id": "Sat 6",
"employee": "Ann"
},
{
"id": "Sun 7",
"employee": "Ann"
},
{
"id": "Sat 13",
"employee": "Ann"
},
{
"id": "Sun 14",
"employee": "Ann"
},
{
"id": "Sat 20",
"employee": "Ann"
},
{
"id": "Sun 21",
"employee": "Ann"
},
{
"id": "Sat 27",
"employee": "Ann"
},
{
"id": "Sun 28",
"employee": "Ann"
}
]
},
"inputMetrics": {
"employees": 1,
"shifts": 8,
"pinnedShifts": 0
},
"kpis": {
"assignedShifts": 8,
"unassignedShifts": 0,
"disruptionPercentage": 0.0,
"activatedEmployees": 1,
"assignedMandatoryShifts": 8,
"assignedOptionalShifts": 0,
"travelDistance": 0
}
}
modelOutput
contains the schedule with all 8 shifts assigned to Ann.
inputMetrics
provides a breakdown of the inputs in the input dataset.
KPIs
provides the KPIs for the output including:
{
"assignedShifts": 8,
"activatedEmployees": 1,
"assignedMandatoryShifts": 8
}
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' work hours: Work limits.