specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: GoatCounter
providerId: goatcounter
created: '2026-05-04'
modified: '2026-08-13'
generated: '2026-08-13'
method: probed
source: >-
  https://www.goatcounter.com/help/api (Rate limit section); response headers observed live on
  https://stats.arp242.net/api/v0/api/v0/me on 2026-08-13; forthcoming api2 limit read from
  https://raw.githubusercontent.com/arp242/goatcounter/main/CHANGELOG.md
description: >-
  Published and live-observed rate limits for the GoatCounter JSON API. This file replaces a
  2026-05-04 bulk-sweep scaffold that carried invented free/professional/enterprise tiers,
  invented per-minute and per-month quotas, and the wrong header names (X-RateLimit-* rather
  than the X-Rate-Limit-* GoatCounter actually returns). GoatCounter publishes ONE rate limit
  and it is not tiered.
headers:
  limit: X-Rate-Limit-Limit
  remaining: X-Rate-Limit-Remaining
  reset: X-Rate-Limit-Reset
  policy: null
  retryAfter: null
header_semantics:
  X-Rate-Limit-Limit: Number of requests at which the rate limit kicks in; always the same value.
  X-Rate-Limit-Remaining: Requests remaining this period.
  X-Rate-Limit-Reset: Seconds until the rate limit resets.
responseCodes:
  throttled: null
  note: >-
    The docs do not state the status code returned when the limit is exhausted, and no 429 is
    declared in the provider-published OpenAPI. Not inferred — recorded as a documentation gap.
limit_count: 1
limits:
  - name: JSON API default
    scope: per-site
    metric: requests_per_second
    limit: 4
    burst: null
    timeFrame: second
    tier: all
    applies:
      - GoatCounter JSON API (/api/v0/*)
    evidence:
      docs: https://www.goatcounter.com/help/api
      probed: '2026-08-13'
      url: https://stats.arp242.net/api/v0/me
      observed_headers:
        x-rate-limit-limit: '4'
        x-rate-limit-remaining: '2'
        x-rate-limit-reset: '1'
forthcoming:
  - name: api2 hourly limit
    metric: requests_per_hour
    limit: 500
    status: unreleased
    source: https://raw.githubusercontent.com/arp242/goatcounter/main/CHANGELOG.md
    note: >-
      Listed under "unreleased" in the GoatCounter CHANGELOG: "Add additional api2 ratelimit to
      prevent people constantly hammering the API with 5 requests/second. This defaults to 500
      requests per hour. You can use -ratelimit api2:none to disable this new limit." Self-hosted
      operators can disable it with the -ratelimit flag. Not yet in a tagged release, so it is
      recorded here rather than in limits[].
policies:
  - name: Self-hosted configurability
    description: >-
      Self-hosted GoatCounter exposes a -ratelimit flag on `goatcounter serve`, so the limits above
      describe the goatcounter.com hosted service and the shipped defaults, not a hard ceiling for
      an operator running their own instance.
  - name: Higher limit for backend counting
    description: >-
      The docs note that /api/v0/count has higher rate limits than the browser-facing /count
      endpoint used by count.js, and allows batching multiple pageviews in one request.
    source: https://www.goatcounter.com/help/api
maintainers:
  - FN: Kin Lane
    email: kin@apievangelist.com