diff --git a/graph/fixes/pd-api-players-endpoint-filter-by-cardset-uses-cardset-id-no-a4100b.md b/graph/fixes/pd-api-players-endpoint-filter-by-cardset-uses-cardset-id-no-a4100b.md
new file mode 100644
index 00000000000..77218c38037
--- /dev/null
+++ b/graph/fixes/pd-api-players-endpoint-filter-by-cardset-uses-cardset-id-no-a4100b.md
@@ -0,0 +1,41 @@
+---
+id: a4100bc8-c4bb-48df-9a2c-31c20598985e
+type: fix
+title: "PD API /players endpoint: filter by cardset uses \"cardset_id\" not \"cardset\""
+tags: [paper-dynasty, api, debugging, gotcha, card-creation, fix]
+importance: 0.8
+confidence: 0.8
+created: "2026-02-22T15:44:22.469478+00:00"
+updated: "2026-02-22T15:44:22.469478+00:00"
+---
+
+# Fix: Paper Dynasty API cardset filter parameter name
+
+## Problem
+
+When querying the Paper Dynasty API `/players` endpoint, using the query parameter `cardset` silently fails. The API ignores the unknown parameter and returns ALL players across all cardsets (13,500+ records).
+
+This caused confusion when investigating cardset 28 (2005 Promos) — it appeared to contain players from every era (1998, 2005, 2018, 2021, etc.) when in reality it only has ~25 players.
+
+## Root Cause
+
+The correct parameter name is `cardset_id`, not `cardset`.
+
+## Correct Usage
+
+```python
+# Wrong - silently returns all players
+db_get('players', params=[('cardset', 28)])
+
+# Correct - filters to cardset 28 only
+db_get('players', params=[('cardset_id', 28)])
+```
+
+The `db_calls.py` helper passes params as query string key-value pairs.
+
+## Impact
+
+Using the wrong parameter name gives no error — it just returns unfiltered results, which can look like the cardset contains thousands of players when it actually contains a handful.
+
+## Tags
+paper-dynasty, api, debugging, gotcha, card-creation