API Resources

Pagination

The Disqus API offers pagination through the use of a concept called cursors. These are specially designed tokens that act as markers in a timeline. If an endpoint allows pagination through cursors, you'll receive an additional object as part of the the response, called cursor.

While most endpoints won't give you a value for total, they will give you next and previous cursors. In our example case, we'll be making a request to posts/list. At the top level of the response JSON we'll see the cursor key:

  "cursor": {
    "prev": null,
    "hasNext": true,
    "next": "1320872487989935:0:0",
    "hasPrev": false,
    "total": null,
  },

You'll also notice that the prev value is not set. In some cases there will not be a way to "navigate to the previous page". You will however, always have a next cursor. Even if there are no results on the next page, we'll still generate a cursor so that you can look for new updates when they're available.

To fetch this next page, we're going to take the value in next and pass it as the cursor parameter to our second request:

GET /api/3.0/posts/list.json?
    public_key=PUBLIC_KEY&
    cursor=1320872487989935:0:0

In the following request, you'll see we have a new next cursor, as well as a previous cursor (which will get us the results from our previous request):

  "cursor": {
    "prev": "1320872487989935:0:1",
    "hasNext": true,
    "next": "1320872485686114:0:0",
    "hasPrev": true,
    "total": null,
  },

You will also notice that both requests gave us hints whether the next or previous page actually has results on it, via the hasNext and hasPrev values.

That's all there is to it. The rest is magic under the hood of the Disqus API.