github-api-pagination

name	github-api-pagination
description	How to use `gh api` with pagination to retrieve all results from GitHub REST API endpoints, including PRs and issues.

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