Recurrence Rules

Some tasks in the Tenable.io API can be scheduled to occur at defined intervals. Recurrence rules define the interval at which the task repeats. Tenable.io implements recurrence rules per the RFC-5545 specification.

The interval is formatted as a string of three (for scans) or four (for exports) values delimited by semi-colons. These values are: the frequency (FREQ=ONETIME or DAILY or WEEKLY or MONTHLY or YEARLY), the interval (INTERVAL=1 or 2 or 3 ... x), the days of the week (BYDAY=SU,MO,TU,WE,TH,FR,SA), and the end date in datetime format (UNTIL=20300101T143000).

For example, for a scan that runs every three weeks on Monday, Wednesday, and Friday, the string would be FREQ=WEEKLY;INTERVAL=3;BYDAY=MO,WE,FR. If the scan is not scheduled to recur, this attribute is null. For more information, see rrules Format

Recurrence Rule Format

Depending on the endpoint, recurrence rules are specified in the rrules or recurrence_rule parameter. These parameters supports a string value in the following format:

FREQ=value;INTERVAL=value;BYDAY=value

This format consists of the following elements:

ElementDescriptionSupported Values
FREQSpecifies how often you want the scan to repeat.Supported frequency codes are:
  • ONETIME—The scan launches a single time on the day and time specified in startime.
  • DAILY—The scan launches daily on the day and time specified in startime.
  • WEEKLY—The scan launches once a week on the day and time specified in startime.
  • MONTHLY—The scan launches once a month on the day and time specified in startime.
  • YEARLY—The scan launches once a year on the day and time specified in startime.
INTERVALSpecifies how often you want the scan to repeat.An integer representing how many of the specified unit of time should elapse between scans. For example, if you specify 3 for a weekly scan, the scan repeats every three weeks.
BYDAYSpecifies the day or days of the week on which you want the scan to repeat.Supported month codes are:
  • SU—Sunday
  • MO—Monday
  • TU—Tuesday
  • WE—Wednesday
  • TH—Thursday
  • FR—Friday
  • SA—Saturday
If you want a scan to repeat on multiple days in the same week, you can use multiple month codes in a comma-delimited list. For example:MO,WE,FR.
UNTILSpecifies the datetime of the last occurrence of the rule.A value in datetime format that indicates when the schedule should end.

Note: The UNTIL element is only valid for scheduled exports. You can not set an end date for scheduled scans, and the end date for scheduled exclusions is specified in the endtime parameter in the schedule object.

Examples

Format

Scheduled scans examples:

Scan Recurrencerrules Value
Run once on MondayFREQ=ONETIME;INTERVAL=0;BYDAY=MO
Run every week on MondayFREQ=WEEKLY;INTERVAL=1;BYDAY=MO
Run every month on the specified MondayFREQ=MONTHLY;INTERVAL=1;BYDAY=MO

Scheduled export examples:

Scan Recurrencerrules Value
Run every week on Thursday until January 1st, 2030FREQ=WEEKLY;BYDAY=TH;INTERVAL=1;UNTIL=20300101T143000
Run every month on the 30thFREQ=MONTHLY;BYMONTHDAY=30;INTERVAL=1
Run every two weeks on Monday until January 1st, 2030FREQ=WEEKLY;BYDAY=MO;INTERVAL=2;UNTIL=20300101T150000

Full Examples

For full examples including request bodies, see the following examples:


Did this page help you?