Was this topic helpful?
The Scheduled Scans API(/msp/scheduled_scans.php) is used to add, list, and remove scheduled scan and map tasks on the Qualys server. Scheduled tasks can be defined to run daily, weekly, and monthly. The Qualys service automatically starts the scheduled tasks according to their specifications.
Express Lite: This API is available to Express Lite users.
The scheduled_scans.php function applies the default option profile in the user account to a scheduled task, unless another profile is specified for the task using the option={name} parameter.
Each scheduled task runs in the local time defined for the task. You have the option to specify the local time as a time zone code or as a GMT shift value. When a time zone code that supports Daylight Saving Time (DST) is specified in the time_zone_code parameter with observe_dst=yes, the task observes DST by automatically adjusting the task’s run time to reflect local time.
The Qualys service assigns a task ID to each scheduled task when the scheduled task is added. This task ID can be used to delete the scheduled task as described below in “Remove Task.”
Each time a scheduled task successfully completes, the API user receives an email notification with scan or map results, unless this notification option is disabled in the user account. This email includes summary information plus a link to the detailed scan or map report. These results may also be returned using the scan_report_list.php and scan_report.php functions.
The reports produced by scheduled scans and maps are saved on the Qualys server. A scan report can be retrieved using the scan_report.php function. A map report can be retrieved using the map_report.php function. A report for a scheduled scan or map can be removed using the scan_report_delete.php function. The scan_report_list.php function lists reports for scheduled scans and maps.
Important: The scheduled_scans.php function does not check for validity of IP addresses and other task settings until run time — the first time the scheduled task is initiated. For example, in a case where you submit a request to add a new scheduled scan with an invalid IP address, the scheduled_scans.php function will create the new task without error or warning. Then, at run time the Qualys service will send an email notification stating “This scheduled task has been deactivated,” with a reason for the deactivation. This email is sent to the registered Qualys user of the account.
The type parameter specifies the scheduled task type. When this parameter is not set, the default is type=scan for a scheduled scan.
Use the type=map parameter to add a scheduled map or request a list of scheduled maps. For example, to request a list of scheduled maps, use this URL: https://qualysapi.qualys.com/msp/scheduled_scans.php?type=map.
Use the type=all parameter to request a list of scheduled scans and maps together.
The task target is defined using the scan_target and asset_groups parameters. For a scan task, you may specify a combination of IP addresses, IP address ranges, and asset groups. For a map task, you may specify a combination of domain names and asset groups.
The scan_target parameter is used to specify the target for a new scheduled scan or map. To add a scan task on IP addresses using the external scanner, use this URL: https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=yes&type=scan&scan_target={addresses}
To add a map task on two domains using a scanner appliance, use this URL: https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y es&type=map&scan_target={domain1,domain2}&iscanner_name=name.
Use the asset_groups={title1,title2...} parameter to specify asset groups for a task target.
For each scan a scanner is applied to the task. External scanning at the network perimeter is supported by the Qualys external scanners, and internal scanning of private use internal IPs is supported using Qualys Scanner Appliances. Private use internal IPs must be scanned using scanner appliances, which are installed inside the corporate network. When a scanner is unspecified for a scan task, the Qualys External Scanners are used.
User permissions for the scheduled_scans.php functions are described below.
|
Parameter |
Required/Optional |
|---|---|
| Manager | Add tasks for all assets in the subscription. Remove all tasks. View all tasks in the subscription. |
| Unit Manager |
Add tasks for assets in the user’s business unit. |
| Scanner | Add tasks for assets in the user’s account. Remove the user’s scheduled tasks. View tasks in the subscription |
| Reader | No permission to add and remove tasks. View tasks in the subscription |
The parameters below apply to all scheduled tasks, both scans and maps. There are four required parameters to add a scheduled scan, and five required parameters for a scheduled map. The iscanner_name parameter is required when a Scanner Appliance is used.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| add_task=yes | Required to add a task | Used to add a scheduled task. |
| scan_title={title} | Required to add a task | Specifies a title for the scheduled task. |
| type=scan | map | all | Optional | Specifies the scheduled task type: scan for a scan task or map for a map task. If unspecified, the type is set to type=scan. For a scheduled map, this parameter must be set to type=map. The all type applies only when retrieving a list of scheduled tasks. For example, to receive a list of scheduled scans and maps, specify type=all. |
| active=yes | no | Required to add a task | Specifies whether the scheduled task is active. When active, the scheduled task runs at the specified time. When inactive, the scheduled task does not run at its specified time. |
| scan_target={target} | Optional | Specifies the task target. For a scheduled scan, specify IPs and/or IP ranges. For a scheduled map, specify one or more domain names. Multiple domain names must be comma separated. This parameter and/or asset_groups must be specified when adding a scheduled task. |
| scan_target={target} | Optional | Specifies the task target. For a scheduled scan, specify IPs and/or IP ranges. For a scheduled map, specify one or more domain names. Multiple domain names must be comma separated. This parameter and/or asset_groups must be specified when adding a scheduled task. |
| asset_groups={title1,title2...} | Optional | Specifies the titles of asset groups to be included in the scheduled task target. Multiple asset groups must be comma separated. This parameter and/or scan_target must be specified when adding a scheduled task. |
| exclude_ip_per_scan={value} | Optional | Used to exclude certain IP addresses/ranges for the scheduled scan. One or more IPs/ranges may be specified. Multiple entries are comma separated. An IP range is specified with a hyphen (for example, 10.10.24.1-10.10.24.20). |
| iscanner_name={name} | Optional |
Specifies the name of the Scanner Appliance to be Note: One of these parameters may be specified in the same request: |
| runtime_http_header={value} | Set a custom value in order to drop defenses (such as logging, IPs, etc) when an authorized scan is being run. The value you enter will be used in the “Qualys-Scan:” header that will be set for many CGI and web application fingerprinting checks. Some discovery and web server fingerprinting checks will not use this header. |
|
| default_scanner=1 | Optional |
Enables the default scanner feature, which is only Note: One of these parameters may be specified in the same request: |
| scanners_in_ag=1 | Optional |
et to 1 to use the scanners in asset group features. Note: One of these parameters may be specified in the same request: |
| option={title} | Optional | Specifies the title of an option profile to be applied to the task, used when adding a task. The profile title must be defined in the user account, and it can have a maximum of 64 characters. If unspecified, the default option profile in the user account is applied. Note that custom option profiles can be defined only using the Qualys user interface. A selective vulnerability scan that includes a subset vulnerabilities (QIDs) in the KnowledgeBase may be specified. It’s recommended that you include certain QIDs to ensure host information is available in your scan results and other reports. |
The parameters listed below are required for daily tasks. See Recurrences for an optional parameter.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| occurrence=daily |
Required |
Specifies that the task will occur daily. |
| frequency_days={value} | Required | Specifies that the task will run every N days, where N is the number of days. A valid value is an integer from 1 to 365. |
| {start time parameters} |
Required |
Specifies when the task will start. See “Start Time” for a complete list of parameters. |
The parameters listed below are required for daily tasks. See Recurrences for an optional parameter.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| occurrence=weekly |
Required |
Specifies that the task will occur weekly. |
| frequency_weeks={value} | Required | Specifies that the task will run every N weeks, where N is a number of weeks. A valid value is an integer from 1 to 52. |
| weekdays={value} | Required | Specifies on which weekdays the task will run. One or more days may be specified. A valid value is: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. Multiple days are comma separated. |
| {start time parameters} | Required | Specifies when the task will start. See “Start Time” for a complete list of parameters. |
The parameters listed below are required for a monthly task to be run on the Nth day of the month where N is a day of the month that you specify. For example, you can setup a monthly task to run on the 15th day of each month. See Recurrence for an optional parameter.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| occurrence=monthly |
Required |
Specifies that the scheduled task will occur monthly. |
| frequency_months={value} | Required | Specifies that the task will run, as in every N months, where N is a number of months. A valid value is an integer from 1 to 12. |
| day_of_month={value} | Required | Specifies the day of the month to run. A valid value is an integer from 1 to 31. |
| {start time parameters} | Required | Specifies when the task will start. See “Start Time” for a complete list of parameters. |
The parameters listed below are required for a monthly task to be run on a day of the week (for example Monday, Tuesday) in a particular week of the month. For example, you can setup a monthly task to run on the second Tuesday of the month. See Recurrence for an optional parameter.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| occurrence=monthly |
Required |
Specifies that the scheduled task will occur monthly. |
| frequency_months={value} | Required | Specifies that the task will run every N months, where N is a number of months. A valid value is an integer from 1 to 12. |
| day_of_week={value} | Required | Specifies the day of the week when the task will run. A valid value is an integer from 0 to 6, where 0 is Sunday and 6 is Saturday. |
| week_of_month={value} | Required | Specifies the Nth week of the month, when the task will run. A valid value is: first, second, third, fourth, or last. |
| {start time parameters} | Required | Specifies when the task will See Start Time for a complete list of parameters. |
The parameters listed below specify start time settings used to launch the scheduled task.
Some start time parameters are required for all scheduled tasks as indicated.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| time_zone_code={value} |
Optional |
Specifies the time zone for the task as a pre-defined code. For example, the time zone code for US California is US-CA. Time zone codes must be specified in upper case. Valid time zone codes are provided in the “Time Zone Code List” returned by the time_zone_code_list.php function. For a time zone code that supports Daylight Saving Time, you can specify observe_dst=yes so that the task is updated automatically to reflect local time. This parameter or time_zone must be specified. See “Time Zone Selection” below for further details. |
| observe_dst={yes} |
Optional |
Enables the observe Daylight Saving Time (DST) feature for the task. This feature can be enabled when the time zone code specified in time_zone_code supports DST. When enabled, the service automatically adjusts the start time for the task to reflect local time. To enable this feature, specify observe_dst=yes. Some locales do not support DST, like Arizona and Hawaii. For these locales, if you specify a time zone code with observe_dst=yes, the function returns an error. This parameter may be specified with time_zone_code. (This parameter is invalid when specified with time_zone.) |
| time_zone={value} |
Optional |
Specifies the time zone for the task as a GMT shift value. This is the difference, in hours, between GMT and the local time zone. A valid value is an integer from -12 to 12. For example, the GMT shift for Pacific Standard Time (PST) in California is -8. This parameter cannot be used when the timezone has a 30 or 15 minute offset (for example GMT-930 or GMT+1245). This parameter or time_zone_code must be specified. See “Time Zone Selection” below for further details. Note: This parameter is available for backward compatibility and may not be supported in future releases. |
| start_date={mm/dd/yyyy} |
Optional |
Specifies the start date in mm/dd/yyyy format. By default, the start date is the date when the task is created. |
| start_hour={hour} | Required | Specifies the hour when the task will start. The hour variable is an integer from 0 to 23, where 0 represents 12 AM, 7 represents 7 AM, and 22 represents 10 PM. |
| start_minute={minute} | Optional | Specifies the minute when the task will start. A valid value is an integer from 0 to 59. |
| end_after={value} | Optional | Specifies the number of hours to wait for a map or scan to complete before deactivating the task. By default the service does not deactivate tasks until they complete. A valid value is an integer from 1 to 48. |
The recurrence parameter listed below is optional. By default the task does not end unless it is deactivated or deleted.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| recurrence={value} |
Optional |
Specifies the number of times the task will be run before it is deactivated. A valid value is an integer from 1 to 99. For example, if you set recurrence=2, the scheduled task will be deactivated after it runs 2 times. |
The following parameters are required to remove a scheduled task. Both parameters must be specified. When these parameters are set, the function removes the specified scheduled task and returns an XML success message.
If you remove a scheduled task, any saved reports for the scheduled task remain on the
Qualys server.
|
Parameter |
Required/Optional |
Description |
|---|---|---|
| drop_task=yes | Required | Used to delete a scheduled task. A valid value is “yes” to delete the task or “no” (the default) to not delete the task. |
|
task_id={taskID} |
Required | Specifies the task ID of the task to be deleted. The Qualys service assigns a task ID to each scheduled task when the task is added. |
API Request
curl --location --request POST 'https://<qualys_base_url>/msp/scheduled_scans.php?add_task=yes&scan_title=Scan1&active=yes&scan_target=10.10.10.1&iscanner_name=shreya_test_scanner1&occurrence=daily&frequency_days=1&time_zone_code=US-CA&observe_dst=yes&start_hour=14&start_minute=0' \
--header 'X-Requested-With: test' \
--header 'Authorization: Basic Encoded username:passwordstring'
API Response
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SCHEDULEDSCANS SYSTEM "https://<qualys_base_url>/scheduled_scans.dtd">
<SCHEDULEDSCANS>
<SCAN active="yes" ref="6197007">
<TITLE>
<![CDATA[Scan1]]>
</TITLE>
<TARGETS>
<![CDATA[11.11.11.1]]>
</TARGETS>
<SCHEDULE>
<DAILY frequency_days="1"/>
<START_DATE_UTC>2025-03-17T22:00:00</START_DATE_UTC>
<START_HOUR>14</START_HOUR>
<START_MINUTE>0</START_MINUTE>
<TIME_ZONE>
<TIME_ZONE_CODE>US-CA</TIME_ZONE_CODE>
<TIME_ZONE_DETAILS>
<![CDATA[(GMT -08:00) United States, California (Pacific Standard Time)]]>
</TIME_ZONE_DETAILS>
</TIME_ZONE>
<DST_SELECTED>1</DST_SELECTED>
</SCHEDULE>
<NEXTLAUNCH_UTC>2025-03-17T21:00:00</NEXTLAUNCH_UTC>
<DEFAULT_SCANNER></DEFAULT_SCANNER>
<ISCANNER_NAME>xxx_test_scanner1</ISCANNER_NAME>
<OPTION>Initial Options</OPTION>
<TYPE>SCAN</TYPE>
<USER_ENTERED_IPS network_id="0">
<RANGE>
<START>11.11.11.1</START>
<END>11.11.11.1</END>
</RANGE>
</USER_ENTERED_IPS>
<OPTION_PROFILE>
<OPTION_PROFILE_TITLE option_profile_default="1">
<![CDATA[Initial Options]]>
</OPTION_PROFILE_TITLE>
</OPTION_PROFILE>
</SCAN>
</SCHEDULEDSCANS>
When adding a task, you must identify local time by specifying either a time zone code or a GMT shift value using the parameters described below. These are mutually exclusive parameters which cannot be used together.
For the time_zone_code parameter, you specify a time zone code that corresponds to local time. Refer to the “Time Zone Code List” below to select an appropriate code. For example if the task will run in New York, then you specify the code “US-NY”. Many time zones, like New York, observe DST. If you specify a code for a time zone that supports DST, you have the option to enable the observe Daylight Saving Time (DST) feature so the task is updated automatically to reflect local time. To enable this feature. specify observe_dst=yes.
For the time_zone parameter, you specify a GMT shift, like -8 for Pacific Standard Time in California, that corresponds to local time. When the timezone has a 30 or 15 minute offset, then the time_zone parameter cannot be used. When specified, the service
automatically determines the appropriate time zone code for the task and includes this in scheduled scans reports. Note this parameter has been available in
previous releases and is supported for backward compatibility.
The time_zone_code_list.php function provides a list of all available time zone codes that can be specified with the time_zone_code parameter.
To retrieve a list of time zone codes, use this URL:
https://qualysapi.qualys.com/msp/time_zone_code_list.php
The DTD for the XML document returned from time_zone_code_list.php can be
found at the following URL:
https://qualysapi.qualys.com/time_zone_code_list.dtd
Time zone code
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SCHEDULEDSCANS SYSTEM
"https://qualysapi.qualys.com/time_zone_code_list.dtd">
<TIME_ZONES>
<TIME_ZONE>
<TIME_ZONE_CODE>AS</TIME_ZONE_CODE>
<TIME_ZONE_DETALS>
<![CDATA[(GMT-1100) American Samoa: Pago
Pago]]>
</TIME_ZONE_DETALS>
<DST_SUPPORTED>0</DST_SUPPORTED>
</TIME_ZONE>
<TIME_ZONE>
<TIME_ZONE_CODE>UM2</TIME_ZONE_CODE>
<TIME_ZONE_DETALS>
<![CDATA[(GMT-1100) Midway Islands
(U.S.)]]>
</TIME_ZONE_DETALS>
<DST_SUPPORTED>0</DST_SUPPORTED>
</TIME_ZONE>
<TIME_ZONE>
<TIME_ZONE_CODE>NU</TIME_ZONE_CODE>
<TIME_ZONE_DETALS>
<![CDATA[(GMT-1100) Niue: Alofi]]>
</TIME_ZONE_DETALS>
<DST_SUPPORTED>0</DST_SUPPORTED>
</TIME_ZONE>
<TIME_ZONES>
Each <TIME_ZONE> element identifies a time zone properties, including the code, in the sub-elements described below.
| Elements | Description |
| <TIME_ZONE_CODE> | A time zone code. These are pre-defined codes. |
| <TIME_ZONE_DETAILS> | Text describing the time zone. |
| <DST_SUPPORTED> | A value (0 or 1) indicating whether the time zone supports Daylight Saving Time (DST). 1 is reported when DST is supported, and 0 is reported when DST is not supported. |
Examples
To receive an XML document including a list of all scheduled scans, use this URL:
https://qualysapi.qualys.com/msp/scheduled_scans.php
To receive an XML document with a list of all scheduled scans and maps, use this URL:
https://qualysapi.qualys.com/msp/scheduled_scans.php?type=all
To receive an XML document including a list of all scheduled maps, use this URL:
https://qualysapi.qualys.com/msp/scheduled_scans.php?type=map
Examples
The URL below adds a daily scan called “Scan1” that is defined to scan IP address “10.20.30.3”. “Scan1” is scheduled to start at 2 PM every day in Los Angeles, California where DST is observed. The URL below includes all parameters required to add “Scan1”
as an active scan:
https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y
es&scan_title=Scan1&active=yes&scan_target=10.20.30.3&iscanner_
name=scanner1&occurrence=daily&frequency_days=1&time_zone_code=
US-CA&observe_dst=yes&start_hour=14&start_minute=0
To add a daily scan called “My Daily Scan” that is defined to scan IP address “10.10.10.3”, specify the URL below. This daily scan is scheduled to start at 4 PM every day in the California time zone. The URL below includes all required parameters:
https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y
es&scan_title=My+Daily+Scan&active=yes&scan_target=10.10.10.3&i
scanner_name=scanner1&occurrence=daily&frequency_days=1&time_zo
ne_code=US-CA&observe_dst=yes&start_hour=14&start_minute=0
The URL below adds a weekly scan called “Scan2” that is defined to scan the asset groups “Finance” and “Operations”. “Scan2” is scheduled to start at 10 AM every 2nd
Tuesday in Paris, France where DST is observed. The URL below includes all required parameters:
https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y
es&scan_title=Scan2&active=yes&asset_groups=Finance,Operations&
iscanner_name=scanner2&option=RV10+Options&occurrence=weekly&fr
equency_weeks=2&weekdays=Tuesday&time_zone_code=FR&observe_dst=
yes&start_hour=10&start_minute=0&recurrence=90
The URL below adds a monthly scan called “Scan3” that is defined to scan 3 asset groups with the default scanner enabled. “Scan3” starts every 2 months on the 2nd Friday of the month at 6 PM in New York City where DST is observed.
https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y
es&scan_title=Scan3&active=yes&asset_groups=Critical+Group+4,Cr
itical+Group+5,Critical+Group+6&default_scanner=1&occurrence=mo
nthly&frequency_months=2&day_of_week=5&week_of_month=2&time_zon
e_code=US-NY&observe_dst=yes&start_hour=18&start_minute=0
The URL below adds a monthly scan called “My Scheduled Scan” that uses the scanners in asset group feature.
https://qualysapi.qualys.com/msp/scheduled_scans.php?
add_task=yes&scan_title=My+Scheduled+Scan&active=yes&
asset_groups=Group+A,Group+B,Group+C&scanners_in_ag=1&
occurrence=monthly&frequency_months=2&day_of_week=5&
week_of_month=2& time_zone_code=US-NY&
observe_dst=yes&start_hour=18& start_minute=0
The URL below removes a scheduled scan with the task ID “6703”. Two parameters are required as shown.
https://qualysapi.qualys.com/msp/scheduled_scans.php?drop_task=
yes&task_id=6703
Examples
To add a weekly map called “My Weekly Map” to perform discovery on “mydomain.com”, specify the URL below. This weekly map runs every 8 weeks and starts on Sunday at 2 AM in Tokyo, Japan. https://qualysapi.qualys.com/msp/scheduled_scans.php?add_task=y es&scan_title=My+Weekly+Map&active=yes&type=map&scan_target=myd omain.com&iscanner_name=scanner5&occurrence=weekly&frequency_we eks=8&weekdays=Sunday&time_zone_code=JP&start_hour=2&start_minu te=0 The URL below removes a scheduled map with the task ID “11155”. Note that two parameters are required as shown. https://qualysapi.qualys.com/msp/scheduled_scans.php? drop_task=yes&task_id=11155
The DTD for the XML results returned by the scheduled_scans.php function can be
found at the following URL:
https://qualysapi.qualys.com/scheduled_scans.dtd
This XML document supports reporting on scheduled scans and maps.
<platform API server>https://qualysapi.qualys.com/time_zone_code_list.dtd
Was this topic helpful?