Create Batch

7min

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 VALUE 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.
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":
Curl
Node.js
Python
PHP
$ curl "https://api.valueserp.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="[email protected]" \
  -d notification_as_csv=true
$ curl "https://api.valueserp.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
﻿
VALUE 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, delete and add Searches 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": "[email protected]",
    "notification_as_json": false,
    "notification_as_csv": true,
    "search_type": "mixed",
    "search_type_locked": false
  }
}
{
  "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 VALUE SERP Dashboard or the Start Batch API.
A Batches' schedule is defined by the schedule_type parameter. The values of schedule_type , and other associated parameters are shown below:
Batch schedules are executed in the timezone set up on your profile﻿
schedule_type
Scheduling Parameters
monthly
schedule_days_of_month 
Array of days of the month to run the Batch, i.e. [1,20] for the 1st & 20th
﻿
schedule_hours 
Array of hours of the day to run the Batch, i.e. [9,17] for 9am & 5pm
weekly
schedule_days_of_week 
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
﻿
schedule_hours 
Array of hours of the day to run the Batch, i.e. [9,17] for 9am & 5pm
daily
schedule_hours 
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 VALUE SERP Dashboard or the Start Batch API .
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
true 
Batch is enabled
﻿
false 
Batch is disabled
schedule_type
optional
Determines the type of schedule the Batches uses. 
Parameter Values
monthly 
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.
﻿
weekly 
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.
﻿
daily 
Batch is run on a daily schedule, use schedule_hours to determine which hours of the day the Batch is run.
﻿
minutes 
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.
﻿
manual 
Batch is run manually, use the VALUE SERP Dashboard or the Start Batch API to start the Batch.
priority
optional
Determines the priority of the Batch. When multiple Batches are queued, VALUE SERP starts them in priority order. Learn more about priorities . 
Parameter Values
highest
﻿
high
﻿
normal
﻿
low
﻿
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 .  
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
every_minute 
Run the Batch every minute
﻿
every_5_minutes 
Run the Batch every 5 minutes
﻿
every_10_minutes 
Run the Batch every 10 minutes
﻿
every_15_minutes 
Run the Batch every 15 minutes
﻿
every_20_minutes 
Run the Batch every 20 minutes
﻿
every_25_minutes 
Run the Batch every 25 minutes
﻿
every_30_minutes 
Run the Batch every 30 minutes
﻿
every_hour 
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 are available for this Batch.
notification_webhook
optional
The URL VALUE SERP will send a webhook POST to when new Result Sets are available for this Batch. Should be a fully qualified URL, i.e. https://yourserver.com/valueserp
notification_as_json
optional
Determines whether VALUE SERP sends download links (in the email notification if notification_email is set, or in the body of the webhook POST if notification_webhook is set) for the Batch Result Sets 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
true 
JSON output format enabled / sent
﻿
false 
JSON output format disabled / not sent
notification_as_jsonlines
optional
Determines whether VALUE SERP sends download links (in the email notification if notification_email is set, or in the body of the webhook POST if notification_webhook is set) for the Batch Result Sets 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
true 
JSON Lines output format enabled / sent
﻿
false 
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 POST if notification_webhook is set) for the Batch Result Sets 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
true 
CSV output format enabled / sent
﻿
false 
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 .
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 VALUE 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 documentation.  
Valid values for searches_type are:  Parameter Values
mixed 
Allow searches of any type to be added to this Batch.
﻿
web 
Lock the Batch to allow only searches of type 'web' to be added.
﻿
news 
Lock the Batch to allow only searches of type 'news' to be added.
﻿
images 
Lock the Batch to allow only searches of type 'images' to be added.
﻿
videos 
Lock the Batch to allow only searches of type 'videos' to be added.
﻿
places 
Lock the Batch to allow only searches of type 'places' to be added.
﻿
place_details 
Lock the Batch to allow only searches of type 'place_details' to be added.
﻿
shopping 
Lock the Batch to allow only searches of type 'shopping' to be added.
﻿
product 
Lock the Batch to allow only searches of type 'product' to be added.
﻿
product_sellers_online 
Lock the Batch to allow only searches of type 'product_sellers_online' to be added.
﻿
product_sellers_local 
Lock the Batch to allow only searches of type 'product_sellers_local' to be added.
﻿
product_reviews 
Lock the Batch to allow only searches of type 'product_reviews' to be added.
﻿
product_specifications 
Lock the Batch to allow only searches of type 'product_specifications' to be added.
﻿
Next Steps
     Update Batches﻿

