Job dependencies

Jobs often depend on each other in various ways. For example, a job may require the completion of another job before it can start, or there may be specific timing relationships that must be maintained between jobs. Understanding how to model these dependencies is crucial for effective scheduling and resource management.

This guide explains how to model job dependencies with the following:

Defining dependency
Preceding job dependency
Delay between dependent jobs
Dependent jobs require the same resource
No intermediate jobs

Defining dependency

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 Manage tenant, 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 Task Scheduling model.

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

Job dependencies are defined in jobs:

{
  "jobs": [
    {
      "id": "Job 1",
      "duration": "PT2H"
    },
    {
      "id": "Job 2",
      "duration": "PT3H",
      "dependencies": [
        {
          "id": "Job 1"
        }
      ]
    }
  ]
}

In this example, Job 2 cannot start until Job 1 has finished.

By default, Job 2 will start immediately after Job 1 completes.

Preceding job dependency

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 Manage tenant, 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 Task Scheduling model.

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

The Job dependency not assigned violation hard constraint is invoked when a job has a dependency on another job that is not assigned to any resource. The constraint adds a hard penalty of 1,000,000 hard score points per violation. Jobs will be left unassigned if assigning them breaks this constraint, meaning that if a job depends on another job that is not assigned, the dependent job will also be left unassigned.

Preceding job dependency example

In the following example, there is one machine and four jobs.

Machine 1 is available from 08:00.
Job A has a duration of four hours and must be completed by 10:00.
Job B has a duration of two hours and depends on the completion of Job A.
Job C has a duration of four hours.
Job D has a duration of two hours and depends on the completion of Job C.

Job A is not assigned because it cannot be completed by its deadline of 10:00. Job B is not assigned because it depends on Job A, which is not assigned. Job C is assigned to Machine 1 from 08:00 to 12:00. Job D is assigned to Machine 1 from 12:00 to 14:00, after Job C completes.

