How to keep GitHub traffic data for longer than 14 days
By Bright Oparaji11 min read
GitHub shows repository traffic for the last 14 days and then lets it go. To keep it, call the traffic API at least once every 14 days (daily is easier), save views and clones as one row per day, and save referrers and popular content as dated snapshots of a 14-day window. Never add those snapshots together.
The Traffic page under a repository's Insights tab is one of the few places GitHub tells you how many people looked at your project. It is also one of the shortest memories on the platform. If you open it once a month, about half of every month has already gone. There is no setting to extend it and no export button. The only way to have a longer history is to copy the numbers somewhere else before they drop off the end.
This post covers exactly what GitHub keeps, the one mistake that makes a saved history wrong, and a small script plus a scheduled workflow that does the copying for you.
What GitHub keeps, and for how long
According to GitHub's documentation on viewing traffic, the Traffic page shows four things:
- Views: page views and unique visitors, for the past 14 days.
- Clones: full clones and unique cloners. Fetches are not counted.
- Referring sites: the sites that sent visitors, excluding search engines and GitHub itself.
- Popular content: the pages in the repository that visitors opened most.
A few details matter once you start saving the numbers:
- Who can see it. Anyone with push access to the repository. Everyone else, including people who starred it, sees nothing.
- Time zone. All of it is in UTC. A "day" on the Traffic page runs from midnight to midnight UTC, whatever your local clock says.
- Update frequency. Clones and visitor information update hourly. Referring sites and popular content update daily.
The REST API reference for traffic exposes the same data through four endpoints, all for repositories you have write access to:
| Endpoint | What it returns |
|---|---|
GET /repos/{owner}/{repo}/traffic/views | Total count and uniques for the 14 days, plus a views array of {timestamp, count, uniques} |
GET /repos/{owner}/{repo}/traffic/clones | The same shape, with a clones array |
GET /repos/{owner}/{repo}/traffic/popular/referrers | The top 10 referrers over the last 14 days, each with referrer, count, uniques |
GET /repos/{owner}/{repo}/traffic/popular/paths | The top 10 popular contents over the last 14 days, each with path, title, count, uniques |
The views and clones endpoints take a per parameter, either day (the default) or week. Timestamps are aligned to UTC midnight at the start of the day or week, and weeks begin on Monday. The referrers and paths endpoints take no per parameter at all, which is the first hint of the trap below.
For fine-grained personal access tokens and GitHub App tokens, the reference says each of the four endpoints needs the "Administration" repository permission, read access. That surprises people, because nothing about reading a visitor count sounds like administration, but it is what the documentation lists.
The trap: referrers and popular content are not daily figures
Views and clones come with a daily breakdown. Each entry in the views array is one UTC day, so if you save today's response and next week's response, the days that appear in both are the same days, and you can keep one row per date.
Referrers and popular content are different. There is no daily breakdown. Each response is a single list covering the whole of the last 14 days. If you save it every day and then add the saved lists together, every visit is counted up to 14 times, once for each day it stayed inside the window. A referrer that sent 30 visitors on one afternoon would show 30 on each of the next 14 snapshots, and a naive sum would report 420.
So keep these as windows. Save each response with the date it was taken and treat it as "the 14 days ending on this date". You can compare one window with another, for example the window after a launch against the window before it. You cannot turn a run of overlapping windows back into daily numbers. And if you sample less often than every 14 days, the time between windows is simply not recorded.
There is a smaller version of the same problem inside the views and clones data. The top-level uniques is the number of unique visitors across the whole window, while each daily uniques counts that day alone. Someone who visits on three different days appears in three daily figures. Adding daily uniques together gives you visitor-days, not people, so label the column honestly and do not present the sum as an audience size.
Saving it yourself: a script and a scheduled workflow
The method below uses the GitHub CLI and jq, both of which are already installed on GitHub's Ubuntu runners. It does two things each time it runs:
- Merges the daily views and clones into
traffic/daily.csv, one row per UTC date. If a date is already in the file, it keeps the larger figure in each column. The most recent day is usually still in progress when the script runs, and the oldest day in the window may be cut short, so the larger figure is the more complete one. - Saves the referrers and popular paths as two JSON snapshots named after the day, in
traffic/windows/. These are never merged into the daily table.
Save this as scripts/fetch-traffic.sh:
#!/usr/bin/env bash
# Usage: fetch-traffic.sh OWNER/REPO [CSV_PATH]
set -euo pipefail
repo="${1:?usage: fetch-traffic.sh OWNER/REPO [CSV_PATH]}"
csv="${2:-traffic/daily.csv}"
mkdir -p "$(dirname "$csv")"
views="$(gh api "repos/$repo/traffic/views?per=day")"
clones="$(gh api "repos/$repo/traffic/clones?per=day")"
# One line per UTC day: date,views,unique_visitors,clones,unique_cloners
fresh="$(jq -nr --argjson v "$views" --argjson c "$clones" '
($v.views | map({key: .timestamp[0:10], value: .}) | from_entries) as $vd
| ($c.clones | map({key: .timestamp[0:10], value: .}) | from_entries) as $cd
| ($vd + $cd | keys[]) as $d
| [$d, ($vd[$d].count // 0), ($vd[$d].uniques // 0),
($cd[$d].count // 0), ($cd[$d].uniques // 0)]
| map(tostring) | join(",")')"
# Merge with what is already saved. A date seen twice keeps the larger
# figure in each column, so a partial day is replaced by its complete count.
{
[ -f "$csv" ] && tail -n +2 "$csv"
printf '%s\n' "$fresh"
} | awk -F, -v OFS=, '
NF == 5 {
for (i = 2; i <= 5; i++)
if (!($1 in seen) || $i + 0 > m[$1, i]) m[$1, i] = $i + 0
seen[$1] = 1
}
END { for (d in seen) print d, m[d, 2], m[d, 3], m[d, 4], m[d, 5] }
' | sort > "$csv.tmp"
{ echo "date,views,unique_visitors,clones,unique_cloners"; cat "$csv.tmp"; } > "$csv"
rm "$csv.tmp"
# Referrers and popular pages are 14-day windows. Save each as a snapshot
# named after the day it was taken; never add them to the daily table.
day="$(date -u +%F)"
mkdir -p "$(dirname "$csv")/windows"
gh api "repos/$repo/traffic/popular/referrers" > "$(dirname "$csv")/windows/referrers-$day.json"
gh api "repos/$repo/traffic/popular/paths" > "$(dirname "$csv")/windows/paths-$day.json"
You can run it by hand first. gh api uses whatever account gh auth login signed you into, and that account needs push access to the repository:
bash scripts/fetch-traffic.sh your-name/your-repo
GitHub returns an entry for every day in the window, with zeros on days that had no traffic, so the table has no gaps. The script still writes zero for a date missing from one response, as a safeguard. Compare your first few rows with the Traffic page before you rely on them.
The token
The default GITHUB_TOKEN that every workflow receives cannot read traffic. The workflow syntax reference lists the permissions you can grant it, and administration is not among them, while the traffic endpoints require "Administration" read. So the workflow needs a second token for reading:
- Create a fine-grained personal access token limited to this one repository, with Administration: Read-only under repository permissions. Nothing else is needed for the traffic calls.
- Add it to the repository as an Actions secret called
TRAFFIC_TOKEN.
The default GITHUB_TOKEN is still the right tool for committing the CSV back, since its permissions are limited to the repository that contains the workflow. Pushes made with it also do not start new push workflow runs, so the daily commit will not set off your CI.
Give the token an expiry date and put the renewal in your calendar. When a token expires, the workflow starts failing, and the days it misses are lost once they leave the 14-day window.
The workflow
Save this as .github/workflows/save-traffic.yml:
name: Save traffic
on:
schedule:
- cron: "17 3 * * *" # 03:17 UTC every day
workflow_dispatch:
permissions:
contents: write
jobs:
save:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Fetch traffic
env:
GH_TOKEN: ${{ secrets.TRAFFIC_TOKEN }}
run: bash scripts/fetch-traffic.sh "${{ github.repository }}"
- name: Commit if anything changed
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add traffic
git diff --cached --quiet || git commit -m "Save traffic for $(date -u +%F)"
git push
GH_TOKEN is set only on the fetch step, so the traffic token is never used for the push. Scheduled times are in UTC, and running a few hours after midnight UTC means the previous day is complete when it is read. The workflow_dispatch line lets you run it from the Actions tab to test it. One more thing to know: in a public repository, scheduled workflows are disabled automatically after 60 days with no repository activity, so check the Actions tab now and then if the project goes quiet.
Keeping the commits out of your history
A daily commit adds up to 365 commits a year to your main branch, which clutters the log and every contributor's git pull. Two alternatives work well:
- A separate data branch. Create an orphan branch, for example
traffic-data, keep the script and CSV there, and addwith: ref: traffic-datato the checkout step. The workflow file itself has to stay on the default branch, because scheduled workflows only run on the default branch, but nothing it writes touches that branch. - A separate repository. Keep the history in a private repository of its own. The fine-grained token then needs Administration read on the project repository and Contents read and write on the data repository, and the checkout step uses that token and points at the data repository.
Letting Orviqa keep it
If you would rather not maintain a token and a workflow, Orviqa keeps traffic history automatically. It reads views and clones daily and keeps them per day, and it keeps top referrers and popular pages as the 14-day windows GitHub reports, never as daily figures. It reads with a workspace owner's connection. Where that connection cannot read traffic, the page says traffic is unavailable rather than showing zeros. This costs no tokens.
What to do with the history
A saved history is only useful if you read it against something. A few weeks of rows give you a normal range for your project, which is what makes a change visible at all.
Put the traffic next to the signals that show use rather than attention. The post on how to measure open-source adoption sets out a weekly record with traffic as one column among downloads, dependents and issues from people outside the project. The comparison of GitHub stars and active users explains why views and clones sit closer to attention than to adoption, and why a rise in either needs something else moving with it before it means much.
Keep a note of what you did each day alongside the numbers (the method for reading a post against that record is in did my launch post work?): a release, a post, a talk, a README change. Without it, a spike in views has no candidate explanation. With it, you will still find that several things often happened in the same week. The six-week digline case study is a full worked example of how far a careful record goes, and where it stops being able to say which effort worked.
A checklist
- Run the script by hand once and compare the CSV with the Traffic page
- Create a fine-grained token with Administration read on the repository and save it as
TRAFFIC_TOKEN - Add the workflow and trigger it once from the Actions tab
- Decide whether the data lives on the default branch, a data branch or its own repository
- Note the token's expiry date
- Treat referrer and popular-content snapshots as 14-day windows, never as daily figures