--- title: Create Batch slug: scaleserp/batches-api/batches/create docTags: createdAt: 2024-08-03T18:00:34.677Z --- # Create Batch Create a Batch to run up to 15,000 Searches (100 when adding searches with `include_html=true` set) on a schedule. You can have up to 10,000 Batches set up on your Scale SERP account at any one time. Batches are created by making an `HTTP POST` to the `/batches` endpoint. POST parameters can be either supplied as `x-www-form-urlencoded` parameters or by POST'ing a `JSON` object to the `/batches` endpoint. :::hint{type="info"} **Using **`include_html=true`** in Batches** When adding searches with `include_html=true` to a Batch the maximum number of searches per Batch is 100 (rather than 15,000) because including the HTML within the response makes the Batch Result Sets much larger. The limit is in place to ensure Result Set files are of a manageable size. If you have need to run a large number of searches all with `include_html=true` then simply split the searches across multiple 100-search Batches. ::: *** ### Example `POST` `/batches` Let's start with a simple example; we'll create a Batch that is set to run every day at 9am and 5pm. We'll use the `notification_email` parameter to specify an email address to send notifications to (when the Batch completes), the `notification_as_csv` parameter to request the Batch results be delivered in CSV format and the `destination_ids` parameter to request that the Result Sets generated by running the Batch be uploaded to the specified Destination ID of "ABCDEFG": :::CodeblockTabs ```curl $ curl "https://api.scaleserp.com/batches?api_key=demo" \ -d name="My First Batch" \ -d enabled=true \ -d schedule_type="daily" \ -d priority="normal" \ -d schedule_hours="9,17" \ -d destination_ids="ABCDEFG" \ -d notification_email="john.smith@example.com" \ -d notification_as_csv=true ``` ```nodejs const axios = require('axios'); const body = { name: 'My First Batch', enabled: true, schedule_type: 'daily', priority: 'normal', schedule_hours: [9,17], destination_ids: [ 'ABCDEFG' ], notification_email: 'john.smith@example.com', notification_as_csv: true } axios.post('https://api.scaleserp.com/batches?api_key=demo', body) .then(response => { const apiResponse = response.data; console.log('Batch Created: ' + JSON.stringify(apiResponse, 0, 2)); }).catch(error => { console.log(error); }); ``` ```python import requests body = { "name": "My First Batch", "enabled": True, "schedule_type": "daily", "priority": "normal", "schedule_hours": [9,17], "destination_ids": [ "ABCDEFG" ], "notification_email": "john.smith@example.com", "notification_as_csv": True } api_result = requests.post('https://api.scaleserp.com/batches?api_key=demo', json=body) api_response = api_result.json() print "Batch Created: ", json.dumps(api_response) ``` ```php "My First Batch", "enabled" => True, "schedule_type" => "daily", "priority" => "normal", "schedule_hours" => "9,17", "destination_ids" => "ABCDEFG", "notification_email" => "john.smith@example.com", "notification_as_csv" => True ]); $ch = curl_init('https://api.scaleserp.com/batches?api_key=demo'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); # the following options are required if you're using an outdated OpenSSL version # more details: https://www.openssl.org/blog/blog/2021/09/13/LetsEncryptRootCertExpire/ curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_TIMEOUT, 180); curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST"); curl_setopt($ch, CURLOPT_POSTFIELDS, $body); $json = curl_exec($ch); curl_close($ch); $api_result = json_decode($json, true); print_r($api_result); echo "Batch Created", PHP_EOL; ?> ``` ::: Scale SERP responds with the following JSON confirming the Batch has been successfully created. Note the Batch `id` , you'll use the Batch ID in subsequent calls to [update](https://docs.trajectdata.com/scaleserp/batches-api/batches/update), [delete](https://docs.trajectdata.com/scaleserp/batches-api/batches/delete) and [add Searches](https://docs.trajectdata.com/scaleserp/batches-api/searches/create) to the Batch. ```json { "request_info": { "success": true }, "batch": { "id": "F994420D", "created_at": "2020-01-01:00:00.000Z", "name": "My First Batch", "schedule_type": "daily", "priority": "normal", "schedule_hours": [ 9, 17 ], "destination_ids": [ "ABCDEFG" ], "enabled": true, "status": "idle", "search_total_count": 0, "search_page_count": 0, "next_result_set_id": 1, "results_count": 0, "notification_email": "john.smith@example.com", "notification_as_json": false, "notification_as_csv": true, "search_type": "mixed", "search_type_locked": false } } ``` *** ### Scheduling Batches Batches can be scheduled on a monthly, weekly or daily basis. You can also set a Batch to be started manually, either via the [Scale SERP Dashboard](https://app.scaleserp.com/batches) or the [Start Batch API](https://docs.trajectdata.com/scaleserp/batches-api/batches/start). A Batches' schedule is defined by the `schedule_type` parameter. The values of `schedule_type` , and other associated parameters are shown below: :::hint{type="info"} Batch schedules are executed in the timezone set up on your [profile](https://app.scaleserp.com/profile) ::: | `schedule_type` | `Scheduling Parameters` | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `monthly` | 1. `schedule_days_of_month` 2. Array of days of the month to run the Batch, i.e. `[1,20]` for the 1st & 20th

