Company logoHelp Center
Visit www.threatlocker.com

(Updating Agent Version) - /portalAPI/ScheduledAgentAction/*

14 min. readlast update: 10.09.2025

This article will encompass all portalAPI calls that are related to /portalAPI/ScheduledAgentAction/* endpoints

 

Be sure to input the instance your organization exists on for each call. This is indicated with the "INSTANCE" text in each endpoint. Linked here is a KB to find your instance:

Locating Your Organization's Instance | ThreatLocker Help Center

 

Please note that in order to use these features, your ThreatLocker agents must be on Windows version 10.7.3, Mac 5.4, Linux 2.2, or Red Hat 1.0 or above. Also, be sure to specify a managedOrganizationId header, using the organizationId where your user exists or another organization your user has access to, for each call you complete.

 

Abort

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction/Abort

  • Method: POST
  • Description: This API is used to abort all or specific locations for a specified scheduled agent action.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Fields
      • abortAll: This field determines whether all locations in the specified scheduledId will be aborted. When wanting to abort everything, set this field to true and be sure to set the appliesTo field below accordingly. When wanting to abort select locations, set this field to false and use the appliesTo field to specify where the scheduled agent action will be aborted.
        • Expects: true or false
      • appliesTo: This field should always be included, even when abortAll is set to true, but is most often used when you want to end the scheduled agent action in a specific location(s). Each location expects each field listed below, as shown in the Required body section. If looking to abort the scheduled agent action for all locations inside the current scheduledId, set abortAll to true and set this field to "appliesTo": [].
        • appliesToId: This field determines the location where the scheduled agent action will be aborted. Currently, this field only expects a computerId value to be entered, as each computer needs to be listed for its scheduled agent action to be aborted. However, this field will be expanded to expect a respective Id value to be entered, either organizationId, computerGroupId, or computerId.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • appliesToTypeId: This field determines the type of location where the scheduled agent action will be aborted. Currently, only individual computers can have their scheduled agent action aborted. Therefore, this field currently only expects the Integer value 3 to be entered. However, once more scheduled agent actions are available, this functionality will expand to encompass the following values as well.
          • Organization = 1
          • Computer Group = 2
          • Computer = 3
          • Global Computer Group = 6
      • scheduledId: This field determines which scheduled agent action will be aborted completely or which specific locations will be aborted.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • Required body

{
  "abortAll": <Boolean>,
  "appliesTo": [
    {
      "appliesToId": "00000000-0000-0000-0000-000000000000",
      "appliesToTypeId": <Integer>
    },
    {
      "appliesToId": "00000000-0000-0000-0000-000000000000",
      "appliesToTypeId": <Integer>
    }
  ],
  "scheduledId": "00000000-0000-0000-0000-000000000000"
}

  • Optional Body/Parameters
    • N/A
  • Permissions Needed for User
    • Edit Computers
    • Edit Computer Groups

 

AppliesTo

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction/AppliesTo

  • Method: GET
  • Description: This API is used to get a list of all the possible options where a scheduled agent action can be applied based on the osType and/or a specific search using the searchText field. The key value returned in this API can be used to set the appliesTo field in the calls below.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Parameters
      • osType: This field determines the OS Type of the computers/groups that will be returned. Red Hat Enterprise Linux has not had an agent released yet, but it is currently in development. This field expects the Integer value associated with the OS Type that you want to search for to be entered.
        • Windows = 1
        • MAC = 2
        • Linux = 3
        • Red Hat Enterprise Linux 6 = 7
  • Optional Body/Parameters
    • Parameters
      • includeChildren: This field determines whether the groups/computers from child organizations where scheduled agent actions can be scheduled will be returned. When this field is set to true, child organizations will be shown. When this field is set to false or omitted, child organizations will not be shown.
        • Expects: true or false 
      • searchText: This field narrows the search to what is entered into this field. This field searches based on organization, computer group, and computer name. Partial or whole names can be entered and searched using this field. Wildcards are effectively added on either side of your search text.
        • Expects: Any text input
  • Permissions Needed for User
    • View Computers
    • View Computer Groups

 

GetByParameters

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction/GetByParameters

  • Method: POST
  • Description: This API is used to get and filter the scheduled agent action details using a specified scheduledId and additional filtering. This API returns the progress and total counts like the GetForHydration call below, but this API also returns the details of the computers and when they are scheduled to complete the agent action.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Fields
      • scheduledId: This field determines which scheduled agent action's details will be returned. A valid and active scheduledId is expected to return accurate details and progress.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
    • Required body

{
  "scheduledId": "00000000-0000-0000-0000-000000000000"
}

  • Optional Body/Parameters
    • Fields
      • computerGroupIds: This field expects the computer group IDs where the scheduled agent action has been applied. It will narrow the results returned to the computer groups specified.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
      • isAscending: This field determines the order in which the computers with scheduled agent actions are returned. When isAscending is set to true or this field is omitted completely, the computers will be returned in decreasing order, from high to low (alphabetically/numerically), based on the orderBy field utilized. When isAscending is false, the computers will be returned in increasing order, from low to high, based on the orderBy field utilized.
        • Expects: true or false
      • orderBy: This field will order the computers that are shown based on the isAscending field and the text entered below. When this field is omitted, the computers will be shown using the scheduleddatetime (default) option. This field expects the text from one of the following options to be entered exactly as they appear.
        • scheduleddatetime
        • computername
        • computergroupname
        • organizationname
      • organizationIds: This field expects the organization IDs where the scheduled agent action has been applied. It will narrow the results returned to the organizations specified.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
      • pageNumber and pageSize: This value determines how many computers will be returned as if the response was in the ThreatLocker Portal. When these fields are not included, pageNumber will default to 1, and pageSize will default to 25. However, this field does not follow the same conventions of the pageNumber and pageSize values as the Portal. Any valid integer can be entered, and it will return in the selected formatting. For instance, if there are 5 computers to be returned but “pageNumber”: 1 and “pageSize”: 2, 2 entries will be returned per page, and the first two computers will be shown.
        • Expects: An Integer value
      • searchText: This field narrows the search to what is entered into this field. This field searches based on organization, computer group, and computer name. Partial or whole names can be entered and searched using this field. Wildcards are effectively added on either side of your search text.
        • Expects: Any text input
    • Optional body

{
  "computerGroupIds": [
    "00000000-0000-0000-0000-000000000000",
    "00000000-0000-0000-0000-000000000000"
  ],
  "isAscending": <Boolean>,
  "orderBy": "<String>",
  "organizationIds": [
    "00000000-0000-0000-0000-000000000000",
    "00000000-0000-0000-0000-000000000000"
  ],
  "pageNumber": <Integer>,
  "pageSize": <Integer>,
  "scheduledId": "00000000-0000-0000-0000-000000000000",
  "searchText": "<String>"
}

  • Permissions Needed for User
    • View Computers
    • View Computer Groups

 

GetForHydration

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction/GetForHydration

  • Method: GET
  • Description: This API is used to get the details and progress of a specific scheduled agent action.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Parameters
      • scheduledId: This field determines which scheduled agent action's details will be returned. A valid and active scheduledId is expected to return accurate details and progress.
        • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
  • Optional Body/Parameters
    • N/A
  • Permissions Needed for User
    • View Computers
    • View Computer Groups

 

List

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction/List

  • Method: GET
  • Description: This API is used to get the list of all the currently scheduled agent actions in your organization. This field is beneficial for getting the scheduledId used in several other ScheduledAgentAction APIs.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Parameters
      • scheduledType: This field determines the type of scheduled agent action that will be searched. Currently, only one agent action to update the ThreatLocker version is available, as listed below. This field expects the Integer value associated with the scheduled agent action to be entered.
        • Version Update = 1
  • Optional Body/Parameters
    • Parameters
      • includeChildren: This field determines whether scheduled agent actions from child organizations will be returned. When this field is set to true, child organizations will be shown. When this field is set to false or is omitted, child organizations will not be shown.
        • Expects: true or false
  • Permissions Needed for User
    • View Computers
    • View Computer Groups

 

ScheduledAgentAction

https://portalapi.INSTANCE.threatlocker.com/portalapi/ScheduledAgentAction

  • Method: POST
  • Description: This API will schedule a new agent action that will be completed on your computers.
  • Required Body/Parameters
    • Valid APIKey/Authorization Token in header
    • Fields
      • appliesTo: This field expects the location(s) where the scheduled agent action will be applied. Each location expects each field listed below, as shown in the Required body section.
        • appliesToId: This field determines the location where the scheduled agent action will be applied. This field expects the respective Id value to be entered, either organizationId, computerGroupId, or computerId.
          • Expects: <GUID> in format "00000000-0000-0000-0000-000000000000"
        • appliesToTypeId: This field determines the type of location where the scheduled agent action will be enabled. This field expects the Integer value associated with the location where the scheduled agent action will be enabled to be entered.
          • Organization = 1
          • Computer Group = 2
          • Computer = 3
          • Global Computer Group = 6
      • scheduledType: This field specifies the type of scheduled agent action that will be applied. Currently, only one agent action to update the ThreatLocker version is available, as listed below. This field expects the Integer value associated with the scheduled agent action to be entered.
        • Version Update = 1
      • scheduledTypePayload: This field expects the payload of the scheduled agent action type to be entered. Currently, only the ThreatLocker version ID can be entered since this is the only agent action that is available. This field expects a full string, including the ThreatLocker version ID for this agent action, as shown below and in the Required body section. Replace the 0 values with the target ThreatLocker version you would like your computers to update to.
        • Expects: "{\"targetVersionId\": \"00000000-0000-0000-0000-000000000000\"}"
    • Required body

{
  "appliesTo": [
    {
      "appliesToId": "00000000-0000-0000-0000 000000000000",
      "appliesToTypeId": <Integer>
    },
    {
      "appliesToId": "00000000-0000-0000-0000-000000000000",
      "appliesToTypeId": <Integer>
    }

  ],
  "scheduledType": <Integer>,
  "scheduledTypePayload": "<String>"
}

  • Optional Body/Parameters
    • Fields
      • batchAmount: This field determines the number of computers that will have the scheduled agent action performed at a time. When an Integer is selected, it will complete the scheduled action on the selected number of computers and proceed to the next batch after one hour has passed, depending on the windowStateTime and windowEndTime fields below. If this field is omitted, the agent actions will not be scheduled and will be completed at once. This field expects one of the integer values below to be entered:
        • 25
        • 50
        • 100
        • 250
        • 500
      • startDate: This field determines when the scheduled agent action will begin to process for your computers. If this field is omitted, the current date and time when the API is called will be used to start the scheduled agent action processing. This expects a date and time entered in UTC in format "YYYY-MM-DDTHH:MM:SSZ", where YYYY is the year, the first MM is the month, DD is the day, HH are the hours, the second MM are the minutes, and SS are the seconds. The T must be included to designate the time and should not be changed or removed.
        • Expects start date and time in format: "YYYY-MM-DDTHH:MM:SSZ"
      • windowStartTime: This field determines the beginning of the window during which the scheduled agent actions will be completed on the computers. If this field is omitted, the scheduled agent action will be attempted every hour until every computer completes the scheduled agent action. This field expects a time, entered in a 24-hour format, in "HH:MM" format, where HH are the hours and MM are the minutes.
        • Expects start time in format: "HH:MM"
      • windowEndTime: This field determines the end of the window during which the scheduled agent actions will be completed on the computers. If this field is omitted, the scheduled agent action will be attempted every hour until every computer completes the scheduled agent action. This field expects a time, entered in a 24-hour format, in "HH:MM" format, where HH are the hours and MM are the minutes.
        • Expects end time in format: "HH:MM"
    • Optional body

{
  "appliesTo": [
    {
      "appliesToId": "00000000-0000-0000-0000 000000000000",
      "appliesToTypeId": <Integer>
    },
    {
      "appliesToId": "00000000-0000-0000-0000-000000000000",
      "appliesToTypeId": <Integer>
    }

  ],
  "batchAmount": <Integer>,
  "scheduledType": <Integer>,
  "scheduledTypePayload": "<String>",
  "startDate": "YYYY-MM-DDTHH:MM:SSZ",
  "windowStartTime": "<String>",
  "windowEndTime": "<String>"
}

  • Permissions Needed for User
    • Edit Computers
    • Edit Computer Groups
Was this article helpful?