GitHub Star History API 怎麼用？用週資料追蹤專案成長

先分清兩個 endpoint#

GitHub 在 2026 年 7 月對 stargazer listing endpoint 加上新的存取限制；新的 history endpoint 只提供聚合數字，不會把使用者清單重新暴露給一般工具。這是隱私邊界，也是資料模型的差異：趨勢工具應改讀 history，而不是一直重試 /stargazers。

用 curl 取得第一頁歷史資料#

以下用實際存在的 withastro/astro 作為公開 repository 範例。astro/astro 不是正確的 owner／repository 組合，複製範例時要替換成自己的 {owner}/{repo}：

1
OWNER=withastro
2
REPO=astro
3
API_ROOT=https://api.github.com
4

5
curl -fsSL \
6
  -H 'Accept: application/vnd.github+json' \
7
  -H 'X-GitHub-Api-Version: 2026-03-10' \
8
  "${API_ROOT}/repos/${OWNER}/${REPO}/stargazers/history?per_page=30&page=1"

官方範例的資料形狀如下：

1
[
2
  {
3
    "week": 1754784000,
4
    "total": 19,
5
    "days": [0, 12, 7, 0, 0, 0, 0]
6
  }
7
]

week 是該週的時間標記，total 是該週新增的 star 數，days 則是七天的分布，順序從星期日開始。GitHub 特別註明週與日的邊界不保證對齊 UTC，因此資料庫可以保存原始 timestamp，但不要未經說明就把它轉成台灣時區日期並當成官方週界線。

用 GitHub CLI 讀目前總數#

如果只是要在 shell 或 CI 取得目前仍存在的 star 數，可以呼叫 count endpoint：

1
gh api \
2
  -H 'X-GitHub-Api-Version: 2026-03-10' \
3
  '/repos/withastro/astro/stargazers/count' \
4
  --jq '.count'

count endpoint 回傳的 count 不包含曾經按過、後來又取消 star 的使用者。因此它回答的是「目前有多少人保留 star」，不是「歷史上曾經累積多少次 star」。這也是為什麼趨勢圖與目前總數最好分開存放，不要只用一個欄位互相推導。

分頁要依週順序重新組合#

history endpoint 每頁最多 30 週，page 最多 100；最新頁在前，往後翻頁會往 repository 建立的週期移動。每頁內的週也是由新到舊，且沒有 star 的週會以零保留，所以完整資料應按 API 頁面順序串接，再依圖表需要轉成舊到新：

1
OWNER=withastro
2
REPO=astro
3

4
gh api --paginate --slurp \
5
  -H 'X-GitHub-Api-Version: 2026-03-10' \
6
  "/repos/${OWNER}/${REPO}/stargazers/history?per_page=30" \
7
  | jq 'add | reverse'

這裡的 --slurp 會把每一頁包成陣列，add 把頁面攤平成一個週資料陣列，reverse 才把官方的新到舊順序轉成圖表常用的舊到新。若你的資料處理程式需要保留最新資料在前，省略 reverse 即可；不要在多次轉換後忘記目前的排序方向。

API 文件目前將 history 的錯誤條件列為 422（參數驗證失敗或 endpoint 被判定為 spam）。實作時要記錄 repository、page、HTTP status 和抓取時間，遇到 422 時停止重試並檢查參數；count endpoint 找不到 repository 則是 404。

公開與私有 repository 的權限差異#

公開 repository 的 history 和 count 都可以不帶 authentication 呼叫，適合放在不含 secret 的公開資料收集器。私有 repository 的這兩個 endpoint 需要 fine-grained token 的 Metadata read；若使用 GitHub App，則改用符合文件要求的 user 或 installation access token。

不要把 token 放在前端瀏覽器或產出的靜態 JSON 中。較安全的流程是由 server-side job、GitHub Actions secret 或 GitHub App 定期抓取，再只發布聚合後的資料。即使 history 本身不含身分，也要把 repository 權限、token scope 和快取輸出一起納入 review。

把 API 接到週報或成長圖#

推薦保存三類資料，而不是只留畫好的一張圖：

1. 原始週資料：week、total、days 和 API 版本。
2. 收集 metadata：repository、page、抓取時間、HTTP status 和是否還有下一頁。
3. 顯示用指標：最近一週新增數、指定期間的週合計、count endpoint 的目前總數。

週合計和目前總數要分開命名。total 是單週新增數，count 是目前仍保留 star 的數目；取消 star、資料抓取中斷或取樣期間不同，都可能讓兩者不相等。days 從星期日開始，也不要把它直接當成以 UTC 切週的資料，除非你的報表明確標示這個轉換規則。

如果原本使用 /stargazers 取得登入者名單，先確認產品是否真的需要身分資料。新的 privacy-safe API 能支援趨勢分析，但不能取代依使用者分群、通知或名單管理等需求；那些需求要重新檢查 GitHub 的存取限制和資料使用目的。

我在本機用 withastro/astro 的 history 與 count endpoint 各做過公開 API smoke test，確認這兩個路徑可回傳成功資料；文章不固定寫入 live star 數，避免範例一更新就過時。正式導入時仍應以 GitHub 文件當天的 schema、版本 header 和 rate limit 為準。

GitHub Star History API 的採用重點，是把「目前總數」與「每週新增趨勢」當成兩種不同資料。公開專案可以先用無 token 的 curl 驗證，接著處理分頁、週界線和 422，再把原始資料與顯示指標分開保存。這樣即使 GitHub 後續調整 listing 存取規則，趨勢圖也不必依賴 stargazer 身分清單。

常見問題#