Pagination

For endpoints that list resources, such as List services and List deploys, results are returned in the form of a list of resources. As these lists can potentially be quite large, we utilize cursor-based pagination for returning lists of resources.

The two parameters to note when sending requests to list endpoints are limit and cursor.

The limit query parameter determines how many resources will be returned from a request. It defaults to 20, and accepts a maximum of 100.

The cursor query parameter specifies that you want to return resources that appear after the cursor of a specific entry in a list of resources.

How to Use

To get the first page of resources from a list endpoint, don't include the cursor query parameter at all. Your request will return a list of resources paired with cursors, like so:

[
  {
    "cursor": "cfQ74cE2sDI=",
    "service": {
      "id": "srv-xxxxx",
      "name" "Test Service",
      ...
    }
  },
  {
    "cursor": "mpFjFKeYgnw=",
    "service": {
      "id": "srv-xxxxx",
      "name" "A Second Service",
      ...
    }
  },
]

You should note that the cursor is not part of the resource object, but is instead returned alongside it.

If there's more resources beyond what were returned from this, you'll need to send another request to this endpoint. This time, though, you should include the cursor of the last returned resource as the cursor query parameter for your request, like so:

curl --request GET \
     --url 'https://api.render.com/v1/services?cursor=mpFjFKeYgnw=' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{render_api_token}}'

This will return the items in the list that come after that cursor, and you can keep doing this until you get to the end of the resource list.