1. `schedule_hours` 2. Array of hours of the day to run the Batch, i.e. `[9,17]` for 9am & 5pm | | `weekly` | 1) `schedule_days_of_week` 2) Array of days of the week (as integers) to run the Batch where 0=Sunday and 6=Saturday, i.e. `[0,2]` for Sunday & Tuesday

1) `schedule_hours` 2) Array of hours of the day to run the Batch, i.e. `[9,17]` for 9am & 5pm | | `daily` | 1. `schedule_hours` 2. Array of hours of the day to run the Batch, i.e. `[9,17]` for 9am & 5pm | | `manual` | When `schedule_type=manual` the Batch must be manually started, either via the [Scale SERP Dashboard ](https://app.scaleserp.com/batches)or the [Start Batch API ](https://docs.trajectdata.com/scaleserp/batches-api/batches/start). | ### Batch Parameters `POST` `/batches` The following parameters can be used when creating a Batch. The `api_key` parameter should be supplied as a querystring parameter on the request URL. Parameters other than `api_key` should be supplied in either `x-www-form-urlencoded` or `JSON` format, in the request body. | `Parameter` | `Required` | `Description` | | --------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `api_key` | `required` | The API key for your account, should be supplied on the request querystring, i.e. `api_key=demo` | | `name` | `required` | The name of the Batch. | | `enabled` | `optional` | Determines whether the Batch is enabled or not. Disabled Batches do not automatically start on their schedule.
`Parameter Values`
1) `true` 2) Batch is enabled

1) `false` 2) Batch is disabled | | `schedule_type` | `optional` | Determines the type of schedule the Batches uses.
`Parameter Values`
1) `monthly` 2) Batch is run on a monthly schedule, use `schedule_days_of_month` to determine which days of the month and `schedule_hours` to determine which hours on those days.

1) `weekly` 2) Batch is run on a weekly schedule, use `schedule_days_of_week` to determine which days of the week and `schedule_hours` to determine which hours on those days.

1) `daily` 2) Batch is run on a daily schedule, use `schedule_hours` to determine which hours of the day the Batch is run.

1) `minutes` 2) Batch is run on a Per X Minutes schedule, use `schedule_minutes` to determine the minutes frequency that the Batch is run. You may optionally use `schedule_hours` , `schedule_days_of_week` and `schedule_days_of_month` to refine the hours of the day, days of the week or days of the month that you wish the Per X Minutes schedule to be run.

1) `manual` 2) Batch is run manually, use the [Scale SERP Dashboard ](https://app.scaleserp.com/batches)or the [Start Batch API ](https://docs.trajectdata.com/scaleserp/batches-api/batches/start)to start the Batch. | | `priority` | `optional` | Determines the priority of the Batch. When multiple Batches are queued, Scale SERP starts them in priority order. Learn more about [priorities ](https://docs.trajectdata.com/scaleserp/batches-api/priorities).
`Parameter Values`
1) `highest`

1) `high`

1) `normal`

1) `low`

