# How to Display WakaTime Stats Using Hakatime or Wakapi with GitHub Readme Stats

> Display WakaTime stats on your GitHub README using Hakatime or Wakapi. Learn how to customize your GitHub Readme Stats card with the api_domain parameter for personalized insights.

- Repository: [Anurag Hazra/github-readme-stats](https://github.com/anuraghazra/github-readme-stats)
- Tags: tutorial
- Published: 2026-02-28

---

**You can display WakaTime statistics from alternative backends like Hakatime or Wakapi by adding the `api_domain` query parameter to your GitHub Readme Stats card URL, overriding the default `wakatime.com` endpoint.**

The `anuraghazra/github-readme-stats` repository supports custom WakaTime-compatible API domains, allowing you to connect self-hosted or alternative time-tracking services. By configuring the `api_domain` parameter, the card fetches data from Hakatime, Wakapi, or any service implementing the WakaTime API contract.

## How the WakaTime Card Handles Custom API Domains

When you request a WakaTime card, the system processes your query through a specific pipeline that constructs the external API call.

The entry point is [`api/wakatime.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/wakatime.js), which extracts query parameters including the optional `api_domain` and passes them through the standard access-guard logic【/cache/repos/github.com/anuraghazra/github-readme-stats/master/api/wakatime.js†L20-L44】.

The critical logic resides in [`src/fetchers/wakatime.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/fetchers/wakatime.js). The `fetchWakatimeStats` function dynamically builds the target URL:

```javascript
const { data } = await axios.get(
  `https://${api_domain ? api_domain.replace(/\/$/gi, "") : "wakatime.com"}/api/v1/users/${username}/stats?is_including_today=true`,
);

```

This implementation defaults to `wakatime.com` but substitutes any domain you provide via the `api_domain` parameter【/cache/repos/github.com/anuraghazra/github-readme-stats/master/src/fetchers/wakatime.js†L18-L22】. The fetched JSON is then passed to `renderWakatimeCard` to generate the final SVG.

## Configuring Hakatime with GitHub Readme Stats

Hakatime provides a WakaTime-compatible API endpoint that you can connect to GitHub Readme Stats using the custom domain parameter.

### Step-by-Step Implementation

Add the `api_domain` parameter pointing to `api.hakatime.com` (or your self-hosted Hakatime instance):

```markdown
[![My WakaTime stats (Hakatime)](https://github-readme-stats.vercel.app/api/wakatime?username=YOUR_WAKATIME_USER&api_domain=api.hakatime.com)](https://github.com/YOUR_GITHUB_USER)

```

Replace `YOUR_WAKATIME_USER` with your Hakatime username and `YOUR_GITHUB_USER` with your GitHub username. The card will fetch statistics from the Hakatime API instead of the default WakaTime servers.

## Configuring Wakapi with GitHub Readme Stats

Wakapi is another self-hosted, WakaTime-compatible tracking service that works seamlessly with GitHub Readme Stats through the same `api_domain` mechanism.

### Implementation Example

Point the `api_domain` parameter to `api.wakapi.dev` or your self-hosted Wakapi domain:

```markdown
[![My WakaTime stats (Wakapi)](https://github-readme-stats.vercel.app/api/wakatime?username=YOUR_WAKATIME_USER&api_domain=api.wakapi.dev)](https://github.com/YOUR_GITHUB_USER)

```

For a self-hosted Wakapi instance, replace `api.wakapi.dev` with your custom domain (e.g., `wakapi.yourdomain.com`), ensuring the trailing slash is omitted as handled by the regex replacement in the fetcher logic.

## Customizing Display Format and Other Options

Beyond switching API domains, you can control how the statistics appear using standard WakaTime card parameters.

The `display_format` parameter accepts `time` (default) or `percent` to change the metric visualization:

```markdown
[![My WakaTime stats (percent)](https://github-readme-stats.vercel.app/api/wakatime?username=YOUR_WAKATIME_USER&api_domain=api.wakapi.dev&display_format=percent)](https://github.com/YOUR_GITHUB_USER)

```

All other standard options—such as `theme`, `hide_title`, `hide_progress`, and `custom_title`—function identically regardless of which `api_domain` you specify, as the rendering logic in `renderWakatimeCard` processes the data agnostically after retrieval.

## Summary

- **GitHub Readme Stats** supports custom WakaTime-compatible backends via the `api_domain` query parameter in [`api/wakatime.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/api/wakatime.js).
- The `fetchWakatimeStats` function in [`src/fetchers/wakatime.js`](https://github.com/anuraghazra/github-readme-stats/blob/main/src/fetchers/wakatime.js) constructs the external API URL, defaulting to `wakatime.com` but substituting any domain you provide.
- **Hakatime** users should set `api_domain=api.hakatime.com` (or their self-hosted domain).
- **Wakapi** users should set `api_domain=api.wakapi.dev` (or their self-hosted domain).
- All standard card customization options—`display_format`, themes, and hiding options—work identically with custom domains.

## Frequently Asked Questions

### Can I use a self-hosted WakaTime instance with GitHub Readme Stats?

Yes. The `api_domain` parameter accepts any domain string, allowing you to point the card at self-hosted Hakatime, Wakapi, or private WakaTime instances. Ensure your self-hosted service exposes the `/api/v1/users/:username/stats` endpoint with the same JSON schema as the official WakaTime API.

### What API endpoints must my custom domain support?

Your custom backend must implement the WakaTime API contract, specifically the `GET /api/v1/users/{username}/stats?is_including_today=true` endpoint. The response must return a JSON object containing a `data` property with fields like `languages`, `editors`, `operating_systems`, and `total_seconds` or `percent` values, depending on your `display_format` setting.

### How do I troubleshoot connection errors when using Hakatime or Wakapi?

First, verify that your `api_domain` value does not include a trailing slash or protocol prefix (the fetcher automatically prepends `https://` and strips trailing slashes using the regex `/\/$/gi`). Test the endpoint directly in your browser: `https://<your_domain>/api/v1/users/<username>/stats`. If the direct request fails, the issue lies with the backend configuration, not the GitHub Readme Stats card.

### Does the api_domain parameter support HTTP vs HTTPS?

The fetcher hardcodes `https://` at the beginning of the URL template, so only HTTPS endpoints are supported. If your self-hosted instance uses HTTP, the request will fail due to protocol mismatch. You must configure SSL/TLS on your custom domain or use a reverse proxy with HTTPS termination to use it with GitHub Readme Stats.