Figure 1. Preceding job dependency example

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/job-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Preceding job dependency example"
    }
  },
  "modelInput": {
    "machines": [
      {
        "id": "Machine 1",
        "start": "2027-02-01T08:00:00+00:00"
      }
    ],
    "jobs": [
      {
        "id": "Job A",
        "duration": "PT4H",
        "maxEnd": "2027-02-01T10:00:00+00:00"
      },
      {
        "id": "Job B",
        "duration": "PT2H",
        "dependencies": [
          {
            "id": "Job A",
            "anchor": "END"
          }
        ]
      },
      {
        "id": "Job C",
        "duration": "PT4H"
      },
      {
        "id": "Job D",
        "duration": "PT2H",
        "dependencies": [
          {
            "id": "Job C",
            "anchor": "END"
          }
        ]
      }

    ]
  }
}

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/job-scheduling/v1/schedules/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Preceding job dependency example",
    "submitDateTime": "2026-06-02T06:52:06.954448025Z",
    "startDateTime": "2026-06-02T06:52:11.751935289Z",
    "activeDateTime": "2026-06-02T06:52:11.908593026Z",
    "completeDateTime": "2026-06-02T06:52:42.095689817Z",
    "shutdownDateTime": "2026-06-02T06:52:42.431082524Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-2medium/-360soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "machines": [
      {
        "id": "Machine 1",
        "schedule": [
          {
            "id": "Job C",
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T12:00:00Z"
          },
          {
            "id": "Job D",
            "start": "2027-02-01T12:00:00Z",
            "end": "2027-02-01T14:00:00Z"
          }
        ]
      }
    ],
    "unassignedJobs": [
      {
        "id": "Job A"
      },
      {
        "id": "Job B"
      }
    ]
  },
  "inputMetrics": {
    "jobs": 4,
    "machines": 1,
    "employees": 0
  },
  "kpis": {
    "makespan": "PT6H",
    "unassignedJobs": 2,
    "assignedJobs": 2,
    "activatedMachines": 1,
    "activatedEmployees": 0,
    "idealEndTimeDeviation": "PT0S"
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "Preceding job dependency example",
    "submitDateTime": "2026-06-02T06:52:06.954448025Z",
    "startDateTime": "2026-06-02T06:52:11.751935289Z",
    "activeDateTime": "2026-06-02T06:52:11.908593026Z",
    "completeDateTime": "2026-06-02T06:52:42.095689817Z",
    "shutdownDateTime": "2026-06-02T06:52:42.431082524Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/-2medium/-360soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

Delay between dependent jobs

Delays are specified in the dependencies field of a job with an anchor and the minOffset and maxOffset fields, which specify the minimum and maximum time that must elapse between the preceding job and the following job.

{
  "jobs": [
    {
      "id": "Job A",
      "duration": "PT2H"
    },
    {
      "id": "Job B",
      "duration": "PT2H",
      "dependencies": [
        {
          "id": "Job A",
          "anchor": "END",
          "minOffset": "PT4H",
          "maxOffset": "PT6H"
        }
      ]
    }
  ]
}

The anchor field specifies which point of the dependency job to use as the reference point for the following job.

END (default): The following job timing is relative to the end of the preceding job.
START: The following job timing is relative to the start of the preceding job.

The Job dependency timing violation hard constraint is invoked when a job and its preceding dependency are both assigned to resources and the timing between them violates the dependency’s offset requirements.

The constraint adds a penalty to the dataset score that is calculated by the number of minutes the job’s actual scheduling violates the dependency’s offsets, incentivizing Timefold to schedule dependent jobs in the correct chronological order and within the time offsets specified by their dependencies.

Jobs will be left unassigned if assigning them breaks this constraint.

Min delay between dependent jobs example

In the following example, there is one machine and two jobs. Job B depends on Job A with a minimum offset of four hours.

Job A is assigned to Machine 1 from 08:00 to 10:00. Job B is assigned to Machine 1 from 14:00 to 16:00.

Figure 2. Delay between dependent jobs example

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/job-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Min delay between dependent jobs example"
    }
  },
  "modelInput": {
    "machines": [
      {
        "id": "Machine 1",
        "start": "2027-02-01T08:00:00+00:00"
      }
    ],
    "jobs": [
      {
        "id": "Job A",
        "duration": "PT2H"
      },
      {
        "id": "Job B",
        "duration": "PT2H",
        "dependencies": [
          {
            "id": "Job A",
            "anchor": "END",
            "minOffset": "PT4H"
          }
        ]
      }
    ]
  }
}

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/job-scheduling/v1/schedules/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Delay between dependent jobs example",
    "submitDateTime": "2026-06-02T07:52:28.823113625Z",
    "startDateTime": "2026-06-02T07:53:39.534662438Z",
    "activeDateTime": "2026-06-02T07:53:39.727904643Z",
    "completeDateTime": "2026-06-02T07:54:09.875370148Z",
    "shutdownDateTime": "2026-06-02T07:54:10.565002692Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "machines": [
      {
        "id": "Machine 1",
        "schedule": [
          {
            "id": "Job A",
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T10:00:00Z"
          },
          {
            "id": "Job B",
            "start": "2027-02-01T14:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          }
        ]
      }
    ]
  },
  "inputMetrics": {
    "jobs": 2,
    "machines": 1,
    "employees": 0
  },
  "kpis": {
    "makespan": "PT8H",
    "unassignedJobs": 0,
    "assignedJobs": 2,
    "activatedMachines": 1,
    "activatedEmployees": 0,
    "idealEndTimeDeviation": "PT0S"
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "Min delay between dependent jobs example",
    "submitDateTime": "2026-06-02T07:52:28.823113625Z",
    "startDateTime": "2026-06-02T07:53:39.534662438Z",
    "activeDateTime": "2026-06-02T07:53:39.727904643Z",
    "completeDateTime": "2026-06-02T07:54:09.875370148Z",
    "shutdownDateTime": "2026-06-02T07:54:10.565002692Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

Max delay between dependent jobs example

In the following example, there is one machine and two jobs. Job B depends on Job A with a minimum offset of 30 minutes and a maximum offset of one hour.

Job A is assigned to Machine 1 from 08:00 to 10:00. Job B is assigned to Machine 1 from 10:30 to 12:30, which is within the required offset of 30 minutes to one hour after Job A completes.

Figure 3. Minimum delay between dependent jobs example

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/job-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Max delay between dependent jobs example"
    }
  },
  "modelInput": {
    "machines": [
      {
        "id": "Machine 1",
        "start": "2027-02-01T08:00:00+00:00"
      }
    ],
    "jobs": [
      {
        "id": "Job A",
        "duration": "PT2H"
      },
      {
        "id": "Job B",
        "duration": "PT2H",
        "dependencies": [
          {
            "id": "Job A",
            "anchor": "END",
            "minOffset": "PT30M",
            "maxOffset": "PT1H"
          }
        ]
      }
    ]
  }
}

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/job-scheduling/v1/schedules/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Max delay between dependent jobs example",
    "submitDateTime": "2026-06-04T09:16:09.840975328Z",
    "startDateTime": "2026-06-04T09:16:14.495143029Z",
    "activeDateTime": "2026-06-04T09:16:14.705947497Z",
    "completeDateTime": "2026-06-04T09:16:44.867569668Z",
    "shutdownDateTime": "2026-06-04T09:16:45.228042389Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-270soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "machines": [
      {
        "id": "Machine 1",
        "schedule": [
          {
            "id": "Job A",
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T10:00:00Z"
          },
          {
            "id": "Job B",
            "start": "2027-02-01T10:30:00Z",
            "end": "2027-02-01T12:30:00Z"
          }
        ]
      }
    ]
  },
  "inputMetrics": {
    "jobs": 2,
    "machines": 1,
    "employees": 0
  },
  "kpis": {
    "makespan": "PT4H30M",
    "unassignedJobs": 0,
    "assignedJobs": 2,
    "activatedMachines": 1,
    "activatedEmployees": 0,
    "idealEndTimeDeviation": "PT0S"
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "Max delay between dependent jobs example",
    "submitDateTime": "2026-06-04T09:16:09.840975328Z",
    "startDateTime": "2026-06-04T09:16:14.495143029Z",
    "activeDateTime": "2026-06-04T09:16:14.705947497Z",
    "completeDateTime": "2026-06-04T09:16:44.867569668Z",
    "shutdownDateTime": "2026-06-04T09:16:45.228042389Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-270soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

Dependent jobs require the same resource

When one job is dependent on another job, it may be necessary for both jobs to be assigned to the same resource.

Dependency on the same resource is specified in the dependencies field of a job with the requiresSameResource field set to true:

{
  "jobs": [
    {
      "id": "Job A",
      "duration": "PT4H"
    },
    {
      "id": "Job B",
      "duration": "PT4H",
      "dependencies": [
        {
          "id": "Job A",
          "anchor": "END",
          "requiresSameResource": true
        }
      ]
    }
  ]
}

The Job dependency not assigned to the same resource violation hard constraint is invoked when a job and its preceding dependency are both assigned to resources, the dependency requires the same resource, but the two jobs are assigned to different resources.

The constraint adds a penalty of 1,000,000 hard score points to the dataset score (a fixed constant per violation), incentivizing Timefold to schedule dependent jobs that require the same resource onto the same resource.

Jobs will be left unassigned if assigning them breaks this constraint.

Dependent jobs required the same resource example

In the following example, there are two machines and two jobs. Job B depends on Job A and requires the same resource. Job A is assigned to Machine 1 from 08:00 to 12:00. Job B is assigned to Machine 1 from 12:00 to 16:00.

No jobs are assigned to Machine 2.

Figure 4. Dependent jobs required the same resource example

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/job-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "Require same resource example"
    }
  },
  "modelInput": {
    "machines": [
      {
        "id": "Machine 1",
        "start": "2027-02-01T08:00:00+00:00"
      },
      {
        "id": "Machine 2",
        "start": "2027-02-01T08:00:00+00:00"
      }
    ],
    "jobs": [
      {
        "id": "Job A",
        "duration": "PT4H"
      },
      {
        "id": "Job B",
        "duration": "PT4H",
        "dependencies": [
          {
            "id": "Job A",
            "anchor": "END",
            "requiresSameResource": true
          }
        ]
      }
    ]
  }
}

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/job-scheduling/v1/schedules/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "Require same resource example",
    "submitDateTime": "2026-06-02T08:43:00.978367507Z",
    "startDateTime": "2026-06-02T08:43:44.067736297Z",
    "activeDateTime": "2026-06-02T08:43:44.284764301Z",
    "completeDateTime": "2026-06-02T08:44:14.450397604Z",
    "shutdownDateTime": "2026-06-02T08:44:14.807873481Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "machines": [
      {
        "id": "Machine 1",
        "schedule": [
          {
            "id": "Job A",
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T12:00:00Z"
          },
          {
            "id": "Job B",
            "start": "2027-02-01T12:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          }
        ]
      },
      {
        "id": "Machine 2"
      }
    ]
  },
  "inputMetrics": {
    "jobs": 2,
    "machines": 2,
    "employees": 0
  },
  "kpis": {
    "makespan": "PT8H",
    "unassignedJobs": 0,
    "assignedJobs": 2,
    "activatedMachines": 1,
    "activatedEmployees": 0,
    "idealEndTimeDeviation": "PT0S"
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "Require same resource example",
    "submitDateTime": "2026-06-02T08:43:00.978367507Z",
    "startDateTime": "2026-06-02T08:43:44.067736297Z",
    "activeDateTime": "2026-06-02T08:43:44.284764301Z",
    "completeDateTime": "2026-06-02T08:44:14.450397604Z",
    "shutdownDateTime": "2026-06-02T08:44:14.807873481Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-480soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

No intermediate jobs

Sometimes it is necessary to ensure that when two dependent jobs are assigned to the same resource, no other jobs can be scheduled between them.

This is specified in the dependencies field of a job with the noIntermediateJobs field set to true:

{
  "jobs": [
    {
      "id": "Job A",
      "duration": "PT4H"
    },
    {
      "id": "Job B",
      "duration": "PT4H"
    },
    {
      "id": "Job C",
      "duration": "PT4H",
      "dependencies": [
        {
          "id": "Job A",
          "anchor": "END",
          "noIntermediateJobs": true
        }
      ]
    }
  ]
}

The Job dependency does not allow intermediate jobs violation hard constraint is invoked when a job and its preceding dependency are both assigned to resources, the dependency does not allow intermediate jobs, but there is at least one other job scheduled on the same resource between the two dependent jobs.

Jobs will be left unassigned if assigning them breaks this constraint.

No intermediate jobs example

In the following example, there is one machine and three jobs. Job C depends on Job A, requires the same resource, and does not allow intermediate jobs.

Job B is assigned to Machine 1 from 08:00 to 12:00. Job A is assigned to Machine 1 from 12:00 to 16:00. Job C is assigned to Machine 1 from 16:00 to 20:00. There are no intermediary jobs assigned between Job A and Job C.

Figure 5. No intermediate jobs example

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/job-scheduling/v1/schedules [email protected]

{
  "config": {
    "run": {
      "name": "No intermediate jobs example"
    }
  },
  "modelInput": {
    "machines": [
      {
        "id": "Machine 1",
        "start": "2027-02-01T08:00:00+00:00"
      }
    ],
    "jobs": [
      {
        "id": "Job A",
        "duration": "PT4H"
      },
      {
        "id": "Job B",
        "duration": "PT4H"
      },
      {
        "id": "Job C",
        "duration": "PT4H",
        "dependencies": [
          {
            "id": "Job A",
            "anchor": "END",
            "noIntermediateJobs": true
          }
        ]
      }
    ]
  }
}

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/job-scheduling/v1/schedules/<ID>

{
  "metadata": {
    "id": "ID",
    "originId": "ID",
    "name": "No intermediate jobs example",
    "submitDateTime": "2026-06-02T09:24:20.441618607Z",
    "startDateTime": "2026-06-02T09:25:09.880879508Z",
    "activeDateTime": "2026-06-02T09:25:10.087192906Z",
    "completeDateTime": "2026-06-02T09:25:40.254330759Z",
    "shutdownDateTime": "2026-06-02T09:25:40.670618956Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-720soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  },
  "modelOutput": {
    "machines": [
      {
        "id": "Machine 1",
        "schedule": [
          {
            "id": "Job B",
            "start": "2027-02-01T08:00:00Z",
            "end": "2027-02-01T12:00:00Z"
          },
          {
            "id": "Job A",
            "start": "2027-02-01T12:00:00Z",
            "end": "2027-02-01T16:00:00Z"
          },
          {
            "id": "Job C",
            "start": "2027-02-01T16:00:00Z",
            "end": "2027-02-01T20:00:00Z"
          }
        ]
      }
    ]
  },
  "inputMetrics": {
    "jobs": 3,
    "machines": 1,
    "employees": 0
  },
  "kpis": {
    "makespan": "PT12H",
    "unassignedJobs": 0,
    "assignedJobs": 3,
    "activatedMachines": 1,
    "activatedEmployees": 0,
    "idealEndTimeDeviation": "PT0S"
  },
  "run": {
    "id": "ID",
    "originId": "ID",
    "name": "No intermediate jobs example",
    "submitDateTime": "2026-06-02T09:24:20.441618607Z",
    "startDateTime": "2026-06-02T09:25:09.880879508Z",
    "activeDateTime": "2026-06-02T09:25:10.087192906Z",
    "completeDateTime": "2026-06-02T09:25:40.254330759Z",
    "shutdownDateTime": "2026-06-02T09:25:40.670618956Z",
    "solverStatus": "SOLVING_COMPLETED",
    "score": "0hard/0medium/-720soft",
    "tags": [
      "system.type:from-request",
      "system.profile:default"
    ],
    "validationResult": {
      "summary": "OK"
    }
  }
}

See the full API spec or try the online API.

Job dependencies

Defining dependency

Preceding job dependency

Preceding job dependency example

Delay between dependent jobs

Min delay between dependent jobs example

Max delay between dependent jobs example

Dependent jobs require the same resource

Dependent jobs required the same resource example

No intermediate jobs

No intermediate jobs example

Next