1) `lowest` | | `schedule_days_of_month` | `optional` | Determines the days of the month the Batch is run when `schedule_type=monthly` or `schedule_type=minutes` , expressed as an array of integers, i.e. `[1,3,20]` for the 1st, 3rd and 20th of the month.
`Note` When using `schedule_days_of_month` in combination with `schedule_type=minutes` the Batch is executed at the per-minute frequency set in `schedule_minutes` on the days of the month set in `schedule_days_of_month` . For example, if you set `schedule_type=minutes` , `schedule_minutes=every_5_minutes` and `schedule_days_of_month=[1,3,20]` your Batch would be run every 5 minutes on the 1st, 3rd and 20th of the month. When `schedule_type=minutes` you can use **either** `schedule_days_of_month` or `schedule_days_of_week` , not both simultaneously. | | `schedule_days_of_week` | `optional` | Determines the days of the week the Batch is run when `schedule_type=weekly` or `schedule_type=minutes` , expressed as an array of integers where 0=Sunday and 6=Saturday, i.e. `[0,2]` for Sunday & Tuesday.
`Note` When using `schedule_days_of_week` in combination with `schedule_type=minutes` the Batch is executed at the per-minute frequency set in `schedule_minutes` on the days of the week set in `schedule_days_of_week` . For example, if you set `schedule_type=minutes` , `schedule_minutes=every_5_minutes` and `schedule_days_of_week=[0,2]` your Batch would be run every 5 minutes on Sunday & Tuesday. When `schedule_type=minutes` you can use either `schedule_days_of_week` or `schedule_days_of_month` , not both simultaneously. | | `schedule_hours` | `optional` | Determines the hours of the day the Batch is run when `schedule_type=minutes` , `schedule_type=monthly` , `schedule_type=weekly` or `schedule_type=daily` . Expressed as an array of integers between 0 (midnight) and 23 (11pm), i.e. `[9,17]` for 9am & 5pm.
`Note` Batch schedules are executed in the timezone set up on your [profile ](https://app.scaleserp.com/profile).
`Note` When using `schedule_hours` in combination with `schedule_type=minutes` the Batch is executed at the per-minute frequency set in `schedule_minutes` throughout the hours set in `schedule_hours` . For example, if you set `schedule_type=minutes` , `schedule_minutes=every_5_minutes` and `schedule_hours=[10,11,12]` your Batch would be run every 5 minutes between the hours of 10am and 1pm. If you wish for a `schedule_type=minutes` Batch to be run continuously 24/7 then you shoud omit the `schedule_hours` parameter. | | `schedule_minutes` | `optional` | Determines the minutes frequency that the Batch is run when `schedule_type=minutes` . `Parameter Values`
1) `every_minute` 2) Run the Batch every minute

1) `every_5_minutes` 2) Run the Batch every 5 minutes

1) `every_10_minutes` 2) Run the Batch every 10 minutes

1) `every_15_minutes` 2) Run the Batch every 15 minutes

1) `every_20_minutes` 2) Run the Batch every 20 minutes

1) `every_25_minutes` 2) Run the Batch every 25 minutes

1) `every_30_minutes` 2) Run the Batch every 30 minutes

1) `every_hour` 2) Run the Batch every hour
`Note` When using `schedule_type=minutes` Batches are run at the selected frequency 24/7 unless specific hours are chosen in the `schedule_hours` parameter, specific days of the week are chosen in the `schedule_days_of_week` parameter or specific days of the month are chosen in the `schedule_days_of_month` parameter. | | `destination_ids` | `optional` | Specifies an array of Destination IDs (i.e. Amazon S3 Buckets, Google Cloud Storage buckets, Microsoft Azure Blob Storage or Alibaba Cloud OSS Buckets) that Result Sets from this Batch are uploaded to. Destination IDs can be retrieved through the Dashboard or via the Destinations API. | | `notification_email` | `optional` | The email address to send notifications to when new [Result Sets ](https://docs.trajectdata.com/scaleserp/batches-api/results/list)are available for this Batch. | | `notification_webhook` | `optional` | The URL Scale SERP will send a [webhook ](https://docs.trajectdata.com/scaleserp/batches-api/batches/webhook)POST to when new [Result Sets ](https://docs.trajectdata.com/scaleserp/batches-api/results/list)are available for this Batch. Should be a fully qualified URL, i.e. `https://yourserver.com/scaleserp` | | `notification_as_json` | `optional` | Determines whether Scale SERP sends download links (in the email notification if `notification_email` is set, or in the body of the [webhook ](https://docs.trajectdata.com/scaleserp/batches-api/batches/webhook)POST if `notification_webhook` is set) for the Batch [Result Sets ](https://docs.trajectdata.com/scaleserp/batches-api/results/list)in JSON format, or not.
If `destination_ids` are configured for this Batch then this setting determines whether Result Set files in JSON format are uploaded to the Destinations on Batch completion. `Parameter Values`
1) `true` 2) JSON output format enabled / sent

