{"openapi":"3.1.0","info":{"title":"quietstats Stats API","version":"1.0.0","description":"Read-only, aggregate, cookie-free website statistics. Bearer API keys created in Settings → API keys. Rate limits per key per hour: free 300, starter 2000, growth 6000, business 20000. Responses never include visitor hashes, IP addresses, user agents or individual events."},"servers":[{"url":"https://quietstats.co.uk/api/v1"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"qs_<48 hex>"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","invalid_key","forbidden","site_not_found","missing_param","invalid_param","not_found","method_not_allowed","rate_limited","internal"]},"message":{"type":"string"},"status":{"type":"integer"},"docs":{"type":"string"}}}}},"Sites":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"domain":{"type":"string"},"created":{"type":"string","format":"date-time"}}}}}},"Aggregate":{"type":"object","properties":{"site":{"type":"string"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"timezone":{"type":"string","const":"UTC"}}},"compare":{"type":"object","properties":{"previous_from":{"type":"string","format":"date"},"previous_to":{"type":"string","format":"date"}}},"filters":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"op":{"type":"string","enum":["==","!="]},"values":{"type":"array","items":{"type":"string"}}}}},"results":{"type":"object","properties":{"visitors":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}},"pageviews":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}},"visits":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}},"views_per_visit":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}},"bounce_rate":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}},"visit_duration":{"type":"object","properties":{"value":{"type":"number"},"previous":{"type":"number"},"change":{"type":["number","null"],"description":"Fractional change vs previous period"}}}}}}},"Timeseries":{"type":"object","properties":{"site":{"type":"string"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"timezone":{"type":"string","const":"UTC"}}},"interval":{"type":"string","enum":["hour","day","week","month"]},"filters":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"op":{"type":"string","enum":["==","!="]},"values":{"type":"array","items":{"type":"string"}}}}},"results":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","description":"Bucket start: YYYY-MM-DDTHH:00:00Z, YYYY-MM-DD (day/week, weeks start Monday) or YYYY-MM"},"visitors":{"type":"integer","description":"Unique visitors (daily-rotating hash; multi-day totals are the sum of daily uniques)"},"pageviews":{"type":"integer"},"visits":{"type":"integer","description":"Visits: pageviews ≤30 min apart"},"views_per_visit":{"type":"number"},"bounce_rate":{"type":"number","description":"0–1 share of single-page visits"},"visit_duration":{"type":"integer","description":"Average seconds, first→last pageview"}}}}}},"Breakdown":{"type":"object","properties":{"site":{"type":"string"},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"days":{"type":"integer"},"timezone":{"type":"string","const":"UTC"}}},"property":{"type":"string","enum":["page","entry_page","exit_page","referrer","channel","ai","utm_source","utm_medium","utm_campaign","country","device","browser","os","screen"]},"filters":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"op":{"type":"string","enum":["==","!="]},"values":{"type":"array","items":{"type":"string"}}}}},"sort":{"type":"string"},"search":{"type":["string","null"]},"totals":{"type":"object","description":"Sums over every value in the period (before search), for shares"},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}},"results":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"visitors":{"type":"integer"},"pageviews":{"type":"integer","description":"Not for entry_page/exit_page"},"visits":{"type":"integer","description":"entry_page/exit_page only"},"bounce_rate":{"type":"number"},"visit_duration":{"type":"integer"}}}}}},"Realtime":{"type":"object","properties":{"site":{"type":"string"},"window_minutes":{"type":"integer"},"visitors":{"type":"integer"},"pages":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"visitors":{"type":"integer"}}}},"countries":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string","description":"ISO country code or ??"},"visitors":{"type":"integer"}}}},"recent":{"type":"array","description":"Latest pageviews in the last 30 minutes, newest first (max 20). No visitor IDs.","items":{"type":"object","properties":{"time":{"type":"string","format":"date-time"},"seconds_ago":{"type":"integer"},"page":{"type":"string"},"referrer":{"type":["string","null"]},"country":{"type":["string","null"]},"device":{"type":["string","null"]},"browser":{"type":["string","null"]}}}},"generated_at":{"type":"string","format":"date-time"}}}}},"paths":{"/sites":{"get":{"summary":"List your sites","description":"A key limited to one site only lists that site.","parameters":[{"name":"format","in":"query","required":false,"description":"json or csv","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Sites","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time the hourly window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Sites"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/aggregate":{"get":{"summary":"Headline numbers with comparison","parameters":[{"name":"site","in":"query","required":true,"description":"Site ID from your Sites page.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"today, 7d, 30d (default), 90d, 12mo, all (since the first day of data, no cap) or custom.","schema":{"type":"string","enum":["today","7d","30d","90d","12mo","all","custom"],"default":"30d"}},{"name":"from","in":"query","required":false,"description":"Start date (UTC, inclusive) when period=custom.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date (UTC, inclusive) when period=custom. Max range 400 days.","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","required":false,"description":"Semicolon-separated filters: key==value or key!=value, values OR-ed with \"|\". Keys: page, referrer, country, device, browser, os, screen, utm_source, utm_medium, utm_campaign. referrer==(direct) matches no referrer. Example: country==GB;device==Mobile|Tablet","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"compare","in":"query","required":false,"description":"Compare with the previous period of equal length (default true).","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Aggregate metrics","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time the hourly window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Aggregate"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/timeseries":{"get":{"summary":"Metrics over time","parameters":[{"name":"site","in":"query","required":true,"description":"Site ID from your Sites page.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"today, 7d, 30d (default), 90d, 12mo, all (since the first day of data, no cap) or custom.","schema":{"type":"string","enum":["today","7d","30d","90d","12mo","all","custom"],"default":"30d"}},{"name":"from","in":"query","required":false,"description":"Start date (UTC, inclusive) when period=custom.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date (UTC, inclusive) when period=custom. Max range 400 days.","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","required":false,"description":"Semicolon-separated filters: key==value or key!=value, values OR-ed with \"|\". Keys: page, referrer, country, device, browser, os, screen, utm_source, utm_medium, utm_campaign. referrer==(direct) matches no referrer. Example: country==GB;device==Mobile|Tablet","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"interval","in":"query","required":false,"description":"hour (≤31 days), day, week or month. Default depends on the range.","schema":{"type":"string","enum":["hour","day","week","month"]}},{"name":"metrics","in":"query","required":false,"description":"Comma-separated subset of visitors, pageviews, visits, views_per_visit, bounce_rate, visit_duration.","schema":{"type":"string"}}],"responses":{"200":{"description":"Buckets with no gaps","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time the hourly window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Timeseries"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/breakdown":{"get":{"summary":"Every value of a property (full, paged list)","parameters":[{"name":"site","in":"query","required":true,"description":"Site ID from your Sites page.","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"today, 7d, 30d (default), 90d, 12mo, all (since the first day of data, no cap) or custom.","schema":{"type":"string","enum":["today","7d","30d","90d","12mo","all","custom"],"default":"30d"}},{"name":"from","in":"query","required":false,"description":"Start date (UTC, inclusive) when period=custom.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"End date (UTC, inclusive) when period=custom. Max range 400 days.","schema":{"type":"string","format":"date"}},{"name":"filters","in":"query","required":false,"description":"Semicolon-separated filters: key==value or key!=value, values OR-ed with \"|\". Keys: page, referrer, country, device, browser, os, screen, utm_source, utm_medium, utm_campaign. referrer==(direct) matches no referrer. Example: country==GB;device==Mobile|Tablet","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv.","schema":{"type":"string","enum":["json","csv"],"default":"json"}},{"name":"property","in":"query","required":true,"description":"What to break down by.","schema":{"type":"string","enum":["page","entry_page","exit_page","referrer","channel","ai","utm_source","utm_medium","utm_campaign","country","device","browser","os","screen"]}},{"name":"limit","in":"query","required":false,"description":"Rows per page, 1–1000 (default 100).","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}},{"name":"page","in":"query","required":false,"description":"Page number, from 1.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"offset","in":"query","required":false,"description":"Row offset from 0 (alternative to page).","schema":{"type":"integer","minimum":0}},{"name":"search","in":"query","required":false,"description":"Case-insensitive match on the value (country also matches English names).","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"visitors (default) or pageviews; entry_page/exit_page: visits (default) or visitors.","schema":{"type":"string","enum":["visitors","pageviews","visits"]}}],"responses":{"200":{"description":"Sorted by visitors (or visits for entry/exit pages)","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time the hourly window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Breakdown"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/realtime":{"get":{"summary":"Visitors in the last 5 minutes","parameters":[{"name":"site","in":"query","required":true,"description":"Site ID from your Sites page.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"json (default) or csv.","schema":{"type":"string","enum":["json","csv"],"default":"json"}}],"responses":{"200":{"description":"Live counts","headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix time the hourly window resets"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Realtime"}},"text/csv":{"schema":{"type":"string"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}