List Batches

5min

List Batches
You can List all of the Batches currently set up on your account by making making a  HTTP GET request to the  /batches endpoint.
Note that the Batch List endpoint is rate-limited to 60 requests per minute. For real-time updates as to your Batch status it is recommended you use Webhooks.
﻿
Parameters
The following querystring (HTTP GET) parameters allow you to refine the results returned by the Batches List API.
Parameter
Required
Description
api_key
required
The API key for your account.
only_with_results
optional
Set to only_with_results=true to only return Batches that have Result Sets available.
only_without_results
optional
Set to only_without_results=true to only return Batches that have no Result Sets available (i.e. that haven't yet been run).
search_term
optional
Limits the returned Batches to just those containing the search_term in their name.
search_type
optional
Determines how the search_term parameter is treated. Valid values are:
Parameter Values
contains
 Default returns Batches that contains all of the words (split by spaces) in the search_term in their name or id properties (case-insensitive). Non alphanumeric characters are replaced by spaces.
﻿
starts_with
Returns Batches whose name property starts with the search_term (case-insensitive).
﻿
ends_with
Returns Batches whose name property ends with the search_term (case-insensitive).
﻿
exact
Returns Batches whose name property exactly matches the search_term (case-sensitive).
status
optional
Filters the Batches returned to only those matching the given status. Valid values are all , idle , queued or running . Defaults to all .
created_before
optional
Filters the Batches returned to only those with a created_at date before the value specified. Should be specified as an ISO UTC timestamp , for example created_before=2020-09-01T00:00:00.000Z .
created_after
optional
Filters the Batches returned to only those with a created_at date after the value specified. Should be specified as an ISO UTC timestamp , for example created_after=2020-06-01T00:00:00.000Z .
last_run_before
optional
Filters the Batches returned to only those with a last_run date before the value specified. Should be specified as an ISO UTC timestamp , for example last_run_before=2020-09-01T00:00:00.000Z .
last_run_after
optional
Filters the Batches returned to only those with a last_run date after the value specified. Should be specified as an ISO UTC timestamp , for example last_run_after=2020-06-01T00:00:00.000Z .
destination_id
optional
Filters the Batches returned to only those with the specified destination_id set. You can view destination IDs on the Destinations page of the Dashboard or via the Destinations API.
page
optional
Set the page number of Batches to return, defaults to page=1 . Unless otherwise specified using the page_size parameter, 25 Batches are returned per page.
page_size
optional
Sets the number of results returned per page. If the page_size parameter is omitted then 25 results are returned per page by default. The maximum number of results returned per page is 1000 ( page_size=1000 ).
sort_by
optional
The sort order to apply to the results. Valid values are created_at (to sort by Batch creation date), last_run (to sort by the date the Batch was last run), name (to sort by Batch name, the default), priority (to sort by Batch priority) or status (to sort by Batch status). Use in conjunction with the sort_direction parameter.
sort_direction
optional
The sort direction to return results. Valid values are descending or ascending (the default). Use in conjunction with the sort_by parameter.
Example
﻿GET  /batches
In the example below we List all the Batches on your account:
HTTP
Curl
Node.js
Python
PHP
https://api.valueserp.com/batches?api_key=demo
https://api.valueserp.com/batches?api_key=demo
﻿
VALUE SERP responds with the following JSON showing all the Batches on your VALUE SERP account:
JSON
{
  "request_info": {
    "success": true
  },
  "total_count": 2,
  "total_pages": 1,
  "current_page": 1,
  "count_this_page": 2,
  "batches": [
    {
      "id": "2A6F94BB",
      "created_at": "2020-01-01T00:00:01.000Z",
      "last_run": "2020-09-01T00:00:00.000Z",
      "name": "My Second Batch",
      "schedule_type": "weekly",
      "priority": "normal",
      "destination_ids": [
        "destination_id_1",
        "destination_id_2"
      ],
      "enabled": true,
      "status": "idle",
      "searches_total_count": 0,
      "searches_page_count": 0,
      "next_result_set_id": 1,
      "results_count": 0,
      "schedule_days_of_week": [
        0,
        3
      ],
      "schedule_hours": [
        8
      ],
      "notification_email": "[email protected]",
      "notification_as_json": false,
      "notification_as_jsonlines": false,
      "notification_as_csv": false
    },
    {
      "id": "CAC8651D",
      "created_at": "2020-01-02T00:00:00.000Z",
      "last_run": "2020-09-01T00:10:00.000Z",
      "name": "My First Batch",
      "schedule_type": "daily",
      "priority": "normal",
      "destination_ids": [],
      "enabled": true,
      "status": "idle",
      "searches_total_count": 0,
      "searches_page_count": 0,
      "results_count": 0,
      "schedule_hours": [
        9,
        17
      ],
      "notification_email": "[email protected]",
      "notification_as_json": false,
      "notification_as_csv": true
    }
  ]
}
{
  "request_info": {
    "success": true
  },
  "total_count": 2,
  "total_pages": 1,
  "current_page": 1,
  "count_this_page": 2,
  "batches": [
    {
      "id": "2A6F94BB",
      "created_at": "2020-01-01T00:00:01.000Z",
      "last_run": "2020-09-01T00:00:00.000Z",
      "name": "My Second Batch",
      "schedule_type": "weekly",
      "priority": "normal",
      "destination_ids": [
        "destination_id_1",
        "destination_id_2"
      ],
      "enabled": true,
      "status": "idle",
      "searches_total_count": 0,
      "searches_page_count": 0,
      "next_result_set_id": 1,
      "results_count": 0,
      "schedule_days_of_week": [
        0,
        3
      ],
      "schedule_hours": [
        8
      ],
      "notification_email": "john.smith@example.com",
      "notification_as_json": false,
      "notification_as_jsonlines": false,
      "notification_as_csv": false
    },
    {
      "id": "CAC8651D",
      "created_at": "2020-01-02T00:00:00.000Z",
      "last_run": "2020-09-01T00:10:00.000Z",
      "name": "My First Batch",
      "schedule_type": "daily",
      "priority": "normal",
      "destination_ids": [],
      "enabled": true,
      "status": "idle",
      "searches_total_count": 0,
      "searches_page_count": 0,
      "results_count": 0,
      "schedule_hours": [
        9,
        17
      ],
      "notification_email": "john.smith@example.com",
      "notification_as_json": false,
      "notification_as_csv": true
    }
  ]
}
﻿
﻿
Next Steps
     Webhook
     List Searches
     List Result Sets﻿

Parameter	Required	Description
api_key	required	The API key for your account.
only_with_results	optional	Set to only_with_results=true to only return Batches that have Result Sets available.
only_without_results	optional	Set to only_without_results=true to only return Batches that have no Result Sets available (i.e. that haven't yet been run).
search_term	optional	Limits the returned Batches to just those containing the search_term in their name.
search_type	optional	Determines how the search_term parameter is treated. Valid values are: Parameter Values contains Default returns Batches that contains all of the words (split by spaces) in the search_term in their name or id properties (case-insensitive). Non alphanumeric characters are replaced by spaces. starts_with Returns Batches whose name property starts with the search_term (case-insensitive). ends_with Returns Batches whose name property ends with the search_term (case-insensitive). exact Returns Batches whose name property exactly matches the search_term (case-sensitive).
status	optional	Filters the Batches returned to only those matching the given status. Valid values are all , idle , queued or running . Defaults to all .
created_before	optional	Filters the Batches returned to only those with a created_at date before the value specified. Should be specified as an ISO UTC timestamp , for example created_before=2020-09-01T00:00:00.000Z .
created_after	optional	Filters the Batches returned to only those with a created_at date after the value specified. Should be specified as an ISO UTC timestamp , for example created_after=2020-06-01T00:00:00.000Z .
last_run_before	optional	Filters the Batches returned to only those with a last_run date before the value specified. Should be specified as an ISO UTC timestamp , for example last_run_before=2020-09-01T00:00:00.000Z .
last_run_after	optional	Filters the Batches returned to only those with a last_run date after the value specified. Should be specified as an ISO UTC timestamp , for example last_run_after=2020-06-01T00:00:00.000Z .
destination_id	optional	Filters the Batches returned to only those with the specified destination_id set. You can view destination IDs on the Destinations page of the Dashboard or via the Destinations API.
page	optional	Set the page number of Batches to return, defaults to page=1 . Unless otherwise specified using the page_size parameter, 25 Batches are returned per page.
page_size	optional	Sets the number of results returned per page. If the page_size parameter is omitted then 25 results are returned per page by default. The maximum number of results returned per page is 1000 ( page_size=1000 ).
sort_by	optional	The sort order to apply to the results. Valid values are created_at (to sort by Batch creation date), last_run (to sort by the date the Batch was last run), name (to sort by Batch name, the default), priority (to sort by Batch priority) or status (to sort by Batch status). Use in conjunction with the sort_direction parameter.
sort_direction	optional	The sort direction to return results. Valid values are descending or ascending (the default). Use in conjunction with the sort_by parameter.

Updated 21 Aug 2024

Did this page help you?

Get Batch

Webhook