GitHub API Pagination with gh api

Overview

GitHub REST API returns paginated results (default 30, max 100 per page). Use gh api with --paginate to automatically fetch all pages.

Basic Usage

# Fetch all pages automatically
gh api --paginate /repos/OWNER/REPO/pulls \
  -X GET \
  -f state=all \
  -f per_page=100

# Use GraphQL for complex queries (no pagination needed for small sets)
gh api graphql -f query='...'

REST API: List PRs with Date Filtering

# Get all PRs created in December 2024 (state=all includes open/closed/merged)
gh api --paginate \
  "repos/cli/cli/pulls?state=all&per_page=100&sort=created&direction=desc" \
  --jq '.[] | select(.created_at >= "2024-12-01T00:00:00Z" and .created_at < "2025-01-01T00:00:00Z")'

Note: --jq applies a jq filter to each page's output.

REST API: List Issues with Date Filtering

gh api --paginate \
  "repos/cli/cli/issues?state=all&per_page=100&sort=created&direction=desc" \
  --jq '.[] | select(.pull_request == null)'  # exclude PRs from issues endpoint

Search API (Efficient for Date Ranges)

The Search API is better for date-bounded queries:

# PRs created in Dec 2024
gh api --paginate \
  "search/issues?q=repo:cli/cli+is:pr+created:2024-12-01..2024-12-31&per_page=100" \
  --jq '.items[]'

# Issues created in Dec 2024
gh api --paginate \
  "search/issues?q=repo:cli/cli+is:issue+created:2024-12-01..2024-12-31&per_page=100" \
  --jq '.items[]'

Combining Pages into a Single JSON Array

# Collect all pages into a single JSON array using --paginate + jq slurp
gh api --paginate \
  "repos/cli/cli/pulls?state=all&per_page=100" \
  --jq '.[]' | jq -s '.'

Key Fields

Field	Description
created_at	ISO8601 timestamp when PR/issue was created
merged_at	ISO8601 timestamp when PR was merged (null if not merged)
closed_at	ISO8601 timestamp when PR/issue was closed
state	open, closed
pull_request.merged_at	For search API results
labels[].name	Array of label objects with name field
user.login	Author's GitHub username

Rate Limits

• REST API: 5000 requests/hour (authenticated)
• Search API: 30 requests/minute (authenticated)
• Use gh api -i to see rate limit headers