Manage job schedules

Use schedule management methods to schedule certain types of periodic operations that run in your cluster.

Job schedule

A job schedule describes the interval at which to run a job, the type of job, and the parameters defining the job scope.

A job schedule has the following form:

{
    "first_run_date": FIRST_RUN_DATE,
    "first_run_time": FIRST_RUN_TIME,
    "timezone": TIMEZONE,
    "interval": INTERVAL,
    "interval_unit": INTERVAL_UNIT,
    "job_params": {
      type: backup | best-practice,
      JOB_PARAMS,
    },
    "id": ID,
    "next_run": NEXT_RUN,
    "last_run": LAST_RUN
}

The job schedule fields are:

Field Type Description

first_run_date

string

The first date on which to run the job in YYYY-MM-DD format.

first_run_time

string

The first time on which to run the job in hh:mm:ss format.

timezone

string

The time zone, listed in the OpsCenter /meta/timezones directory, for the job schedule. For example, GMT, US/Central, US/Pacific, or US/Eastern.

interval

integer

Sets the frequency at which the job runs.

Specifies the number of time units (interval_unit) between job executions. For example, to run a job every two weeks, set "interval": 2,"interval_unit": "weeks".

interval_unit

string

The unit of time for interval. Allowed values are minutes, hours, days, or weeks.

job_params

dict

A dictionary that describes the job.

The type field is required. Allowed values are best-practice and backup. Additional fields within job_params depend on the type.

If type is best-practice the only additional field is rules, which is a JSON list of rules to run on the given schedule. At least one rule must be specified.

  "job_params": {
    "type": "best-practice",
    "rules": [ "RULE_1", "RULE_2" ]
  },

If type is backup, the following additional fields are included. If any of these fields are not set, the defaults are used.

  • keyspaces: A JSON list containing the names of keyspaces to backup. To include all keyspaces, set to an empty list or null.

  • cleanup_age: Sets the backup retention period to automatically delete old backups.

    If set to 0 (default), backup cleanup is disabled. If set to a positive integer, backup cleanup is enabled with the time unit set by cleanup_age_unit. For example, to delete backups older than two weeks, set "cleanup_age": 2,"cleanup_age_unit": "weeks".

  • cleanup_age_unit: The unit of time for cleanup_age. Allowed values are minutes, hours, days (default), or weeks.

  • pre_snapshot_script: The name of a custom script file to run prior to creating each backup. This file must exist within the bin/backup-scripts/ directory where the OpsCenter agent is installed. The file name can contain only letters, numbers, underscores, and hyphens.

  • post_snapshot_script: The name of a custom script file to run after each backup is taken. This file must exist within the bin/backup-scripts/ directory where the OpsCenter agent is installed. The file name can contain only letters, numbers, underscores, and hyphens.

    For interaction with the backup job, the name of each file included in a backup is passed to the script through stdin .

  • datacenters: A JSON list containing the names of the datacenters where the backup should run. To include all datacenters, set to an empty list or null.

  • destinations: A JSON object representing destinations for backup storage. The key is a destination ID returned by /{cluster_id}/backups/destinations, and the value is a JSON object with parameters specific to the given destination. For example, specify retention time for a specific destination with the cleanup_age and cleanup_age_unit parameters or set compression with the compressed boolean. Multiple destination keys can be set in the destinations object.

  • alert_on_failure: Whether an alert is triggered on backup failure. The default is false (disabled).

  • retries: The number of retries to attempt before reporting a backup as failed. The default is 0 (no retries).

  "job_params": {
    "type": "backup",
    "keyspaces": KEYSPACES,
    "cleanup_age": CLEANUP_AGE,
    "cleanup_age_unit": CLEANUP_AGE_UNIT,
    "pre_snapshot_script": PRE_SNAPSHOT_SCRIPT,
    "post_snapshot_script": POST_SNAPSHOT_SCRIPT,
    "datacenters": DATACENTERS,
    "destinations": DESTINATIONS,
    "alert_on_failure": ALERT_ON_FAILURE,
    "cleanup_dests": CLEANUP_DESTS,
    "retries": RETRIES
  },