1) `false` 2) JSON output format disabled / not sent | | `notification_as_jsonlines` | `optional` | Determines whether Scale SERP sends download links (in the email notification if `notification_email` is set, or in the body of the [webhook ](https://docs.trajectdata.com/scaleserp/batches-api/batches/webhook)POST if `notification_webhook` is set) for the Batch [Result Sets ](https://docs.trajectdata.com/scaleserp/batches-api/results/list)in JSON Lines format, or not.
If `destination_ids` are configured for this Batch then this setting determines whether Result Set files in JSON Lines format are uploaded to the Destinations on Batch completion. `Parameter Values`
1) `true` 2) JSON Lines output format enabled / sent

1) `false` 2) JSON Lines output format disabled / not sent | | `notification_as_csv` | `optional` | Determines whether sends download links (in the email notification if `notification_email` is set, or in the body of the [webhook ](https://docs.trajectdata.com/scaleserp/batches-api/batches/webhook)POST if `notification_webhook` is set) for the Batch [Result Sets ](https://docs.trajectdata.com/scaleserp/batches-api/results/list)CSV format, or not. To set the CSV fields included in the Result Set use the `csv_fields` parameter.
If `destination_ids` are configured for this Batch then this setting determines whether Result Set files in CSV format are uploaded to the Destinations on Batch completion.
`Parameter Values`
1) `true` 2) CSV output format enabled / sent

1) `false` 2) CSV output format disabled / not sent | | `notification_csv_fields` | `optional` | Determines the fields that are returned when `notification_as_csv=true` . Should be specified as a comma seperated list of fields (in nested field, dot notation, format). For more information see the [CSV Fields Reference ](https://docs.trajectdata.com/scaleserp/search-api/reference/csv-fields). | | `searches_type` | `optional` | Determines whether this Batch is locked to only allow searches of the specified type to be added to it.
Locking a Batch to a specific search type has several benefits including allowing Scale SERP to automatically choose the correct CSV fields, appropriate to the searches in the Batch, to be selected by default when exporting a Result Set in CSV mode. It can also help organize your account when you have many Batches set up.
To allow any searches type to be added either omit `searches_type` entirely, or set it to `mixed` .
When set, the `searches_type_locked=true` property is present when retrieving the Batch letting you know that the Batch is locked.
If you leave the Batch as unlocked (i.e. by setting `searches_type=mixed` ) then `searches_type_locked=false` will be present when retrieving the Batch and `searches_type` will be set to either `mixed` (in the case of the Batch containing mixed searches types) or a `searches_type` value automatically detected based on the type of searches that have been subsequently added to the Batch.
`Note` The `searches_type` cannot be changed after the Batch is created.
For more information see the [Batch Locking ](https://docs.trajectdata.com/scaleserp/batches-api/locking)documentation.
Valid values for `searches_type` are: `Parameter Values`
1) `mixed` 2) Allow searches of any type to be added to this Batch.

1) `web` 2) Lock the Batch to allow only searches of type 'web' to be added.

1) `news` 2) Lock the Batch to allow only searches of type 'news' to be added.

1) `images` 2) Lock the Batch to allow only searches of type 'images' to be added.

1) `videos` 2) Lock the Batch to allow only searches of type 'videos' to be added.

1) `places` 2) Lock the Batch to allow only searches of type 'places' to be added.

1) `shopping` 2) Lock the Batch to allow only searches of type 'shopping' to be added.

1) `autocomplete` 2) Lock the Batch to allow only searches of type 'autocomplete' to be added.

1) `place_details` 2) Lock the Batch to allow only searches of type 'place\_details' to be added.

1) `place_reviews` 2) Lock the Batch to allow only searches of type 'place\_reviews' to be added.

1) `place_products` 2) Lock the Batch to allow only searches of type 'place\_products' to be added.

1) `place_posts` 2) Lock the Batch to allow only searches of type 'place\_posts' to be added.

1) `scholar` 2) Lock the Batch to allow only searches of type 'scholar' to be added.

1) `product` 2) Lock the Batch to allow only searches of type 'product' to be added.

1) `product_sellers_online` 2) Lock the Batch to allow only searches of type 'product\_sellers\_online' to be added.

1) `product_sellers_local` 2) Lock the Batch to allow only searches of type 'product\_sellers\_local' to be added.

1) `product_reviews` 2) Lock the Batch to allow only searches of type 'product\_reviews' to be added.

1) `product_specifications` Lock the Batch to allow only searches of type 'product\_specifications' to be added. | *** **Next Steps**      [Update Batches](https://docs.trajectdata.com/scaleserp/batches-api/batches/update)