---
title: Schedule Batch Prediction jobs
description: How to create a definition and schedule the execution of a Batch Prediction job.

---

# Schedule Batch Prediction jobs {: #schedule-batch-prediction-jobs }

After [creating a job definition](job-definitions.md), you can choose to execute job definitions on a scheduled basis instead of manually doing so through the `/batchPredictions/fromJobDefinition` endpoint.

A Scheduled Batch Prediction job works just like a regular Batch Prediction job, except DataRobot handles the execution of the job.

In order to schedule the execution of a Batch Prediction job, a definition must first be created, as described [here](job-definitions.md).

For more information about Batch Prediction REST API routes, view the [DataRobot REST API reference documentation](public-api/predictions).

<!--private start-->
You can also access the legacy [REST API documentation](https://app.datarobot.com/apidocs/index.html){ target=_blank }.
<!--private end-->

## Schedule a job definition {: #schedule-a-job-definition }

The API accepts the keywords `enabled` as well as a `schedule` object, as such:

`POST https://app.datarobot.com/api/v2/batchPredictionJobDefinitions`

```json
{
    "deploymentId": "<deployment_id>",
    "intakeSettings": {
        "type": "dataset",
        "datasetId": "<dataset_ud>"
    },
    "outputSettings": {
        "type": "jdbc",
        "statementType": "insert",
        "credentialId": "<credential_id>",
        "dataStoreId": "<data_store_id>",
        "schema": "public",
        "table": "example_table",
        "createTableIfNotExists": false
    },
    "includeProbabilities": true,
    "includePredictionStatus": true,
    "passthroughColumnsSet": "all"
    "enabled": false,
    "schedule": {
        "minute": [0],
        "hour": [1],
        "month": ["*"]
        "dayOfWeek": ["*"],
        "dayOfMonth": ["*"],
    }
}
```

### `Schedule` payload {: #schedule-payload }

The `schedule` payload defines at what intervals the job should run, which can be combined in various ways to construct complex scheduling terms if needed. In all of the elements in the objects, you can supply either an asterisk `["*"]` denoting "every" time denomination or an array of integers (e.g. `[1, 2, 3]`) to define a specific interval.

<table>
<colgroup>
   <col span="1" style="width: 20%;">
   <col span="1" style="width: 17%;">
   <col span="1" style="width: 17%;">
   <col span="1" style="width: 46%;">
</colgroup>

<thead>
  <tr>
    <th style="text-align:center;">Key</th>
    <th style="text-align:center;">Possible values</th>
    <th style="text-align:center;">Example</th>
    <th style="text-align:center;">Description</th>
  </tr>
</thead>

<tbody>
  <tr>
    <td><b>minute</b></td>
    <td><code>["*"]</code> or <code>[0 ... 59]</code></td>
    <td><code>[15, 30, 45]</code></td>
    <td>The job will run at these minute values for every hour of the day.</td>
  </tr>
  <tr>
    <td><b>hour</b></td>
    <td><code>["*"]</code> or <code>[0 ... 23]</code></td>
    <td><code>[12,23]</code></td>
    <td>The hour(s) of the day that the job will run.</td>
  </tr>
  <tr>
    <td><b>month</b></td>
    <td><code>["*"]</code> or <code>[1 ... 12]</code></td>
    <td><code>["jan"]</code></td>
    <td>
        Strings, either 3-letter abbreviations or the full name of the month, can be used interchangeably (e.g., "jan" or "october"). <br/>
        Months that are not compatible with <code>dayOfMonth</code> are ignored,
        for example <code>{"dayOfMonth": [31], "month":["feb"]}.</code>
    </td>
 </tr>
  <tr>
    <td><b>dayOfWeek</b></td>
    <td><code>["*"]</code> or <code>[0 ... 6]</code> where (Sunday=0)</td>
    <td><code>["sun"]</code></td>
    <td>
        The day(s) of the week that the job will run. Strings, either 3-letter abbreviations or the full name
        of the day, can be used interchangeably (e.g., "sunday", "Sunday", "sun", or "Sun", all map to <code>[0]</code>). <br/>
        <br />
        <strong>NOTE</strong>: This field is
        additive with <code>dayOfMonth</code>, meaning the job will run both on the date specified by
        <code>dayOfMonth</code> and the day defined in this field.
    </td>
  </tr>
  <tr>
    <td><b>dayOfMonth</b></td>
    <td><code>["*"]</code> or <code>[1 ... 31]</code></td>
    <td><code>[1, 25]</code></td>
    <td>
        The date(s) of the month that the job will run. Allowed values are either <code>[1 ... 31]</code> or <code>["*"]</code> for all
        days of the month. <br/>
        <br />
        <strong>NOTE</strong>: This field is additive with <code>dayOfWeek</code>, meaning the job will run both on the date(s)
        defined in this field and the day specified by <code>dayOfWeek</code> (for example, dates 1st, 2nd, 3rd, plus every Tuesday).
        If <code>dayOfMonth</code> is set to <code>["*"]</code> and <code>dayOfWeek</code> is defined, the scheduler will trigger on every day of
        the month that matches <code>dayOfWeek</code> (for example, Tuesday the 2nd, 9th, 16th, 23rd, 30th).
        Invalid dates such as February 31st are ignored.
    </td>
  </tr>
</tbody>
</table>

!!! note
    When specifying a time of day to run jobs, you must use UTC in the `schedule` payload&mdash;local time zones are not supported.
    To account for DST (daylight savings time), update the schedule according to your local time.

### Examples {: #examples }

<table>
<colgroup>
   <col span="1" style="width: 25%;">
   <col span="1" style="width: 50%;">
   <col span="1" style="width: 25%;">
</colgroup>

<thead>
  <tr>
    <th style="text-align:center;">Interval</th>
    <th style="text-align:center;">Example</th>
    <th style="text-align:center;">Description</th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>Run every 5 minutes</td>
    <td>

    "schedule": {
        "minute": [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55],
        "hour": ["*"],
        "month": ["*"]
        "dayOfWeek": ["*"],
        "dayOfMonth": ["*"],
    }
</td>
    <td>
        Executes every time the minute dial of a clock reaches the number(s) defined in <code>minute</code>, since all other fields are with asterisks.
    </td>
  </tr>

<tr>
    <td>Run every full hour</td>
    <td>

    "schedule": {
        "minute": [0],
        "hour": ["*"],
        "month": ["*"]
        "dayOfWeek": ["*"],
        "dayOfMonth": ["*"],
    }
</td>
    <td>
        Executes every time the clock reaches the minute(s) defined in <code>minute</code>. <br />
        <br/>
        This example executes every day at <code>1:00 AM</code>, <code>2:00 AM</code>,
        <code>3:00 AM</code>, and so forth.
    </td>
    </tr>

<tr>
    <td>Run right before noon every day</td>
    <td>

    "schedule": {
        "minute": [59],
        "hour": [11],
        "month": ["*"]
        "dayOfWeek": ["*"],
        "dayOfMonth": ["*"],
    }
</td>
    <td>
        Executes every time the minute dial of a clock reaches the minutes(s) defined in <code>minute</code>, and the
        same when the hour dial reaches the number(s) defined in <code>hour</code>. <br />
        <br/>
        This example executes every day at <code>11:59 AM</code>.
    </td>
    </tr>

<tr>
    <td>Run every full hour once every half year</td>
    <td>

    "schedule": {
        "minute": [0],
        "hour": ["*"],
        "month": [1, 6]
        "dayOfWeek": ["*"],
        "dayOfMonth": ["*"],
    }
</td>
    <td>
        Executes every time the minute dial of a clock reaches the minute(s) defined in <code>minute</code>,
        and only when the month is January (<code>1</code>) or June (<code>6</code>). </td>
    </tr>


<tr>
    <td>Run every full hour once every half year and only on Mondays and Saturdays</td>
    <td>

    "schedule": {
        "minute": [0],
        "hour": ["*"],
        "month": [1, 6]
        "dayOfWeek": ["mon", "sun"],
        "dayOfMonth": ["*"],
    }
</td>
    <td>
        Same as above, but with <code>dayOfWeek</code> specified, the interval is only executed on the days specified.
    </td>
    </tr>

<tr>
    <td>Run every full hour once every half year and only on Mondays and Saturdays, <strong>but also</strong> on the 1st and 10th of the month</td>
    <td>

    "schedule": {
        "minute": [0],
        "hour": ["*"],
        "month": [1, 6]
        "dayOfWeek": ["mon", "sun"],
        "dayOfMonth": [1, 10],
    }
</td>
    <td>
        Same as above, but with <em>both</em> <code>dayOfWeek</code> and <code>dayOfMonth</code> specified, these
        values <em>add</em> to each other, not excluding. <br />
        <br />
        This example executes on both the times defined in <code>dayOfWeek</code> and <code>dayOfMonth</code>,
        and not, as could be believed, only on those years where the 1st and 10th are Mondays and Sundays.
    </td>
    </tr>
</tbody>
</table>

## Disable a scheduled job {: #disable-a-scheduled-job }

Job definitions are only be executed by the scheduler if `enabled` is set to `True`.
If you have a job definition that was previously running as a scheduled job, but should now be stopped, simply `PATCH` the endpoint with `enabled` set to `False`.
If a job is currently running, this will finish execution regardless.

`PATCH https://app.datarobot.com/api/v2/batchPredictionJobDefinitions/<job_definition_id>`

```json
    {
        "enabled": false
    }
```

## Limitations {: #limitations }

The Scheduler has limitations set to how often a job can run and how many jobs can run at once.

### Total runs per day {: #total-runs-per-day }

Each organization is limited to a number of job executions per day.
If you are a Self-Managed AI Platform user, you can change this limitation by changing the environment variable `BATCH_PREDICTIONS_JOB_SCHEDULER_MAX_NUMBER_OF_RUNS_PER_DAY_PER_ORGANIZATION`.
On cloud, this limit is `1000` by default.

Note that the limitation is across all scheduled jobs per an organization, so if one scheduled job has a maximum run time of `1000` per day, no more scheduled jobs can be activated by that organization.

### Schedules are best-effort {: #schedules-are-best-effort }

Depending on the load of different definitions running at the same time across the organization, the scheduler cannot guarantee to execute all jobs at the exact second of the schedule. However, in most cases, the scheduler will have resources to trigger the job within 5 seconds of the schedule.

### Running the same definition simultaneously {: #running-the-same-definition-simultaneously }

One job definition cannot run more than once on a scheduled basis. This means that if a schedule job is taking long to execute, causing the next interval to trigger before the first one finished, the job will be rejected and aborted. This will continue to happen until the running job finishes.

### Automatic disablement of failing jobs {: #automatic-disablement-of-failing-jobs }

If a user has created a job definition that cannot execute due to misconfiguration and is aborted, this will cause the `enabled` feature to be auto-disabled after `5` consecutive failures.
It is therefore recommended that you use the existing `/batchPredictions` endpoint to test if the solution works, before `POST`ing the identical, confirmed working payload to the `/batchPredictionJobDefinitions`.
For Self-Managed AI Platform customers, this cut-off point of consecutive failures can be adjusted by changing the `BATCH_PREDICTIONS_JOB_SCHEDULER_FAILURES_BEFORE_ABORT` environment variable.