--- title: "Create a scheduled search: Request" slug: "create-a-scheduled-search-request" tags: ["Reference", "NDRC 4.x", "Customer", "Network Security", "NDR 4.x"] updated: 2026-09-09T18:07:45Z published: 2026-09-09T18:07:45Z canonical: "docs.trellix.com/create-a-scheduled-search-request" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.trellix.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a scheduled search: Request To create a scheduled search, send the following request: `POST https://<IA_IP_address>:<port_number>/scheduledsearch/v1/watch/<user_name>` Required header: ``` Cookie: px= ``` Request body: ``` {  "name":  "state":  "trigger": {    [      "interval": |"schedule":    ]  }  "input": {    "search": {      "request": {        "body": {          "query":        }      }    }  },  "condition": {    "hitCount":    "operator":  } } ``` Options - IA_IP_address—The IP address of the NDR appliance running the NDR API. - port_number—The port number of the NDR appliance running the NDR API. - user_name—The name of the user. The user_name must match the name of the logged-in user. - token—This token authenticates the session. By default, the session times out after 24 hours. - scheduled_search_name—The name of the scheduled search. The scheduled search name must not already exist for the user creating it. The name can consist of alphanumeric characters and underscores. - scheduled_search_state—The state of the scheduled search. The state can be `ACTIVE` if the query runs at scheduled intervals or `INACTIVE` if no queries are run. > [!WARNING] > Important > > Trellix recommends using trigger_schedule instead of trigger_interval. To avoid interfering with network traffic, schedule the search for times with the least network activity. > > Use trigger_interval or trigger_schedule but not both. If you use more than one kind of trigger, the result is unpredictable. - trigger_interval—The interval between scheduled searches. Valid values are `1m`–`59m` or `1h`–`23h`. For example, a value of `5h` means to run the query every 5 hours from now, and a value of `20m` means to run the query every 20 minutes from now. - trigger_schedule—When the query will run. Valid values are `hourly`, `daily`, or `weekly`: - hourly—Valid values are `1`–`59`; for example, `10` means to run the query every 10th minute of every hour. - daily—The valid value is the time of day in hour:minute format. For example, `13:40` means to run the query every 14th hour at 40 minutes, and 01:01 means to run the query every second hours at 1 second. - weekly—Valid values are `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, and `SUNDAY` and the time of day in hour:minute format; for example, `"items": {"MONDAY","WEDNESDAY","FRIDAY"} "at": 01:01`. - query_string_or_saved_query—The Elasticsearch query to run or the name of a saved query to run. - lookback_period_type—The start time of the period examined by the query. The start time is `AUTO` if the start time is the last invocation of the query or `CUSTOM` if the start time is provided with the period field. Valid values for the period field are `1h`–`23h` or `1d`–`31d`, indicating the number of hours or days before now to start searching. For example, `{"type": "CUSTOM", "period": "4h"}` indicates that the query examines the four hours before now. - hit_count—The number of search results returned before the query results are saved. - operator—The operator to be evaluated with hit_count value. Valid vales are `EQUAL`, `NOTEQUAL`, `LESSTHAN`, `LESSTHANOREQUAL`, and `GREATERTHANOREQUAL`. - token—This token authenticates the session. By default, the session times out after 24 hours. ### Example ``` POST https://xxx.xxx.xxx.xxx:443/scheduledsearch/v1/watch/npadmin ``` Required header: ``` Cookie: px=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Request body: ``` {  "name": "SavedQueryExample",  "trigger": {    "schedule": {      "weekly": {        "at": "14:10",        "daysOfWeek": [          "MONDAY",          "TUESDAY"        ]      }    }  },  "input": {    "search": {      "request": {        "body": {          "query": {            "ef_saved_query_id": "querybody::npadmin::test"          }        },        "lookback_period": {          "type": "AUTO"        }      }    }  },  "condition": {    "hitCount": 100,    "operator": "GREATERTHAN"  } } ``` ### Create a scheduled search: Response ``` HTTP/1.1 [Response Code] [Response Message] Server: [Server] Date: [Date] Content-Type: [Content Type] name: [Scheduled Search Name] state: [Scheduled Search State] interval: [Trigger Interval] schedule: [Trigger Schedule] hourly: [Hourly] daily: [Daily] weekly: [Weekly] daysOfWeek: [Days of Week] at: [Weekly At] search_type: [Search Type] indices: [Indices] type: [Lookback Type] period: [Lookback Period] query: [Query] hitCount: [Hit Count] operator: [Condition Operator] ``` ###### Response fields - Response Code—A standard HTTP response code. - 201—Request successful; the scheduled search was created. - 404—Request unsuccessful because the scheduled search name already exists. - Response Message—A standard HTTP response message. - Created—Request successful; the scheduled search was created. - Not Found—Request unsuccessful because the scheduled search name already exists. - Server—The server being used. - Date—Standard HTML date format. - Content Type—The response format. - Scheduled Search Name—The name of the scheduled search. - Scheduled Search State—The state of the scheduled search. The state can be `ACTIVE` if the query runs at scheduled intervals or `INACTIVE` if no queries are run. - Trigger Interval—The interval between scheduled searches. Valid values are `1m`–`59m` or `1h`–`23h`. For example, a value of `5h` means to run the query every 5 hours from now, and a value of `20m` means to run the query every 20 minutes from now. - Trigger Schedule—When the query will run. Valid values are `hourly`, `daily`, or `weekly`. - Hourly—Valid values are `1`–`59`; for example, `10` means to run the query every 10th minute of every hour. - Daily—The valid value is the time of day in hour:minute format. For example, `13:40` means to run the query every 14th hour at 40 minutes, and 01:01 means to run the query every second hours at 1 second. - Weekly—The query is run for the specified days of the week at the specified time. - Days of Week—Valid values are `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, and `SUNDAY`. - Weekly At—The time of day in hour:minute format. - Search Type—`*` indicates that everything is searched. - Indices—The index type that is searched. - Lookback Type—The start time of the period examined by the query. The start time is `AUTO` if the start time is the last invocation of the query or `CUSTOM` if the start time is provided with the period field. - Lookback Period—Valid values are `1h`–`23h` or `1d`–`31d`, indicating the number of hours or days before now to start searching. For example, `{"type": "CUSTOM", "period": "4h"}` indicates that the query examines the four hours before now. - Query—The Elasticsearch query to run or the name of a saved query to run. - Hit Count—The number of search results returned before the query results are saved. - Condition Operator—The operator to be evaluated with the hitCount value. Valid vales are `EQUAL`, `NOTEQUAL`, `LESSTHAN`, `LESSTHANOREQUAL`, and `GREATERTHANOREQUAL`. ###### Example ``` HTTP/1.1 201 Created Server: nginx Date: Thu, 28 Apr 2016 20:23:55 GMT Content-Type: text/plain; charset=utf-8 {  "name":"test3",  "state":"ACTIVE",  "trigger":{    "schedule":{      "daily":{        "at":"10:00"      }    }  },  "input":{    "search":{      "request":{        "search_type":"query_then_fetch",        "indices":[          "nspector",          "alert"        ],        "lookback_period":{          "type":"CUSTOM",          "period":"5h"        },        "body":{          "query":{            "query_string":{              "analyze_wildcard":true,              "lowercase_expanded_terms":false,              "query":"doc_values_type:fileinfo"            }          }        }      }    }   },  "condition":{    "hitCount":10,    "operator":"GREATERTHAN"  } } ``` ### cURL code sample: Create a scheduled search ``` curl -k -X POST -H "Content-Type: application/json" --cookie "px=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" https://xxx.xxx.xxx.xxx:443/scheduledsearch/v1/watch/npadmin -d '{"name":"QueryStringExample","trigger":{"schedule":{"daily":{"at":"10:00"}}},"input":{"search":{"request":{"body":{"query":{"query_string":{"analyze_wildcard":true,"lowercase_expanded_terms":false,"query":"doc_values_type:fileinfo"}}},"lookback_period": {"type":"CUSTOM","period":"5h"}}}},"condition":{"hitCount":10,"operator":"GREATERTHAN"}}' ``` This cURL sample includes the following options: - `-k`—This option explicitly allows cURL to perform insecure SSL connections and transfers, which allows you to test your SSL connection without installing a CA certificate. - `-X POST`—This option specifies using the POST method. - `-H "Content-Type: application/json"`—This header specifies that the request body is in JSON format. - `--cookie "px=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"`—This option specifies the authentication token for this session. - `https://xxx.xxx.xxx.xxx:443/scheduledsearch/v1/watch/npadmin`—The scheduled search request URL. Replace `xxx.xxx.xxx.xxx` with the IP address of your NDR appliance. Replace `npadmin` with your user name. - `-d '{"name":"QueryStringExample","trigger":{"schedule":{"daily":{"at":"10:00"}}},"input":{"search":{"request":{"body":{"query":{"query_string":{"analyze_wildcard":true,"lowercase_expanded_terms":false,"query":"doc_values_type:fileinfo"}}},"lookback_period":{"type":"CUSTOM","period":"5h"}}}},"condition":{"hitCount":10,"operator":"GREATERTHAN"}}'`—This option specifies what will be searched for and when the search will be run. ###### Results This example creates a search that is run every day at 10 a.m. A report is created if there are more than 10 results.