How to get a list of spectatable live games in progress?

I would like to use the API to get a list of all live games that I can spectate? (i.e. the one that is accessed using and usually contains about 100 games)

I have tried this query:

But it returns over 10 000 results, not a hundred. Is there something I can add to the query to make it do show only the games on the “live games being played” screen?

You can check the time_per_move attribute, though we’ll have to poke @anoek for the cut off time for live games. I can never remember.

Thank you. I think, however, than even old live games are shown. It feels like some old games are never removed from the list.

Last time I tried it, I think the old ones were removed. Have you looked at the real time lists? We have a API set up so you can keep a constantly updated list.

I have some example snippets using it if you are interested. Also, we have a Slack channel for OGS development. If you are interested, send me a private message with an email that you don’t mind me having and I will send you an invite.

Yes, please! If you have any snippets, I am very interested in them!

I was already invited into the Slack channel! Thank you very much!

@anoek tells me that you got what you needed in the Slack channel?

Well, I have a lead on what API call to make. I’m still interested in the example snippets, though.

I’ll dig some of those up then. :smiley:

I’m also interested in those snippets, can I get them too?

The API call (seekgraph/connect, or seek_graph/connect) doesn’t seem to do anything, though. Does it need arguments?

Apologies for reviving this, though hopefully it contains useful information.

First include the socket code in your page somewhere

<script src=""></script>

Then connect to the server

     var socket = io('', {
        path: '/',
        transports: ['websocket'],

Once connected (probably using socket.on(‘connected’, …)) you can ask for a list of watchable games with

     socket.emit('gamelist/query', {
        list: 'live',
        sort_by: 'rank',
        from: 0,
        limit: 20,
     }, function(games) {});

IIUC the seekgraph calls are more about listing games that need another player (eg. for those “seeking” a game).

You may (or may not) need to filter the list that you get back, and each game has some properties to help you. The one I use to filter the viewable list is phase and I expect its value to be play

Appologies for reviving this thread too, but it’s the only mention of gamelist/query on the forum. I’m also trying to do this (from Android) but it frustratingly doesn’t work. I managed to log in, I managed to subscribe to other notifications (e.g. gamelist/count/subscribe) and I even managed to search for a game (e.g. automatch/find_match) but the gamelist query simply does not work. How can I debug this? There is no error, I simply do not receive the expected notifications!

val options = IO.Options()
options.transports = arrayOf("websocket")
val socket = IO.socket("", options)

// works
                    var obj = JSONObject()
                    obj.put("username", uiConfig.user.username)
                    obj.put("auth", uiConfig.chat_auth)
                    socket.emit("authenticate", obj)

// also works

// refuses to work
                    socket.emit("gamelist/query", createJsonObject {
                        put("list", "live")
                        put("sort_by", "rank")
                        put("from", 0)
                        put("limit", 9)

// even this very complicated one works
                    // json = createJsonObject() // lots of stuff here
                    socket!!.emit("automatch/find_match", json)

Any help would be appreciated

pinging @anoek

The code I shared earlier is still working for me, so I doubt there’s an issue on the server side. You’re showing a couple of different ways of creating the 2nd argument for the emit calls, and IIUC you don’t need to provide JSON, just a POJO will do!

I think the real cause of your issue is that you’re not providing the callback as the 3rd argument as the example illustrates…

eg. try

					socket.emit('gamelist/query', {
						list: 'live',
						sort_by: 'rank',
						from: 0,
						limit: 20,
					}, function(games) { console.log(games); });
1 Like

Hi Andrew, thank you very much for looking at this. I feel silly now, indeed, the results are returned through the third parameter (intuitively named Ack() in the Kotlin library), not asynchronousely as with the other calls (for example the seekgraph or the gamelist/count/subscribe). In my defence I spent 13 years programming mobiles and never had to deal with Socket.IO, the documentation on that is shoddy at best.

Btw, do you have any insight on why this request behaves differently than the others so that I know what to expect in the future?

PS: I know I can provide POJOs (aka data classes in Kotlin) but I am not at that point yet. At the moment I am just stitching together some code to prove that it can be done in Android. Code is here

For refference, this now works:

        socket!!.emit("gamelist/query", createJsonObject {
            put("list", "live")
            put("sort_by", "rank")
            put("from", 0)
            put("limit", 9)
        }, Ack {
            args -> { println(it) }

Hey MrAlex, yeah sorry about that, I’m not sure why I assumed you were working in javascript like I was :slight_smile:

Regarding the API behaviour, I could only suggest that it’s a design decision, and would prefer not to guess at the reasoning :slight_smile:

IMO if you’re making a call and expecting a once-off response (such as the gamelist) then passing a callback seems like a reasonable approach. If you’re subscribing to something that might emit multiple events (eg. watching a game and getting notifications of each move) then the event listener approach would be good. It does come down to the designers choice though, so the best we could ask for is reasonable documentation (or even the source).

To help you work through this API it might be worth adding a final argument to all your socket.emit() calls which logs the response so you can have some idea if it’s being used or not. Eg.

socket.emit('testing/event', {args}, function() { console.log(arguments); });

Thanks for sharing your code, and good luck!