--- title: List Collections slug: backyardapi/collections-api/collections/list docTags: createdAt: 2024-07-23T14:57:52.062Z --- # 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. :::hint{type="info"} 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`
1) `contains` 2) **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.

1) `starts_with` 2) Returns Collections whose `name` property starts with the `search_term` (case-insensitive).

1) `ends_with` 2) Returns Collections whose `name` property ends with the `search_term` (case-insensitive).

1) `exact` 2) 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 ](https://docs.trajectdata.com/backyardapi/collections-api/collections/https://en.wikipedia.org/wiki/ISO_8601), 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 ](https://docs.trajectdata.com/backyardapi/collections-api/collections/https://en.wikipedia.org/wiki/ISO_8601), 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 ](https://docs.trajectdata.com/backyardapi/collections-api/collections/https://en.wikipedia.org/wiki/ISO_8601), 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 ](https://docs.trajectdata.com/backyardapi/collections-api/collections/https://en.wikipedia.org/wiki/ISO_8601), 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: :::CodeblockTabs HTTP ```HTTP https://api.backyardapi.com/collections?api_key=demo ``` ```curl $ curl "https://api.backyardapi.com/collections?api_key=demo" ``` ```nodejs const axios = require('axios'); const params = { api_key: 'demo' } axios.get('https://api.backyardapi.com/collections?api_key=demo') .then(response => { const apiResponse = response.data; console.log("Total Collections: ", apiResponse.total_count); apiResponse.collections.map((collection, number) => console.log((number + 1) + '. ' + collection.name); }).catch(error => { console.error(error); }); ``` ```python import requests params = { 'api_key': 'demo' } api_result = requests.get('https://api.backyardapi.com/collections', { params }) api_response = api_result.json() print "Total Collections: ", api_response['total_count'] for number, collection in enumerate(api_response['collections'], start=1): print "%s. %s" % (number, collection['name']) ``` ```php 'demo', ]); $ch = curl_init(sprintf('%s?%s', 'https://api.backyardapi.com/collections', $queryString)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); # the following options are required if you're using an outdated OpenSSL version # more details: https://www.openssl.org/blog/blog/2021/09/13/LetsEncryptRootCertExpire/ curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_TIMEOUT, 180); $json = curl_exec($ch); curl_close($ch); $api_result = json_decode($json, true); print_r($api_result); echo "Total Collections: ", $api_result['total_count'], PHP_EOL; foreach ($api_result['collections'] as $number => $collection) { echo "{$number}. {$collection['name']}", PHP_EOL; } ?> ``` ::: Backyard API responds with the following JSON showing all the Collections on your Backyard 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": "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](https://docs.trajectdata.com/backyardapi/collections-api/collections/webhook)      [List Requests](https://docs.trajectdata.com/backyardapi/collections-api/requests/list)      [List Result Sets](https://docs.trajectdata.com/backyardapi/collections-api/results/list)