name: goatcounter
description: Query GoatCounter analytics API for pageviews, visitor stats, top pages, and referrers. Use when checking website analytics, traffic stats, visitor counts, or page performance. Triggers on: GoatCounter, analytics, pageviews, visitors, traffic, stats, referrers.

GoatCounter Analytics

Query GoatCounter via REST API. Lightweight, privacy-friendly web analytics.

Prerequisites

1. Create API Token: Dashboard → Settings → API tokens → New
2. Set Environment Variables:
   bash export GOATCOUNTER_SITE="yoursite" # Site code (from yoursite.goatcounter.com) export GOATCOUNTER_TOKEN="your-token" # API token

API Basics

• Base URL: https://{site}.goatcounter.com/api/v0
• Auth: Authorization: Bearer {token}
• Rate Limit: 4 requests/second

Quick Commands

Check Auth

curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/me" | jq

Total Stats (pageviews + visitors)

# Last 7 days
curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/stats/total" | jq

# Custom date range
curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/stats/total?start=2024-01-01&end=2024-01-31" | jq

Today's Stats

TODAY=$(date +%Y-%m-%d)
curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/stats/total?start=$TODAY&end=$TODAY" | jq

Top Pages (hits per path)

curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/stats/hits?limit=10" | jq

All Paths

curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/paths" | jq

Referrer Stats for a Path

# Get path_id from /paths first, then:
curl -sH "Authorization: Bearer $GOATCOUNTER_TOKEN" \
  "https://$GOATCOUNTER_SITE.goatcounter.com/api/v0/stats/hits/{path_id}" | jq

Helper Script

Use scripts/goatcounter.sh for common queries:

./goatcounter.sh stats          # Total stats (7 days)
./goatcounter.sh today          # Today's visitors
./goatcounter.sh pages [n]      # Top n pages (default 10)
./goatcounter.sh paths          # List all paths
./goatcounter.sh me             # Auth check

Response Examples

/stats/total

{
  "total": 1234,
  "total_unique": 567
}

/stats/hits

{
  "hits": [
    {
      "path": "/",
      "title": "Home",
      "count": 500,
      "count_unique": 200
    }
  ]
}

/paths

{
  "paths": [
    {
      "id": 1,
      "path": "/",
      "title": "Home",
      "event": false
    }
  ]
}

Common Workflows

Daily Traffic Summary

1. Query /stats/total with today's date
2. Query /stats/hits?limit=5 for top pages
3. Report: total visitors, top pages

Weekly Report

1. Query /stats/total for last 7 days
2. Query /stats/hits for page breakdown
3. Compare to previous week if needed

Debug Low Traffic

1. Check /paths to see what's being tracked
2. Query /stats/hits for specific pages
3. Check referrer stats for traffic sources