# How the HelloGitHub Bot Handles Pagination to Retrieve All Recent Events

> Discover how the HelloGitHub bot uses sequential HTTP requests to fetch all recent events, processing 10 pages of the GitHub Events API for up to 300 entries.

- Repository: [削微寒/HelloGitHub](https://github.com/521xueweihan/HelloGitHub)
- Tags: internals
- Published: 2026-02-25

---

**The HelloGitHub bot retrieves all recent events by iterating through 10 pages of the GitHub Events API, collecting up to 300 events (30 per page) using sequential HTTP requests in [`script/github_bot/github_bot.py`](https://github.com/521xueweihan/HelloGitHub/blob/main/script/github_bot/github_bot.py).**

The `521xueweihan/HelloGitHub` repository includes an automation bot that monitors GitHub user activity to curate content for its monthly publication. To ensure comprehensive data collection without exceeding API constraints, the bot implements explicit pagination logic that handles the retrieval of all recent events through controlled sequential requests.

## Understanding the GitHub Events API Pagination Limits

GitHub's Events API enforces strict pagination boundaries that dictate how the bot structures its data retrieval strategy. The API returns a maximum of **30 items per page** and caps the total accessible events at **300 items** per user.

These constraints mean that fetching the complete allowable dataset requires exactly **10 sequential page requests**. The bot hardcodes this limit in [`script/github_bot/github_bot.py`](https://github.com/521xueweihan/HelloGitHub/blob/main/script/github_bot/github_bot.py) to ensure it captures the full spectrum of recent activity without making unnecessary API calls beyond GitHub's service-defined boundaries.

## How the Bot Fetches Individual Pages

The pagination implementation relies on two core functions: `get_data()` for single-page retrieval and `get_all_data()` for aggregation. The single-page function constructs targeted HTTP requests with explicit page parameters.

### Building the Paginated Request

The `get_data(page=1)` function in [`script/github_bot/github_bot.py`](https://github.com/521xueweihan/HelloGitHub/blob/main/script/github_bot/github_bot.py) constructs the paginated query by appending a page parameter to the GitHub Events API endpoint. It builds the query string using `?page={page}` and targets the authenticated user's received events at `https://api.github.com/users/{username}/received_events`.

```python
def get_data(page=1):
    """Fetch one page of events."""
    args = f'?page={page}'
    response = requests.get(API['events'] + args,
                            auth=(ACCOUNT['username'], ACCOUNT['password']))
    if response.status_code == 200:
        return response.json()
    return []

```

### Handling API Authentication

Each paginated request includes **Basic Authentication** using the bot's configured GitHub credentials. The `auth` tuple passes the username and password (or personal access token) with every request to ensure access to private events and to comply with GitHub's authenticated rate limits, which permit 5,000 requests per hour compared to 60 for unauthenticated requests.

## Aggregating All Recent Events with Sequential Pagination

The `get_all_data()` function orchestrates the complete data collection by executing a fixed-size loop that sequentially requests all ten pages of events. This approach ensures the bot retrieves the maximum allowable 300 recent events without missing data or exceeding API limits.

The function initializes an empty list `all_data_list` and iterates `for i in range(10)`, calling `get_data(i + 1)` to fetch pages 1 through 10. Each successful response extends the master list using `extend()`, which flattens the JSON array of events into the aggregate collection.

```python
def get_all_data():
    """Collect up to 300 recent events (10 pages × 30 items)."""
    all_data_list = []
    for i in range(10):                     # pages 1‑10

        page_data = get_data(i + 1)
        if page_data:
            all_data_list.extend(page_data)
    return all_data_list

```

This sequential pagination strategy guarantees that the bot captures the complete set of recent GitHub events available through the API, providing comprehensive data for subsequent content curation and analysis workflows.

## Summary

- The HelloGitHub bot retrieves recent events from `https://api.github.com/users/{username}/received_events` using explicit pagination logic defined in [`script/github_bot/github_bot.py`](https://github.com/521xueweihan/HelloGitHub/blob/main/script/github_bot/github_bot.py).
- GitHub's Events API limits responses to **30 items per page** with a maximum of **300 total events**, necessitating exactly **10 paginated requests**.
- The `get_data(page)` function constructs individual HTTP requests with `?page={page}` query parameters and authenticates using Basic Auth credentials.
- The `get_all_data()` function aggregates results by iterating `range(10)`, extending a master list with each page's JSON response to compile the complete 300-event dataset.

## Frequently Asked Questions

### Why does the bot stop at 10 pages?

The bot stops at 10 pages because GitHub's Events API enforces a hard limit of 300 events per user. Since the API returns 30 events per page, 10 pages exactly exhausts the available data (10 × 30 = 300). Requesting additional pages would return empty results or 422 errors, so the fixed loop in `get_all_data()` optimizes performance by avoiding unnecessary API calls.

### How does the bot handle API rate limits?

The bot handles rate limits by using **authenticated requests** with Basic Authentication (username and password/token), which increases the hourly quota from 60 to 5,000 requests. Since the pagination logic only requires 10 requests per execution to fetch 300 events, the bot operates well within these limits even during frequent runs. The code checks for `status_code == 200` to ensure successful responses before processing data.

### Can the pagination logic be modified to fetch fewer events?

Yes, developers can modify the pagination depth by adjusting the `range(10)` parameter in the `get_all_data()` function. Changing this to `range(5)` would fetch only 150 events (5 pages), while `range(1)` would retrieve only the most recent 30 events. However, reducing the page count means missing older events that might be relevant for the bot's content curation purposes, so modifications should align with the specific data requirements of the workflow.

### What authentication method does the bot use for GitHub API requests?

The bot uses **Basic Authentication** via the `requests` library's `auth` parameter, passing a tuple of `(username, password)` or `(username, personal_access_token)`. This authentication method is specified in the `get_data()` function where `requests.get(API['events'] + args, auth=(ACCOUNT['username'], ACCOUNT['password']))` executes the authenticated request. Basic Auth is required to access private received events and to benefit from the higher 5,000 requests/hour rate limit.