Sessions API

The Sessions API gives you the action log of a play session: every action anyone took at the table, in order, with who took it and which pieces it touched. Pull it into a spreadsheet or your own analysis tools.

Only people who can edit the game (its owner and collaborators) can use these endpoints.

What the log contains

The log includes everything, hidden information too: cards in every player's hand, pieces in restricted spaces, the faces of face-down cards. During play those are private to the players who hold them. The log is for the designer, which is why only editors of the game can download it.

How long you can download it

A session's history is kept for 24 hours after the session ends, or 90 days after it ends when the game's owner is on a Pro plan or the session is a Pro session. A session that never ends is deleted 30 days after its table was created, or after it was reopened. A reopened session is listed with its new status, no endedAt, and the expiresAt of a table being played, until it ends again. Someone who can edit the game can also delete a session's history sooner, from the Design Journal. Once the history is deleted the log can no longer be downloaded, so download anything you want to keep before then. Each session's expiresAt says when its history goes.

List sessions

GET /api/v1/games/:gameId/sessions

Lists the game's play sessions whose log can still be downloaded, newest first.

curl https://playtestparlor.com/api/v1/games/GAME_ID/sessions \
  -H "Authorization: Bearer pp_your_token"

{
  "sessions": [
    {
      "id": "k17d...",
      "name": "Friday Night",
      "status": "ended",
      "createdAt": 1790000000000,
      "endedAt": 1790007200000,
      "expiresAt": 1790093600000,
      "eventCount": 412
    }
  ],
  "nextCursor": null
}

nextCursor is null when there are no more sessions. eventCount is the number of actions that stand in the session's history: actions that were undone are not counted.

Download the action log

GET /api/v1/games/:gameId/sessions/:sessionId/action-log?format=csv
GET /api/v1/games/:gameId/sessions/:sessionId/action-log?format=json

format is csv (the default) or json. The response is a file download.

The file is sent as it is read, a part at a time, so a long session starts downloading at once. A problem found before the file starts (no access, no such session, history expired) comes back as an error status, listed under Errors. A problem found after the file has started, such as your edit rights being removed or the table's history changing partway, cannot change the status any more, so the transfer ends early instead: curl exits with an error and a browser marks the download as failed. Throw away the partial file and download again.

curl -o log.csv "https://playtestparlor.com/api/v1/games/GAME_ID/sessions/SESSION_ID/action-log?format=csv" \
  -H "Authorization: Bearer pp_your_token"

CSV columns

One row per action, in order.

A cell that starts with =, +, - or @ is written with a leading ' so a spreadsheet does not run a player-chosen name as a formula.

JSON shape

{
  "session": {
    "id": "k17d...",
    "name": "Friday Night",
    "gameId": "j57a...",
    "createdAt": 1790000000000,
    "endedAt": 1790007200000,
    "expiresAt": 1790093600000
  },
  "exportedAt": 1790010000000,
  "events": [
    {
      "seq": 1,
      "timestamp": 1790000012000,
      "elapsedMs": 12000,
      "seatIndex": 1,
      "seatName": "Ada",
      "seatColor": "#e11d48",
      "actionType": "stack.draw_multiple",
      "description": "Seat 1 drew 3 cards from Deck A",
      "pieces": [
        { "id": "p1...", "name": "Deck A", "type": "stack" },
        { "id": "p2...", "name": "Goblin", "type": "tile" }
      ]
    }
  ],
  "seats": [
    { "seatIndex": 1, "displayName": "Ada", "color": "#e11d48" }
  ]
}

seats lists every seat the log names, and comes last because the whole log has to be read to know them. The file puts one action per line inside events.

Piece type uses the table's internal names: tile is a card and stack is a deck.

What an action includes

The log records the actions that change the table and that undo can take back. Undone actions are not in it, whether or not anyone acted after the undo. The file is the table's history as it stood when the download started: actions taken, undone or redone after that do not change it. Undoing the newest action that stood when the download started, or resetting the table, changes that history, and the download stops (see HISTORY_CHANGED below). Pointer movement, chat and presence are not table actions and are not logged.

Errors