Create Searches
Adding Searches to a Batch is achieved by making an HTTP PUT to the /batches/BATCH_ID endpoint (where BATCH_ID is the id of the Batch to add Searches to). The body of the request should be a JSON array of search objects (up to 1000 Searches can be added per call). The maximum number of Searches per Batch is 15,000 (or 100 when adding searches with include_html=true set).
The /batches/BATCH_ID endpoint used for adding Searches to a Batch is the same endpoint as used when Updating a Batch, we've just listed them seperately in the Docs for ease of reference.
The parameters for creating a Search are the same as those used when making a request via the Search API.
Batch Status Searches can only be added to a Batch when the Batch is not running. To check whether a Batch is currently running use the Get Batch endpoint.
Concurrency when Creating Searches You should make calls to the Create Search endpoint sequentially, rather than in parallel. Each call can contain up to 1000 Search to add though. If you make too many concurrent calls you will receive an HTTP 429 error.
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.
PUT /batches/BATCH_ID
In the example below we add a new Search to a Batch with id=123456 :
Custom IDs When you add a Search to a Batch VALUE SERP assigns it an unique id - you can use this id to track the Search across multiple Result Sets.
VALUE SERP also lets you specify your own custom_id , in addition to the VALUE SERP-assigned id, making it easy to use an ID from your app track Searches.
VALUE SERP responds with the following JSON confirming the Searches have been successfully created. Note the searches_total_count now reflects the count of the Searches the Batch has, including those just added. To List the Searches in the Batch use the List Searches endpoint:
Next Steps Update Search Delete Search List Searches