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](../endpoints/games.md) for all available filters (`playerCount`, `drawing`, `length`, `familyFriendly`, `pack`).

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

**Sample response (200 OK):**

```json
[
  {
    "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](../endpoints/sessions.md) for full details on session game fields.

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

**Sample response (200 OK):**

```json
[
  {
    "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.

```javascript
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):**

```json
{
  "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](../endpoints/games.md) — full catalog CRUD, filters, favor bias
- [Sessions endpoints](../endpoints/sessions.md) — session games, status updates, room codes
- [Picker endpoint](../endpoints/picker.md) — weighted random selection with session exclusion
- [Stats endpoint](../endpoints/stats.md) — `mostPlayedGames`, `topRatedGames`
- [Voting & Popularity guide](voting-and-popularity.md) — how votes and popularity scores work