GitHub Actions API Returns 2,500+: Fix Workflow Run Reporting Scripts

GitHub changed how large workflow-run queries are counted in the Actions UI and REST API. When a filtered query matches more than 2,500 runs, the reported count becomes 2,500+ instead of an exact number.

GitHub made the change because very large count queries frequently timed out and could return a precise-looking but incomplete number. The new value is less precise, but it does not pretend that a partial count is exact.

If a dashboard, compliance export, or cost report treats total_count as an exact integer, update it now.

What changed

The behavior applies when workflow runs are searched by fields such as workflow, event, status, branch, or actor. GitHub continues returning paginated results, but a single query is limited to at most 1,000 returned items. When matching records exceed 2,500, the displayed count is 2,500+.

This means two separate assumptions can break:

1. total_count is always an exact count;
2. paging one broad filtered query can export every historical run.

The safe pattern is to split reporting into bounded date windows and paginate each window.

Find scripts that rely on total_count

Search automation repositories:

rg -n 'total_count|actions/runs|workflow_runs' scripts .github src

Review code that calculates the number of pages from total_count, expects a numeric equality, or fetches an entire year with one status or branch filter.

Use the created filter

The workflow-runs endpoint accepts a created date-time range and up to 100 results per page. A GitHub CLI request for one day looks like:

gh api --method GET --paginate \
  -H 'X-GitHub-Api-Version: 2026-03-10' \
  /repos/OWNER/REPO/actions/runs \
  -f per_page=100 \
  -f created='2026-09-01T00:00:00Z..2026-09-01T23:59:59Z' \
  --jq '.workflow_runs[] | [.id, .name, .event, .status, .conclusion, .created_at] | @tsv'

Use non-overlapping UTC windows so the same run cannot land in two exports. If a busy repository produces close to 1,000 matching runs in one day, split that day into hourly windows.

A windowed export pattern

#!/usr/bin/env bash
set -euo pipefail
 
owner="example"
repo="platform"
 
for day in 01 02 03 04 05 06 07; do
  range="2026-09-${day}T00:00:00Z..2026-09-${day}T23:59:59Z"
 
  gh api --method GET --paginate \
    -H 'X-GitHub-Api-Version: 2026-03-10' \
    "/repos/${owner}/${repo}/actions/runs" \
    -f per_page=100 \
    -f created="$range" \
    --jq '.workflow_runs[] | {id, workflow_id, run_number, run_attempt, event, status, conclusion, created_at}'
done | jq -s 'unique_by(.id)'

Deduplicate by the immutable run ID, not by workflow name or run number. Persist the window used for each export so a failed job can retry only the missing range.

For incremental reporting, store a high-water mark and include a small overlap in the next query. Deduplicate the overlap by run ID. This protects against delayed processing without repeatedly scanning the full history.

Do not parse 2,500+ as 2,500

Treat the count as a display hint:

type QueryCount = number | "2500+"
 
function isExactCount(value: QueryCount): value is number {
  return typeof value === "number"
}

If your API client exposes only a number, verify its behavior against a repository with a large result set. Do not strip the plus sign and report 2,500 as an exact compliance total.

Add completeness checks

A reliable export should record:

• repository and filters;
• start and end timestamps;
• number of unique run IDs received;
• first and last created_at timestamps;
• HTTP failures and retry attempts;
• whether the window approached the 1,000-result ceiling.

Alert when a window hits the ceiling, then rerun it with smaller windows. This makes truncation visible instead of silently undercounting activity.

Migration checklist

• Find consumers of workflow-run total_count.
• Stop treating 2,500+ as an exact total.
• Add explicit UTC date windows.
• Paginate with per_page=100.
• Split windows that approach 1,000 returned runs.
• Deduplicate by workflow-run ID.
• Store checkpoints and completeness metadata.
• Test on a high-volume repository before replacing the old report.

Want a structured path for building secure CI/CD workflows? Explore this GitHub Actions course on Udemy. Affiliate link: DevOpsBoys may earn a commission at no extra cost to you.

Sources

• GitHub Changelog: Changes to query results in the Actions API and UI
• GitHub Docs: REST API endpoints for workflow runs
• GitHub Docs: Using pagination in the REST API