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.redcircleapi.com/collections?api_key=demo
https://api.redcircleapi.com/collections?api_key=demo
﻿
RedCircle API responds with the following JSON showing all the Collections on your RedCircle 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 08 Aug 2024

Did this page help you?

Get Collection

Webhook