Paginating collections

You cannot list/download all of your collection's resources at once: there can be too many.
So we provided you with standard scrolling features: as soon as you finish fetching a set of resources, you can trigger a second API call to fetch next resources according to the ordering configuration you are using in the request, then a third API call and so on.

The largest possible set of resources returned at one contains up to 25 resources and it's the default choice we provide to you. This means that if you have less than 25 resources in a collection, you don't have to worry about resources scrolling at all. However, when you have more than 25 resources in a collection, you'll need to download first 25 and then ask for resources from 26 to 50, and so on with 51 to 75 up to the totality of your resources.

Responses to listing endpoint are ordered lists of resources, according to sorting criteria and sorting direction.
If a request wasn't specifying any criteria and any direction (see Sorting collections), default values apply for sorting, depending on the collection's nature.

Limiting resources per request

A limit parameter is provided in all endpoints returning a collection of resources.
Such parameter is valued 25 (maximum) as default, but you can change with smaller values if you want your collection to be returned in more batches.


Do not rely on max limit

Please mind we reserve the ability to change anytime the maximum number of resources returned in a single listing request.

Getting all resources

A last parameter is provided in all endpoints returning a collection of resources.
Such parameter is not valued by default, but you can change it with the last id you fetched from the previous API listing request so that the current API request will return next set of resources according to the sorting criteria and direction you specified, starting from last (excluded) onward.

You can refer to the following snippet to understand how to retrieve all resources using subsequent API calls. The example is specific to Links, but you can apply it also to Workspaces, Domains, Tags, and to any Rebrandly resource supporting a listing.

import requests

apiKey = "YOUR_API_KEY"

workspace = None 
# to use a non-default workspace, set workspace id here
lastLink = None
# to resume downloading after a specific link, set link id in lastLink

pageSize = MAX_PAGE_SIZE

def getAllLinks(apiKey, workspace, pageSize=MAX_PAGE_SIZE):
  allLinks = []

  def downloadLinksAfter(lastLink):
    last = lastLink["id"] if lastLink else ""
    limit = pageSize
  	requestHeaders = {
      "Content-type": "application/json",
      "apikey": apiKey,
      "workspace": workspace
    endpoint = f"{limit}&last={last}"
    r = requests.get(endpoint, headers=requestHeaders)
    if (r.status_code !=
      raise Exception(f"Could not retrieve links, response code was {r.status_code}")
    links = r.json()
    return links
  keepDownloading = True
  lastDownloadedLink = { "id": lastLink } if lastLink or None
  while (keepDownloading):
    justDownloadedLinks = downloadLinksAfter(lastDownloadedLink)
    allLinks += justDownloadedLinks
    keepDownloading = any(justDownloadedLinks)
    if keepDownloading:
      lastDownloadedLink = justDownloadedLinks[-1]

  return allLinks
links = getAllLinks(apiKey, workspace, pageSize)