Skip to content

Instantly share code, notes, and snippets.

@stephenlb stephenlb/
Last active Oct 3, 2016

What would you like to do?
PubNub History API V2

PubNub History API V2

URL Parameters:
start     (time token): Beginning of a timeline slice (exclusive)
end       (time token): Ending of a timeline slice (inclusive)
count        (integer): The number of messages to return (default:100, max:100)
callback      (string): JSONp callback function
reverse   (true/false): If we should traverse the timeline in reverse (default is false).
                  true: OLDEST  -->  newest.
                 false: NEWEST  -->  oldest.
Response Format:

Returns a JSON Array with three or more elements as follows:

  1. the list of messages
  2. the starting slice time token, and
  3. the ending slice time token.
[[msg, msg, msg], timetoken, timetoken]

Using a combination of start/end/reverse you can:

  • Traverse newest to oldest messages (default)
  • Traverse oldest to newest (setting reverse=true)
  • Page through results by providing a start OR end time token.
  • Retrieve a "slice" of the timeline by providing both a start AND end time token.

Include Token include_token=true

A new feature on the server-side that is available which includes the timetoken with each message. If you modify the REST call to send the include_token=true parameter in the history requests, you should get what you are looking for:

Include Token = True

JavaScript Example Code

// ----------------------------------
// Usage Example of get_all_history()
// ----------------------------------
    channel  : channel.value,
    callback : function(messages) {

// ----------------------------------
// Get All History Example
// ----------------------------------
function get_all_history(args) {
    var channel  = args['channel']
    ,   callback = args['callback']
    ,   start    = 0
    ,   count    = 100
    ,   history  = []
    ,   params   = {
            channel  : channel,
            count    : count,
            callback : function(messages) {
                var msgs = messages[0];
                start = messages[1];
                params.start = start;
                PUBNUB.each( msgs.reverse(), function(m) {history.push(m)} );
                if (msgs.length < count) return callback(history);
                count = 100;

    function add_messages() { PUBNUB.history(params) }

PubNub History REST API Examples:

GET Most Recent Messages
>>> [["Pub1","Pub2","Pub3","Pub4","Pub5"],13406746729185766,13406746845892666]
GET oldest 3 messages (in reverse):
>>> [["Pub1","Pub2","Pub3"],13406746729185766,13406746780720711]
GET messages newer than a given timetoken (OLD to NEW from START):
>>> [["Pub4","Pub5"],13406746814579888,13406746845892666]
GET messages until a given timetoken (NEW to OLD until an END):
>>> [["Pub3","Pub4","Pub5"],13406746780720711,13406746845892666]
GET any messages published on Tue, 26 Jun 2012 GMT (Unix timestamp in seconds * 10000000):
  • start (time token of Tues 26th): 13406688000000000
  • end (time token of Wed 27th): 13407552000000000
>>> [["Pub1","Pub2","Pub3","Pub4","Pub5"],13406746729185766,13406746845892666]

This comment has been minimized.

Copy link

attheodo commented Dec 21, 2014

@stephenlb the "include_timetoken" is missing as a valid argument for history() from your javascript API reference docs (along with some others). Although this gist was very helpful for discovering it, I suggest you include it in the API reference as well.


This comment has been minimized.

Copy link

dira commented Jan 22, 2015

@stephenlb +1 for adding it to the docs


This comment has been minimized.

Copy link

javanesevn commented Apr 13, 2016

I am using c# SDK.
The result timetoken of message from subscribe & history callback have different values.



Do they have the same timetoken value or not? I want to keep track timetoken of message to detect unread message for each clients.

Does PubNub support to track unread messages from server side? For those users unread their messages we can send the push notification to them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.