Table of Contents

Pagination
Using Relative Links for Pagination
Response Limits

Pagination

🚧

Paginating when using user tokens

Please note that you will not be able to paginate or use the limit param when querying the API with a user token generated in the SSO flow. Paginating only works with district bearer tokens provided through a Secure Sync subscription.

Queries on the Clever API can return large numbers of results. To improve performance and make the data more consumable, the Clever API supports paginating large responses.

To iterate through results, you should follow the rel:next link contained with every set of results. For example, querying the /users endpoint with a district bearer token you might see the following:

"links": [
    {
      "rel": "next",
      "uri": "/v3.0/users?starting_after=530e5961049e75a9262cffe4"
    }
  ]

The link uses the starting_after parameter to jump to the next page of results. This form of pagination is called range-based pagination. Elements are returned sorted with ascending IDs (based on create time).

Using Relative Links for Pagination

If there are more results to consume, the response's links object will have a rel link called next, that lets you query the next page of results. Similarly, there may be a prev link for the previous page of results.

Example links object for request GET /v3.0/districts?starting_after=53ced71e65a64d5918157c04:

"links": [
    {
        "rel": "self",
        "uri": "/v3.0/districts?starting_after=53ced71e65a64d5918157c04"
    },
    {
        "rel": "next",
        "uri": "/v3.0/districts?starting_after=56fad73b82c6fd818c6b48cc"
    },
    {
        "rel": "prev",
        "uri": "/v3.0/districts?ending_before=53ced71e65a64d5918157c04"
    }
]

📘

Queries

starting_after queries may have prev links even when there are no previous results. Following such links will return an empty array of data. Similarly, ending_before queries may have next links even when there are no more results, and following those links will return an empty array.

Response Limits

Rather than serving every result at once, by default the Clever API limits the number of entries in responses to 100 per page. You can change the number of results returned by setting the limit parameter. For instance, GET /v3.0/users?limit=30 returns at most 30 students

📘

Maximum limit

The maximum limit is 10000 records per page.