Pagination

Most App.net API endpoints that return lists of objects are paginated. Understanding how paginated data is requested and returned is key to retrieving data efficiently from the API.

Overview

App.net always returns items from newest to oldest. You paginate through results by passing before_id and since_id to the API which restricts the range of content App.net will return. By adjusting these parameters, you can consistently fill in the data you’re missing from the App.net API.

By default, when you request data App.net will return the most recent items that are older than before_id. If instead you’d like the least recent items that are newer than since_id, you can specify count as a negative value. As an example, if a stream contains:

10, 9, 8, 7, 6, 5, 4, 3, 2, 1

requesting it with before_id=9&since_id=2&count=2 returns

8, 7

requesting it with before_id=9&since_id=2&count=-2 returns

4, 3

In summary:

  • before_id and since_id define the range App.net will return results from. If provided, they should be filled in from a previous request’s min_id or max_id.
  • Every item in a paginated response will have a pagination_id attribute. This attribute is NOT unique for the individual item but it is unique per (user, api endpoint) pair. For example, if user 2 follows user 1 and subscribes to channel 1, user 2 will appear in both results for Users subscribed to a channel and Users following a user. But, the pagination_ids for user 2 in each of those responses will be different.
  • count tells App.net how many items you want. It defaults to 20 and cannot be more than 200.
  • If count is negative, App.net returns results starting from the since_id. Remember, items are always returned from newest to oldest even in this case.

Parameters

Requests for paginated streams can optionally be filtered by passing the following query string parameters along with the request:

Name Description
since_id Return objects following the max_id provided in the response metadata of a previous query or following one of the special pagination ids for streams with Stream Markers.
before_id Return objects preceding the min_id provided in the response metadata of a previous query or preceding one of the special pagination ids for streams with Stream Markers.
count The number of objects to return, up to a maximum of 200. If this value is negative, items will be returned starting at since_id. Please see the pagination overview for more information.

Special pagination ids

When requesting objects from an endpoint that supports Stream Markers, you can pass the following special values to the since_id and before_id pagination parameters:

Value Description
last_read Use the last_read_id of the current Stream Marker (if there is one) as the value.
last_read_inclusive Use the last_read_id of the current Stream Marker (if there is one) as the value. Also include the "last read" object.
marker Use the id of the current Stream Marker (if there is one) as the value.
marker_inclusive Use the id of the current Stream Marker (if there is one) as the value. Also include the "marked" object.

Response Metadata

Responses from paginated streams will include the following fields in the meta object of the response envelope.

Name Type Description
max_id string The greatest ID returned in the data set. Inclusive. This should be considered an opaque identifier that may be passed as since_id in the next call in order to retrieve the next set of objects.
min_id string The least ID returned in the data set. Inclusive. This should be considered an opaque identifier that may be passed as before_id in the next call in order to retrieve the previous set of objects.
more boolean If more is true, there are more matches available for the given query than would fit within count objects. If more is false, there are no more matches available.