id

string

A unique ID that references a job schedule.

When creating a job schedule, omit this field. The system assigns an ID when the job schedule is created.

When you GET,PUT, or DELETE a job schedule, use the ID to reference the specific job schedule.

next_run

string

The date and time of the next scheduled run.

This field is always system-defined. Omit this field from your POST and PUT requests.

last_run

string

The date and time of the last successful run.

This field is always system-defined. Omit this field from your POST and PUT requests.

GET /{cluster_id}/job-schedules

Retrieve a list of jobs scheduled to run in OpsCenter. Currently the only types of jobs are a scheduled backup or a best practice rule.

Path arguments:

Returns a list of job-schedule objects.

Example:

curl http://127.0.0.1:8888/Test_Cluster/job-schedules

Output:

[
  {
    "first_run_date": "2012-04-19",
    "first_run_time": "18:00:00",
    "id": "19119720-115a-4f2c-862f-e10e1fb90eed",
    "interval": 1,
    "interval_unit": "days",
    "job_params": {
      "cleanup_age": 30,
      "cleanup_age_unit": "days",
      "keyspaces": [],
      "type": "backup"
    },
    "last_run": "2012-04-20 18:00:00 GMT",
    "next_run": "2012-04-21 18:00:00 GMT",
    "timezone": "GMT"
  },
  ...
]

GET /{cluster_id}/job-schedules/{schedule_id}

Get the description of a scheduled job.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • schedule_id: A unique ID of the scheduled job that matches the id of a job-schedule object.

Returns a Job Schedule object.

POST /{cluster_id}/job-schedules

Create a new scheduled job. You can create a scheduled job to run one time in the future by specifying an interval of -1 and interval_unit of null.

Path arguments:

Body: A dictionary in the format of a Job Schedule describing the scheduled job to create. Don’t include the id, last_run, and next_run fields; these are set by the system when the job schedule is created and triggered.

Returns 201 response code and the ID of the newly created job if successful.

Example:

curl -X POST
  http://127.0.0.1:8888/Test_Cluster/job-schedules/
  -d
  '{
    "first_run_date": "2012-05-03",
    "first_run_time": "18:00:00",
    "interval": 1,
    "interval_unit": "days",
    "job_params": {
        "cleanup_age": 30,
        "cleanup_age_unit": "days",
        "keyspaces": [],
        "type": "backup"
    },
    "timezone": "GMT"
  }'

Output:

"905391b7-1920-486d-a633-282f22dce604"

PUT /{cluster_id}/job-schedules/{schedule_id}

Update a scheduled job.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • schedule_id: A unique ID identifying the schedule job to update.

Body: A dictionary with fields from the job-schedule object that you want to update.

Returns 200 response code and a null message if the schedule was updated successfully.

Example:

curl -X PUT
  http://127.0.0.1:8888/Test_Cluster/job-schedules/905391b7-1920-486d-a633-282f22 dce604
  -d
  '{
    "interval": "12",
    "interval_unit": "hours"
  }'

DELETE /{cluster_id}/job-schedules/{schedule_id}

Delete a scheduled job.

Path arguments:

  • cluster_id: The ID of a cluster returned from GET /cluster-configs.

  • schedule_id: A unique ID identifying the schedule job to delete.

Returns 200 response code and a null message if the schedule was deleted successfully.

Example:

curl -X DELETE
  http://127.0.0.1:8888/Test_Cluster/job-schedules/905391b7-1920-486d-a633-282f22 dce604

Was this helpful?

Give Feedback

How can we improve the documentation?

© Copyright IBM Corporation 2026 | Privacy policy | Terms of use |  Manage Privacy Choices

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: Contact IBM