Paginate across Pinwheel's data

Pinwheel offers a number of list endpoints to retrieve collections of data (e.g. employers, platforms, etc). When you call one of these API methods to retrieve data, you will now receive a portion (or page) of data. Rather than having to wait to receive the full collection in a single request, you can now paginate through the data with faster individual requests.

How does pagination work?

To return pages of data for large lists, Pinwheel uses cursor-based pagination. A cursor is like a pointer; it refers to a particular point in the data and marks the boundary between pages. Our paginated endpoints will now return responses with both a list of results and a next_cursor pointing to the next page of data for that endpoint. This next_cursor can then be supplied in subsequent requests to the same endpoint to retrieve the following page of data. Once you've reached the end of the collection, the final response you receive will have a null next_cursor.

Requests to paginated endpoints will now all support limit and cursor parameters. The limit parameter is used to determine how large the result set should be, while the cursor parameter tells us which page of data you want. To retrieve the first page of data, the cursor parameter should not be supplied.

The following examples illustrate how the aforementioned limit and cursor fields should be used:

GET /employers
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "limit": 25,
  ...
}

Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "data": [
    ... 
  ],
  "meta": {
    "count": 25,
    "next_cursor": "eyJuYW1lIjogImFtYXpvbiJ9"
  }
}

GET /employers
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "limit": 25,
  "cursor": "eyJuYW1lIjogImFtYXpvbiJ9",
  ...
}

Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "data": [
    ... 
  ],
  "meta": {
    "count": 25,
    "next_cursor": "eyJuYW1lIjogImJpbmcifQ=="
  }
}

GET /employers
Host: api.getpinwheel.com
Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "limit": 25,
  "cursor": "eyJuYW1lIjogImJpbmcifQ==",
  ...
}

Content-Type: application/json
Pinwheel-Version: 2022-03-02

{
  "data": [
    ... 
  ],
  "meta": {
    "count": 25,
    "next_cursor": null
  }
}

See List Employers for an example of a paginated endpoint.

Please contact [email protected] for access to our Dashboard.