List Collections

5min

List Collections
You can List all of the Collections currently set up on your account by making making a  HTTP GET request to the  /collections endpoint.
Note that the Collection List endpoint is rate-limited to 60 requests per minute. For real-time updates as to your Collection status it is recommended you use Webhooks.
﻿
Parameters
The following querystring (HTTP GET) parameters allow you to refine the results returned by the Collections 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 Collections that have Result Sets available.

only_without_results 

optional 

Set to  only_without_results=true  to only return Collections that have no Result Sets available (i.e. that haven't yet been run).

search_term 

optional 

Limits the returned Collections 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 Collections 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 Collections whose  name  property starts with the  search_term  (case-insensitive).
﻿
ends_with 
Returns Collections whose  name  property ends with the  search_term  (case-insensitive).
﻿
exact 
Returns Collections whose  name  property exactly matches the  search_term  (case-sensitive).
status 

optional 

Filters the Collections returned to only those matching the given status. Valid values are  all ,  idle ,  queued  or  running . Defaults to  all .
created_before 

optional 

Filters the Collections 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 Collections 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 Collections 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 Collections 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 Collections 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 Collections to return, defaults to  page=1 . Unless otherwise specified using the  page_size  parameter, 25 Collections 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 Collection creation date),  last_run  (to sort by the date the Collection was last run),  name  (to sort by Collection name, the default),  priority  (to sort by Collection priority) or  status  (to sort by Collection 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  /collections
In the example below we List all the Collections on your account:
HTTP
Curl
Node.js
Python
PHP
https://api.bigboxapi.com/collections?api_key=demo
https://api.bigboxapi.com/collections?api_key=demo
﻿
BigBox API responds with the following JSON showing all the Collections on your BigBox API account:
JSON
{
  "request_info": {
    "success": true
  },
  "total_count": 2,
  "total_pages": 1,
  "current_page": 1,
  "count_this_page": 2,
  "collections": [
    {
      "id": "2A6F94BB",
      "created_at": "2020-01-01T00:00:01.000Z",
      "last_run": "2020-09-01T00:00:00.000Z",
      "name": "My Second Collection",
      "schedule_type": "weekly",
      "priority": "normal",
      "destination_ids": [
        "destination_id_1",
        "destination_id_2"
      ],
      "enabled": true,
      "status": "idle",
      "requests_total_count": 0,
      "requests_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 Collection",
      "schedule_type": "daily",
      "priority": "normal",
      "destination_ids": [],
      "enabled": true,
      "status": "idle",
      "requests_total_count": 0,
      "requests_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,
  "collections": [
    {
      "id": "2A6F94BB",
      "created_at": "2020-01-01T00:00:01.000Z",
      "last_run": "2020-09-01T00:00:00.000Z",
      "name": "My Second Collection",
      "schedule_type": "weekly",
      "priority": "normal",
      "destination_ids": [
        "destination_id_1",
        "destination_id_2"
      ],
      "enabled": true,
      "status": "idle",
      "requests_total_count": 0,
      "requests_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 Collection",
      "schedule_type": "daily",
      "priority": "normal",
      "destination_ids": [],
      "enabled": true,
      "status": "idle",
      "requests_total_count": 0,
      "requests_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 Requests
     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 Collections that have Result Sets available.
only_without_results	optional	Set to only_without_results=true to only return Collections that have no Result Sets available (i.e. that haven't yet been run).
search_term	optional	Limits the returned Collections 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 Collections 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 Collections whose name property starts with the search_term (case-insensitive). ends_with Returns Collections whose name property ends with the search_term (case-insensitive). exact Returns Collections whose name property exactly matches the search_term (case-sensitive).
status	optional	Filters the Collections returned to only those matching the given status. Valid values are all , idle , queued or running . Defaults to all .
created_before	optional	Filters the Collections 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 Collections 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 Collections 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 Collections 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 Collections 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 Collections to return, defaults to page=1 . Unless otherwise specified using the page_size parameter, 25 Collections 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 Collection creation date), last_run (to sort by the date the Collection was last run), name (to sort by Collection name, the default), priority (to sort by Collection priority) or status (to sort by Collection 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 07 Aug 2024

Did this page help you?

Get Collection

Webhook