Multiple times a day, I switch between my laptop and my phone. It’s frustrating that I have to ask myself “have I seen this post?” as I scroll through My Stream. Today we’re adding support for Stream Markers to the API. This will allows clients to sync where you are in your stream, global, and even in individual threads between clients.

In the response envelope for all streams that support markers, there will now be a Stream Marker object. If a marker hasn’t been set, it will just include the name of the stream so you can set a marker:

$ curl -H 'Authorization: BEARER [access token]' "https://alpha-api.app.net/stream/0/posts/stream/unified"
{
    "data": [...],
    "meta": {
        "code": 200,
        "marker": {
            "name": "unified"
        },
        "max_id": 65009,
        "min_id": 65009,
        "more": true
    }
}

If a marker has been set, it will include information about when the marker was last updated including the Post ID of the post at the top of the window, a timestamp, and an opaque value representing the version of this marker so you can easily see if it’s been updated.

$ curl -H 'Authorization: BEARER [access token]' "https://alpha-api.app.net/stream/0/posts/stream/global"
{
    "data": [...],
    "meta": {
        "code": 200,
        "marker": {
            "id": "50000",
            "name": "global",
            "percentage": 0,
            "updated_at": "2012-11-09T23:35:38Z",
            "version": "NWoZK3kTsExUV00Ywo1G5jlUKKs"
        },
        "max_id": 65109,
        "min_id": 65109,
        "more": true
    }
}

Stream Markers aren’t meant to broadcast a User scrolling through a stream in real time so we recommend that you only update a marker when a user is changing to a different stream, closing the client, or has stopped scrolling for at least 10 seconds. To update a marker, just POST a JSON dictionary that matches our Stream Marker schema with the correct stream name:

$ curl -H 'Authorization: BEARER [access token]' -H "Content-Type: application/json" -X POST -d '{"name": "global", "id": 50001}' "https://alpha-api.app.net/stream/0/posts/marker"
{
    "data": {
        "id": "50001",
        "name": "global",
        "percentage": 0,
        "updated_at": "2012-11-12T22:24:04Z",
        "version": "G2RTiSRzpGfQc3LUXrBavCAxZHo"
    },
    "meta": {
        "code": 200
    }
}

If you store the “version” that’s returned, you’ll be able to tell when a user has changed position on a different client and update accordingly.

Currently the following streams can be marked:

• Global Stream
• My Stream
• Unified Stream
• My Mentions
• An individual user’s stream of posts
• A hashtag stream
• The replies stream for a post

As always, let us know if you have any feedback through any of the developer support channels listed here.