Keep track of your CurseForge mod downloads over time and present the results as clean badges or optional charts.
The history stays in your repository, with no separate statistics server to maintain.
Choose one setup template:
| Setup | Use when | Template |
|---|---|---|
| Daily badges | You want a simple daily download total | https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-daily.yml |
| More frequent updates | You want the current day to refresh more often | https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-hourly.yml |
| Daily badges and charts | You want download numbers and visual trends | https://github.com/N6REJ/curseforge-downloads-action/blob/main/templates/workflows/curseforge-daily-with-chart.yml |
- Download or copy the template that matches the result you want.
- Place the file in the repository under
.github/workflows/. - Set
curseforge_mod_idto the numeric CurseForge mod (project) ID you want to track. - (Optional) Add a repository secret named
CF_STUDIO_API_KEYfor the official CurseForge for Studios API (Settings → Secrets and variables → Actions → New repository secret). Without it, the action uses the public cfwidget API, which needs no key. - Commit and push.
- Open the repository's Actions tab and select Run workflow once.
- Add one or both badges to the README, replacing
_OWNER_and_REPOSITORY_:

- CurseForge mod id: open your project on CurseForge. The number in the project URL (
curseforge.com/minecraft/mc-mods/<slug>→ see the project's "Project ID" under the About section) is thecurseforge_mod_id. - CurseForge API key (optional): create one from your CurseForge for Studios account and store it as the
CF_STUDIO_API_KEYsecret.
The action supports two sources and picks them automatically:
| Condition | Source | Key required | Notes |
|---|---|---|---|
cf_studio_api_key set |
Official CurseForge for Studios API (api.curseforge.com) |
Yes | Stable and supported; preferred. |
cf_studio_api_key unset |
Public cfwidget API (api.cfwidget.com) |
No | Zero-setup fallback for casual use. |
| Key set but the official API rejects the request | cfwidget fallback | n/a | The action logs a warning and retries against cfwidget. |
Both sources return a single running download total, so day/week/month/year comparisons work the same either way.
The cfwidget fallback is an independent, community-run service. It is convenient and needs no account, but it is not operated by CurseForge. For the most reliable results, set
CF_STUDIO_API_KEY.
Public badges need a publicly readable result file. Private repositories usually cannot display them to signed out visitors.
CurseForge shows your mod's lifetime download count, but it does not show how that total changed over time.
CurseForge Downloads Action keeps that short history for you. On a schedule you choose, it reads the current number from the CurseForge API, saves the total for the day, and updates the small files used by your badges and charts.
Everything remains in the repository, making the result easy to inspect, reuse, and remove without depending on a hosted analytics account.
- Read the download total for your mod from the CurseForge API using
curseforge_mod_id. If theCF_STUDIO_API_KEYsecret is set, the official CurseForge for Studios API is used; otherwise the action falls back to the public cfwidget API. - Save one total for the current day.
- Compare the available history to show day, ISO week, calendar month, and calendar year changes.
- Clearly mark a comparison as partial when there is not yet enough history for the complete calendar period.
- Publish the result to
stats-data:curseforge/downloads.jsonby default. - Optionally publish chart images from the same history.
flowchart LR
A[Scheduled workflow] --> B[curseforge-downloads-action]
B --> C[CurseForge mod download total]
C --> B
B --> D[Daily history and comparisons]
D --> E[Badge data]
D --> F[Optional chart images]
E --> G[README badges]
F --> H[README charts]
The badge reads the small public data file produced by the action. With the default settings, its address follows this pattern:
Default source URL pattern:
https://raw.githubusercontent.com/<_OWNER_>/<_REPO_>/stats-data/curseforge/downloads.json
stats-data is simply the branch used to store the generated files. It is a plain data branch and is not tied to any GitHub Pages website.
raw vs jsDelivr:
raw.githubusercontent.comis direct and simple, and is used by the examples in this README.cdn.jsdelivr.netcan be faster in some locations, although updates may take longer to appear.
Alternative jsDelivr pattern:
https://cdn.jsdelivr.net/gh/<_OWNER_>/<_REPO_>@stats-data/curseforge/downloads.json
day, week, month, and year are calendar periods, not rolling windows:
day= the current day (since the previous snapshot).week= the current ISO week (Monday–Sunday, UTC).month= the current calendar month (since the 1st, UTC).year= the current calendar year (since January 1, UTC).
Each value is today's total − the snapshot at the period start. The periods block in the JSON records each period's start, end, and a label (2026-W43, Oct 2026, 2026).
Calendar comparisons need a snapshot at or after the period start. A new setup therefore takes time to build history, and values reset when a period rolls over.
- A comparison is complete when a snapshot exists exactly on the period start date.
- If the exact date is missing but a later snapshot exists, the value is the best available and is flagged
partial. - If no snapshot is retained at or after the period start, the value is
partial.
A partial value is not a failure. It is the best comparison available from the dates collected so far.
Retention: the action keeps enough history for the current calendar year automatically. The effective window_days is raised to at least the day-of-year (up to ~366) so a January 1 baseline is retained even when window_days is smaller.
Because buckets are calendar-based, values reset at period boundaries: month drops to a small number on the 1st, year on January 1, and week each Monday.
Replace _OWNER_ and _REPOSITORY_.
Preview:
Preview:
Preview:
Preview:
Preview:
Preview:
<sub>Powered by <a href="https://github.com/N6REJ/curseforge-downloads-action">curseforge-downloads-action</a></sub>Preview:
Powered by curseforge-downloads-action
You can publish static SVG charts and embed them directly in your README.
Enable chart publishing in workflow:
with:
publish_chart: "true"
chart_output_path: "curseforge/downloads-trend.svg"
chart_types: "total-trend,daily,weekly,monthly,yearly"
chart_themes: "black,slate,orange"
charts_output_dir: "curseforge/charts"
chart_width: "1000"
chart_height: "360"
chart_zero_baseline: "true"
chart_y_ticks: "6"
chart_x_label_every_days: "0"
chart_show_value_labels: "false"
chart_date_label_format: "yyyy-mm-dd"
chart_show_generated_at: "true"
chart_title_mode: "default"
chart_title_text: ""Chart options:
chart_types:total-trend,daily,weekly,monthly,yearlychart_themes:black,slate,orangechart_width,chart_height: pixel dimensions for all published SVG fileschart_zero_baseline: whentrue, Y-axis starts at 0 (enabled by default)chart_y_ticks: Y-axis interval count (2..12) for denser/sparser value lineschart_x_label_every_days: date label spacing (0= auto spacing,1= every day)chart_show_value_labels: render per-point numeric values above the linechart_date_label_format: date labels (yyyy-mm-dd,yy/mm/dd,dd/mm,mm/dd,none)chart_show_generated_at: show/hideGenerated <date>footer textchart_title_mode: title style (default,custom,none)chart_title_text: custom title text (required only whenchart_title_mode: "custom")chart_output_path: primary chart path (firstchart_types+ firstchart_themes)charts_output_dir: directory for all matrix charts (<type>--<theme>.svg)
Note: chart_output_path publishes one primary chart, while charts_output_dir publishes the full chart matrix.
Note: for safety, output_path cannot overlap any chart output file when publish_chart is enabled.
Implementation note: chart types/themes/date/title enums are centralized in src/lib/chart-config.js.
Dense chart example (more Y values, daily date labels, and numbers):
with:
publish_chart: "true"
chart_types: "daily"
chart_themes: "black"
chart_zero_baseline: "true"
chart_y_ticks: "10"
chart_x_label_every_days: "1"
chart_show_value_labels: "true"
chart_date_label_format: "dd/mm"
chart_show_generated_at: "true"
chart_title_mode: "custom"
chart_title_text: "My mod daily downloads"Simple chart presets:
- Clean default trend: keep defaults (
chart_zero_baseline: "true",chart_y_ticks: "6",chart_x_label_every_days: "0") - Detail-heavy daily chart: set
chart_types: "daily",chart_y_ticks: "10",chart_x_label_every_days: "1",chart_show_value_labels: "true" - Minimal labels (less clutter): keep
chart_show_value_labels: "false"and usechart_x_label_every_days: "7"or higher
Embed the primary chart:
Embed a matrix chart directly:
Preview gallery (5 chart types):
Theme preview (same chart, 3 themes):
You can publish a README-style dashboard Markdown file that summarises the current stats.
with:
publish_dashboard: "true"
dashboard_path: "curseforge/dashboard.md"Behavior:
- Enabled by default. Set
publish_dashboard: "false"to turn it off. - On the first run the full dashboard is generated and written.
- On later runs your customized dashboard is preserved: only the generated data tables are refreshed from the live payload. Titles, prose, badge rows, chart sections, and footers you edit stay as you left them.
- The chart sections and chart images are generated on the first run and not overwritten afterwards, so you can customize them freely.
- Values are rendered from the live payload, so the
Windowrow always matches the currentwindow_days. - If an existing dashboard file is missing the
Windowrow (for example after a manual edit), the dashboard update is skipped for that run and the rest of the action continues normally. - Badge images use
style=flat-square,logo=curseforge, andcacheSeconds=900. - When
publish_chartis enabled, the dashboard links the published chart images. dashboard_pathmust differ fromoutput_path.
The dashboard is written to output_branch (default stats-data). To embed it in another README:
[](#)Expected first-run result (nothing pre-seeded), so the file appears on the initial run:
- Header:
# <owner>/<repo> downloads - Badge row: total, day, week, month, year
- Optional chart section when
publish_chartis enabled - A
## Datatable with update mode, the live window, snapshot count, partial flags, and generated time
Generate Markdown image lines for selected chart types/themes.
node <<'NODE'
const owner = '_OWNER_';
const repo = '_REPOSITORY_';
const types = ['total-trend', 'daily', 'weekly', 'monthly', 'yearly'];
const themes = ['black', 'slate', 'orange'];
const base = `https://raw.githubusercontent.com/${owner}/${repo}/stats-data`;
for (const type of types) {
for (const theme of themes) {
console.log(``);
}
}
NODEPowerShell variant:
$owner = "_OWNER_"
$repo = "_REPOSITORY_"
$types = @("total-trend", "daily", "weekly", "monthly", "yearly")
$themes = @("black", "slate", "orange")
$base = "https://raw.githubusercontent.com/$owner/$repo/stats-data"
foreach ($type in $types) {
foreach ($theme in $themes) {
Write-Output ""
}
}Generate all badge markdown lines for a repo.
node <<'NODE'
const owner = '_OWNER_';
const repo = '_REPOSITORY_';
const src = `https://raw.githubusercontent.com/${owner}/${repo}/stats-data/curseforge/downloads.json`;
const url = encodeURIComponent(src);
const definitions = [
['total', '$.stats.total', '0A7EA4'],
['day', '$.stats.day', '1E8E3E'],
['week', '$.stats.week', '0069C2'],
['month', '$.stats.month', 'B26A00'],
['year', '$.stats.year', '6A1B9A'],
['profile', '$.profile.defaultMode', '5E35B1'],
];
for (const [metric, query, color] of definitions) {
const label = encodeURIComponent(`downloads/${metric}`);
console.log(`}&label=${label}&color=${color})`);
}
NODEPowerShell variant:
$owner = "_OWNER_"
$repo = "_REPOSITORY_"
$src = "https://raw.githubusercontent.com/$owner/$repo/stats-data/curseforge/downloads.json"
$u = [uri]::EscapeDataString($src)
$defs = @(
@{ Name = "total"; Query = "$.stats.total"; Color = "0A7EA4" },
@{ Name = "day"; Query = "$.stats.day"; Color = "1E8E3E" },
@{ Name = "week"; Query = "$.stats.week"; Color = "0069C2" },
@{ Name = "month"; Query = "$.stats.month"; Color = "B26A00" },
@{ Name = "year"; Query = "$.stats.year"; Color = "6A1B9A" },
@{ Name = "profile"; Query = "$.profile.defaultMode"; Color = "5E35B1" }
)
foreach ($d in $defs) {
$label = [uri]::EscapeDataString("downloads/$($d.Name)")
$query = [uri]::EscapeDataString($d.Query)
Write-Output ")"
}Schema file: schema/downloads.schema.json
The action writes schemaVersion: "2" using this structure:
{
"schemaVersion": "2",
"owner": "N6REJ",
"repo": "repository",
"visibility": "public",
"generatedAt": "2026-02-18T10:00:00.000Z",
"stats": {
"total": 9412,
"day": 16,
"week": 159,
"month": 802,
"year": 6543
},
"partial": {
"day": false,
"week": false,
"month": true,
"year": true
},
"periods": {
"day": { "start": "2026-02-18", "end": "2026-02-18", "label": "2026-02-18" },
"week": { "start": "2026-02-16", "end": "2026-02-22", "label": "2026-W08" },
"month": { "start": "2026-02-01", "end": "2026-02-28", "label": "Feb 2026" },
"year": { "start": "2026-01-01", "end": "2026-12-31", "label": "2026" }
},
"snapshots": {
"windowDays": 365,
"count": 31,
"firstDate": "2026-01-18",
"lastDate": "2026-02-18",
"series": {
"2026-02-18": 9412
}
},
"profile": {
"defaultMode": "daily",
"hourlyEnabled": false
}
}For the v2 major line, the project follows these stability expectations:
- Existing output keys in
downloads.jsonwill remain stable. schemaVersionchanges only for explicit schema migrations.- Existing action inputs and outputs are not removed without a major version bump.
- Workflow template updates are additive or documented in release notes when behavior changes.
Note: schemaVersion: "2" changed week/month/year from rolling windows to calendar periods and added the periods block. The keys are unchanged; only their meaning (and the extra block) is new.
| Input | Required | Default | Type | Notes |
|---|---|---|---|---|
token |
No | empty | string | GitHub token for publishing (${{ secrets.GITHUB_TOKEN }} recommended) |
owner |
No | workflow repo owner | string | Target repo owner (publish destination) |
repo |
No | workflow repo name | string | Target repo name (publish destination) |
curseforge_mod_id |
Yes | – | integer | CurseForge mod (project) ID whose download total is tracked |
cf_studio_api_key |
No | empty | string | Optional CurseForge for Studios API key (${{ secrets.CF_STUDIO_API_KEY }}); when empty, the public cfwidget API is used (no key) |
window_days |
No | 365 |
integer | Allowed range: 1..3650; automatically raised to at least the current day-of-year so the calendar-year baseline is retained |
enable_hourly_profile |
No | false |
boolean | true/false, 1/0, yes/no accepted |
output_branch |
No | stats-data |
string | Must be a valid git branch name |
output_path |
No | curseforge/downloads.json |
string | Repo-relative file path; traversal blocked |
min_refresh_minutes |
No | 0 |
integer | Optional cache window in minutes (0..10080); when >0, a fresh prior total can be reused |
publish_chart |
No | false |
boolean | When true, publishes static SVG charts |
chart_output_path |
No | curseforge/downloads-trend.svg |
string | Repo-relative path for the SVG chart |
chart_types |
No | total-trend |
csv | Chart types list: total-trend,daily,weekly,monthly,yearly |
chart_themes |
No | black |
csv | Chart themes list: black,slate,orange |
charts_output_dir |
No | curseforge/charts |
string | Repo-relative directory where matrix chart files are written |
chart_width |
No | 1000 |
integer | Chart width in pixels (640..4096) |
chart_height |
No | 360 |
integer | Chart height in pixels (240..2160) |
chart_zero_baseline |
No | true |
boolean | When true, Y-axis starts at 0 |
chart_y_ticks |
No | 6 |
integer | Y-axis interval count (2..12) |
chart_x_label_every_days |
No | 0 |
integer | Date label spacing in days (0..365, 0 means auto) |
chart_show_value_labels |
No | false |
boolean | When true, draws numeric labels above points |
chart_date_label_format |
No | yyyy-mm-dd |
enum | Date labels: yyyy-mm-dd, yy/mm/dd, dd/mm, mm/dd, none |
chart_show_generated_at |
No | true |
boolean | When true, shows Generated <date> footer |
chart_title_mode |
No | default |
enum | default (owner/repo), custom (uses chart_title_text), or none |
chart_title_text |
No | empty | string | Custom title shown when chart_title_mode=custom (max 120 chars) |
publish_dashboard |
No | true |
boolean | When true, publishes a README-style dashboard Markdown file built from the current stats |
dashboard_path |
No | curseforge/dashboard.md |
string | Repo-relative path for the dashboard Markdown file |
owner,repo,generated_attotal,day,week,month,yearpartial_day,partial_week,partial_month,partial_yeartotal_source(apiorcache)chart_output_pathchart_published(truewhen one or more chart SVGs were updated in this run)chart_published_count,chart_total_countchart_files(comma-separated generated chart paths)dashboard_path,dashboard_published(truewhen the dashboard Markdown was updated in this run)output_branch,output_pathpublished(truewhen file was updated,falsewhen no material change was detected)
- Style checks:
scripts/style-check.js - Public test suite:
tests/run-tests.js - Compatibility checks:
compat/run-compat.js - Local command:
npm test
partial: falsemeans the action has the exact earlier date needed for that comparison.partial: truemeans the exact baseline date is missing, so the action uses an available snapshot and marks the comparison as incomplete.
For a new setup, expect weekly and monthly comparisons to remain partial until enough daily history has been collected.
- Weekly and monthly comparisons may be partial while the history is still growing.
- The action records daily totals, not individual download events or unique users.
- GitHub Raw and badge caching can delay when a new value becomes visible.
- Running the action again on the same day may produce no new commit when nothing has changed.
| Symptom | Likely cause | Exact fix |
|---|---|---|
| Badge shows no value | JSON URL is wrong or file not published yet | Open raw JSON URL directly and confirm it returns JSON |
Badge says resource not found |
Repo is private | Publish data from a public repo/branch for public badges |
partial.week or partial.month is true |
Warm-up period or missing baseline snapshots | Wait for enough snapshots; this is expected during early runs |
| Values look very low | Mod has little/no download traffic | Confirm the mod id is correct and the project has real downloads |
Action fails with 401/403 |
CurseForge API key set but invalid, and the cfwidget fallback also rejected the request | Check the CF_STUDIO_API_KEY secret, or remove it to use the keyless cfwidget fallback |
Action fails with 404 |
Wrong CurseForge mod id | Check curseforge_mod_id against your project's Project ID |
| Workflow reports no commit | No material change between previous and current payload | Check published output; this is expected when totals did not change |
Push/write fails on stats-data |
Missing write permission or branch protection blocks Actions | Set permissions: contents: write, pass token, allow Actions to push or use another branch |
| Wrong publish target repository data | Owner/repo auto-resolution mismatch | Set owner and repo explicitly in workflow with |
If your mod has few downloads, totals and deltas will naturally stay low.
No. stats-data is only used as a storage branch for the generated files.
- Badge examples: README badge examples (copy-paste)
- Charts and chart options: Charts (optional)
- Dashboard: Dashboard (optional)
- All inputs: Inputs
- All outputs: Outputs
- Troubleshooting: Troubleshooting
- JSON schema: Published JSON schema
- Label definitions:
.github/labels.json - Label sync workflow:
.github/workflows/sync-labels.yml - Suggested issue labels for triage:
| Label | Purpose |
|---|---|
bug |
Behavior is incorrect and needs a fix |
enhancement |
Feature or UX improvement |
question |
Usage/setup question |
documentation |
Docs-only improvement |
good first issue |
Beginner-friendly task |
help wanted |
Maintainers are actively looking for contributors |
breaking-change |
Behavior/input/output change requiring migration |
performance |
API load/runtime efficiency work |
- Grant the workflow only the repository permissions required for its selected output.
- Store your CurseForge API key as the
CF_STUDIO_API_KEYsecret; never commit it to the repository. - Remember that public badges need a publicly readable result file.
- Refer to the repository Security Policy for private vulnerability reporting.
- Additional policies are available in
.github/PRIVACY.mdand.github/EULA.md.
Contributions are welcome.
- Start with
.github/CONTRIBUTING.md - Use Issues for defect reports, feature proposals, and questions
- GitHub Issues: https://github.com/N6REJ/curseforge-downloads-action/issues
Licensed under the Apache License 2.0 (Apache-2.0).
See LICENSE.
Project concept based on justagwas/github-downloads-action.