How to Track GitHub Release Downloads: What download_count Actually Measures

To track GitHub release downloads over a reporting period, read the download_count field for an uploaded release asset through GitHub’s REST API and compare two snapshots of the same asset ID. The difference is the number of additional downloads counted between those observations—not a count of unique people or confirmed installations.

GitHub provides the field in its release-asset response. You can retrieve a release by tag, find the file in its assets array and record its ID, name and count. GitHub REST API: releases · GitHub REST API: release assets

What download_count Measures

download_count is the download counter associated with an uploaded GitHub release asset. An asset is a file attached to a release, such as a compiled executable, installer or archive uploaded by the maintainer. GitHub release-asset API

For example, a release might contain separate files for Windows, macOS and Linux. Each uploaded file has its own asset ID and its own counter. To report the total for a release, you need to decide which assets belong in that total and record each one consistently.

The counter does not establish:

• How many unique people downloaded the file.
• How many downloads resulted in a completed installation.
• How many people ran the software.
• How many repository clones occurred.
• Why someone downloaded the asset.

A person may download a file more than once, and a download does not prove the software was installed or used.

Uploaded Assets vs Source Archives

GitHub also provides automatically generated source-code archives for releases. These are distinct from files uploaded as release assets.

Do not assume that an uploaded asset’s download_count includes downloads of the automatically generated source archives. If source-archive activity matters to your report, check the measurement available for that path separately.

How to Find the Download Counter

The following workflow uses placeholders. Replace OWNER, REPO and TAG with the repository owner, repository name and release tag you want to inspect.

For public resources, GitHub documents that these release endpoints can be used without authentication. Private resources have access requirements; do not put credentials in a public example or shared report. GitHub release-asset API

1. Retrieve the Release by Tag

Send a read-only request:

curl -L \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/OWNER/REPO/releases/tags/TAG"

GitHub returns information about the release, including its assets array. Locate the uploaded file you want to track and record these fields:

• id
• name
• download_count

Use the tag exactly as it appears for the release. If the request returns an error, verify the owner, repository, tag and access to the resource before interpreting the absence of a response as zero downloads.

2. Read the Asset Entry

A shortened hypothetical asset entry might look like this:

{
  "id": 123456,
  "name": "example-app-linux.zip",
  "download_count": 420
}

Here, 420 is the counter for the asset whose ID is 123456. The example is illustrative; it is not a real repository measurement.

The filename makes the row readable, while the asset ID is the key field for deciding whether two snapshots refer to the same uploaded asset.

3. Retrieve One Asset Directly

Once you know the asset ID, you can request that asset directly:

GET /repos/{owner}/{repo}/releases/assets/{asset_id}

For example, with placeholders:

curl -L \
  -H "Accept: application/vnd.github+json" \
  "https://api.github.com/repos/OWNER/REPO/releases/assets/ASSET_ID"

The JSON response includes id, name and download_count. GitHub documents the endpoint and response fields in its release-asset API reference.

The JSON request reads the asset’s metadata. It is different from requesting the asset’s binary content for download.

How to Track Downloads Over Time

A single download_count tells you the counter value when you collected it. It does not, by itself, tell you how many downloads happened last week or during a launch campaign.

To calculate a period change, keep two observations:

1. Record a snapshot at the beginning of the period.
2. Record another snapshot at the end.
3. Confirm that the repository and asset ID match.
4. Subtract the first count from the second.

Store the collection time in UTC so reporting periods are unambiguous.

A useful snapshot contains:

Hypothetical Two-Snapshot Calculation

Both rows refer to the same hypothetical asset ID.

510 − 420 = 90

The result is 90 additional counted downloads between the two snapshots.

It is not evidence of 90 different users, 90 installations or 90 active deployments. The two timestamps define the observed interval; without the earlier snapshot, the later value alone cannot reconstruct the count for that period.

What If the Asset ID Changes?

Start a new series if the asset ID changes. A replacement file may have the same or a similar filename, but a different ID means you should not automatically subtract the old asset’s count from the new asset’s count.

For a release-level report covering several files, record a separate snapshot for each included asset. If one is added, removed or replaced between observations, document that change before calculating a combined total.

Release Downloads vs Clones vs Stars

These metrics answer different questions:

For repository views and clones, see GitHub Traffic Analytics. For the distinctions among repository signals, see GitHub Stars vs Watchers vs Forks.

The Promobox GitHub Stars service concerns a repository’s star count. It is not a release-download counter, and a change in stars does not establish a change in downloads.

How to Report a Release Campaign

Record the release date and any announcements alongside the asset snapshots. If the counter rises during a campaign, you can report the observed change for the chosen interval.

For example:

“The Linux asset’s counter increased by 90 between the two UTC snapshots.”

Avoid turning that into “the campaign generated 90 users.” The timing may coincide with the campaign, but the counter alone does not establish which downloads were caused by a particular announcement.

Before sharing the report, check that both snapshots use the same asset ID, the timestamps are clear, and the result is described as additional counted downloads rather than people or installations.