schedule_type	Scheduling Parameters
monthly	schedule_days_of_month Array of days of the month to run the Batch, i.e. [1,20] for the 1st & 20th schedule_hours Array of hours of the day to run the Batch, i.e. [9,17] for 9am & 5pm
weekly	schedule_days_of_week 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 schedule_hours Array of hours of the day to run the Batch, i.e. [9,17] for 9am & 5pm
daily	schedule_hours 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 VALUE SERP Dashboard or the Start Batch API .

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 true Batch is enabled false Batch is disabled
schedule_type	optional	Determines the type of schedule the Batches uses. Parameter Values monthly 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. weekly 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. daily Batch is run on a daily schedule, use schedule_hours to determine which hours of the day the Batch is run. minutes 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. manual Batch is run manually, use the VALUE SERP Dashboard or the Start Batch API to start the Batch.
priority	optional	Determines the priority of the Batch. When multiple Batches are queued, VALUE SERP starts them in priority order. Learn more about priorities . Parameter Values highest high normal low 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 . 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 every_minute Run the Batch every minute every_5_minutes Run the Batch every 5 minutes every_10_minutes Run the Batch every 10 minutes every_15_minutes Run the Batch every 15 minutes every_20_minutes Run the Batch every 20 minutes every_25_minutes Run the Batch every 25 minutes every_30_minutes Run the Batch every 30 minutes every_hour 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 are available for this Batch.
notification_webhook	optional	The URL VALUE SERP will send a webhook POST to when new Result Sets are available for this Batch. Should be a fully qualified URL, i.e. https://yourserver.com/valueserp
notification_as_json	optional	Determines whether VALUE SERP sends download links (in the email notification if notification_email is set, or in the body of the webhook POST if notification_webhook is set) for the Batch Result Sets 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 true JSON output format enabled / sent false JSON output format disabled / not sent
notification_as_jsonlines	optional	Determines whether VALUE SERP sends download links (in the email notification if notification_email is set, or in the body of the webhook POST if notification_webhook is set) for the Batch Result Sets 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 true JSON Lines output format enabled / sent false 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 POST if notification_webhook is set) for the Batch Result Sets 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 true CSV output format enabled / sent false 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 .
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 VALUE 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 documentation. Valid values for searches_type are: Parameter Values mixed Allow searches of any type to be added to this Batch. web Lock the Batch to allow only searches of type 'web' to be added. news Lock the Batch to allow only searches of type 'news' to be added. images Lock the Batch to allow only searches of type 'images' to be added. videos Lock the Batch to allow only searches of type 'videos' to be added. places Lock the Batch to allow only searches of type 'places' to be added. place_details Lock the Batch to allow only searches of type 'place_details' to be added. shopping Lock the Batch to allow only searches of type 'shopping' to be added. product Lock the Batch to allow only searches of type 'product' to be added. product_sellers_online Lock the Batch to allow only searches of type 'product_sellers_online' to be added. product_sellers_local Lock the Batch to allow only searches of type 'product_sellers_local' to be added. product_reviews Lock the Batch to allow only searches of type 'product_reviews' to be added. product_specifications Lock the Batch to allow only searches of type 'product_specifications' to be added.

Updated 13 Aug 2024

Did this page help you?

Locking

Update Batch