jackboxpartypack-gamepicker/docs/api/guides/game-status-by-session.md

Game Status by Session

How to build a complete view of all enabled games—with popularity data and whether each game has been played in the current session. No single endpoint returns all three pieces today; this guide shows how to combine two public endpoints and join the results client-side.

---

1. Fetch Enabled Games

GET /api/games?enabled=true returns every enabled game in the catalog. Each row includes popularity_score, upvotes, downvotes, play_count, and favor_bias.

Why: This gives you the full list of games that are available for play, along with their cumulative popularity data across all sessions.

See Games endpoints for all available filters (playerCount, drawing, length, familyFriendly, pack).

curl "http://localhost:5000/api/games?enabled=true"

Sample response (200 OK):

[
  {
    "id": 1,
    "pack_name": "Jackbox Party Pack 7",
    "title": "Quiplash 3",
    "min_players": 3,
    "max_players": 8,
    "length_minutes": 15,
    "has_audience": 1,
    "family_friendly": 0,
    "game_type": "Writing",
    "secondary_type": null,
    "play_count": 4,
    "popularity_score": 7,
    "upvotes": 10,
    "downvotes": 3,
    "enabled": 1,
    "favor_bias": 0,
    "created_at": "2024-01-15T12:00:00.000Z"
  },
  {
    "id": 5,
    "pack_name": "Jackbox Party Pack 9",
    "title": "Fibbage 4",
    "min_players": 2,
    "max_players": 8,
    "length_minutes": 15,
    "has_audience": 1,
    "family_friendly": 1,
    "game_type": "Trivia",
    "secondary_type": null,
    "play_count": 2,
    "popularity_score": 3,
    "upvotes": 5,
    "downvotes": 2,
    "enabled": 1,
    "favor_bias": 1,
    "created_at": "2024-01-15T12:00:00.000Z"
  }
]

---

2. Fetch Session Games

GET /api/sessions/{id}/games returns games that have been added to a specific session. Each row includes status (playing, played, or skipped), played_at, and joined popularity fields from the game catalog.

Why: This tells you which games have already been played (or are currently playing) in the session, so you can mark them in the catalog.

See Sessions endpoints for full details on session game fields.

curl "http://localhost:5000/api/sessions/5/games"

Sample response (200 OK):

[
  {
    "id": 14,
    "session_id": 5,
    "game_id": 1,
    "played_at": "2026-03-15T20:30:00.000Z",
    "manually_added": 0,
    "status": "played",
    "room_code": "LSBN",
    "player_count": 6,
    "player_count_check_status": "completed",
    "pack_name": "Jackbox Party Pack 7",
    "title": "Quiplash 3",
    "game_type": "Writing",
    "min_players": 3,
    "max_players": 8,
    "popularity_score": 7,
    "upvotes": 10,
    "downvotes": 3
  }
]

Key fields for the join:

Field	Purpose
game_id	Matches id in the games catalog
status	playing, played, or skipped
played_at	When the game was added to the session

---

3. Combine Client-Side

Join the two responses by matching game_id (from session games) to id (from the catalog). This produces a single list of enabled games annotated with their session play status.

const gamesRes = await fetch('/api/games?enabled=true');
const games = await gamesRes.json();

const sessionGamesRes = await fetch('/api/sessions/5/games');
const sessionGames = await sessionGamesRes.json();

const sessionGameMap = new Map(
  sessionGames.map(sg => [sg.game_id, sg])
);

const combined = games.map(game => {
  const sessionEntry = sessionGameMap.get(game.id);
  return {
    ...game,
    playedInSession: !!sessionEntry,
    sessionStatus: sessionEntry?.status ?? null,
    sessionPlayedAt: sessionEntry?.played_at ?? null,
  };
});

Sample merged output (one entry):

{
  "id": 1,
  "pack_name": "Jackbox Party Pack 7",
  "title": "Quiplash 3",
  "min_players": 3,
  "max_players": 8,
  "length_minutes": 15,
  "has_audience": 1,
  "family_friendly": 0,
  "game_type": "Writing",
  "play_count": 4,
  "popularity_score": 7,
  "upvotes": 10,
  "downvotes": 3,
  "enabled": 1,
  "favor_bias": 0,
  "playedInSession": true,
  "sessionStatus": "played",
  "sessionPlayedAt": "2026-03-15T20:30:00.000Z"
}

Games that have not been played in the session will have playedInSession: false, sessionStatus: null, and sessionPlayedAt: null.

---

Quick Reference

Data point	GET /api/games	GET /api/sessions/{id}/games
Enabled status	enabled field + ?enabled=true filter	Not included
Popularity score	popularity_score, upvotes, downvotes	popularity_score, upvotes, downvotes (joined)
All-time play count	play_count	Not included
Played in session	Not included	status field (playing/played/skipped)
Auth required	No	No

---

Related Documentation

• Games endpoints — full catalog CRUD, filters, favor bias
• Sessions endpoints — session games, status updates, room codes
• Picker endpoint — weighted random selection with session exclusion
• Stats endpoint — mostPlayedGames, topRatedGames
• Voting & Popularity guide — how votes and popularity scores work