Pagination

The Platform currently supports three types of pagination:

• Offset-based pagination
• Time-based pagination
• Cursor-based pagination

Cursor-based Pagination

Cursor pagination is our preferred method of paging, and the list of Graph API endpoints which support it are growing. A cursor refers to a random string of characters which mark a specific point in a list of data. You can reliably assume that a cursor will always point to that same part of the list and use it to page through the data.

If you are using additional filters on the API endpoint when you receive a cursor, this cursor will only work for calls with those filters.

When using an endpoint that supports cursor pagination, you will see the following JSON response:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "cursors": {
      "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
      "before": "NDMyNzQyODI3OTQw"
    },
    "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw"
    "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
  }
}

Supports the following parameters:

• before : This is the cursor that points to the start of the page of data that has been returned.
• after : This is the cursor that points to the end of the page of data that has been returned.
• limit : This is the number of individual objects that are returned in each page. Note that this is an upper limit, if there are not enough remaining objects in the list of data, then less than this number will be returned.
• next : The Graph API endpoint that will return the next page of data. If not included, this is the last page of data.
• previous : The Graph API endpoint that will return the previous page of data. If not included, this is the first page of data.

Returned results under cursor paging more consistently match the limit requested, even after hiding any records for which you do not have permissions to view (eg. if you request 10 records, but do not have permissions to see 3 of those records, 3 additional records will be pulled transparently, so that a full 10 records are pulled).

The following Graph API connections are cursor-based with more coming soon:

• /photos
• /albums
• /links
• /notes
• /admins
• /comments

Using Cursors to Check for New Content

When you first make an API call and get a cursor-paged list of objects, the end of the list will be the point at which you do not receive another next parameter with the response. You will still, however, receive an after cursor, and you can use this pointer to determine when the list of objects has been updated with additional entries.

As an example, imagine a request to /comments on a post by a Page, which would return the following paging info:

  "paging": {
    "cursors": {
      "after": "abcd1234",
      "before": "wxyz0987"
    },
    "previous": "https://graph.facebook.com/12345/comments?limit=25&after=efgh5678"
  }

The app that makes this request now has a list of comments posted as well as a cursor that points to the end of that list, abcd1234. Then, after a period of time, to determine whether there are any new comments on the post, the app would make the following API call:

GET https://graph.facebook.com/12345/comments?limit=25&after=abcd1234

If there have been new comments, this call will have a list of comment objects as data, all of which will be comments posted after the first API call. If there have been no new comments, an empty set will be returned.

Time-based Pagination

Time pagination is used to navigate through results data using Unix timestamps which point to specific times in a list of data. Time paging can be less accurate than cursors because it may not always represent the same part of a list.

When using an endpoint that uses time-based pagination, you will see the following JSON response:

{
  "data": [
     ... Endpoint data is here
  ],
  "paging": {
    "previous": "https://graph.facebook.com/me/feed?limit=25&since=1364849754",
    "next": "https://graph.facebook.com/me/feed?limit=25&until=1364587774"
  }
}

Supports the following parameters:

• until : A Unix timestamp or strtotime data value that points to the end of the range of time-based data.
• since : A Unix timestamp or strtotime data value that points to the start of the range of time-based data.
• limit : This is the number of individual objects that are returned in each page.
• next : The Graph API endpoint that will return the next page of data.
• previous : The Graph API endpoint that will return the previous page of data.

Offset-based Pagination

Offset pagination can be applied to any Graph API endpoint in combination with any other type of pagination. It can be used on its own when you do not care about chronology and just want a specific number of objects returned.

Supports the following parameters:

• offset : This offsets the start of each page by the number specified.
• limit : This is the number of individual objects that are returned in each page.

Note that if new objects are added to the list of items being paged, the contents of each offset-based page will change.