Public API

Turn it on per site and Piqo gives you a URL carrying an unguessable key. Anything that can make an HTTP request can read it: your own website's JavaScript, a static-site build step, a serverless function, a spreadsheet. You choose exactly which data it exposes — everything is opt-in and nothing you didn't tick is ever written to the response.

1. Enable it

1. Open your site's Settings → Public API.
2. Tick Enable the public API. Piqo generates your URL.
3. Tick the datasets it may return, and pick a default range.

2. Fetch your stats

curl "https://app.piqo.app/api/v1/public/YOUR_KEY/stats?period=7d"

The response mirrors your dashboard:

{
  "site":   { "name": "Acme", "domain": "acme.com", "timezone": "UTC" },
  "period": "7d",
  "datasets": ["overview", "sources", "pages"],
  "data": {
    "summary":    { "visitors": 1284, "pageviews": 3907, "bounce_rate": 41.2, ... },
    "timeseries": { "series": [{ "bucket": "2026-08-14", "visitors": 180, ... }] },
    "referrers":  { "rows": [{ "name": "google.com", "visitors": 402, ... }] },
    "pages":      { "rows": [{ "name": "/pricing", "pageviews": 611, ... }] }
  }
}

Parameters

• ?period= — today, yesterday, 24h, 7d, 30d, 90d, 6m, 12m. Anything else falls back to your configured default. Custom date ranges are not exposed publicly.

Endpoints

• /api/v1/public/KEY — what this key exposes (site, enabled datasets, accepted periods).
• /api/v1/public/KEY/stats?period=7d — the stats payload above.
• /api/v1/public/KEY/realtime — { "visitors": 12 }. Only available when the Live visitor count dataset is enabled.

Use it in the browser

CORS is open, so you can call it straight from your own page — no proxy, no server code:

<p>Readers online now: <span id="live">–</span></p>

<script>
  const KEY = 'YOUR_KEY';

  async function refresh() {
    const res = await fetch(`https://app.piqo.app/api/v1/public/${KEY}/realtime`);
    const { visitors } = await res.json();
    document.getElementById('live').textContent = visitors;
  }

  refresh();
  setInterval(refresh, 30000);
</script>

Or render a top-pages list on a static site at build time:

const res  = await fetch('https://app.piqo.app/api/v1/public/YOUR_KEY/stats?period=30d');
const json = await res.json();

for (const page of json.data.pages.rows.slice(0, 5)) {
  console.log(page.name, page.pageviews);
}

What you can expose

• Overview — visitors, pageviews, bounce rate, session time + the time series behind the chart.
• Traffic sources — referrers, UTM terms and content, ad sources, AI assistants.
• Pages — top pages, entry pages, exit pages.
• Geography — countries, cities, continents.
• Devices — device types, browsers, operating systems, languages.
• Custom events and Outbound links.
• Live visitor count — the separate realtime endpoint.

Revenue and conversions are their own toggle and stay off unless you explicitly switch them on.

Limits & caching

• Responses are cached for 60 seconds, so a busy page barely touches Piqo.
• 120 requests per minute per key. Over that you get 429.
• Read-only — the API can never modify anything in your account.
• Disabling the API (or minting a new URL) takes effect instantly; the old URL then returns 404.