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

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, 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. The fetchWakatimeStats function dynamically builds the target URL:

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):

[![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:

[![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:

[![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.
• The fetchWakatimeStats function in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}