Using the Clicky API (for AI agents)

Clicky's public API is plain HTTP with query parameters via POST (recommended) or GET. No OAuth, token exchange, or SDK required. If your app speaks HTTP, you can use it. The full API reference is at /help/api, this page is just the bootstrap and the worked examples.


Use output=md unless you have a reason not to. It returns the same data as markdown tables, which costs a fraction of the tokens of JSON or XML, so it's the cheapest option to put in a model's context. The JSON examples below stay in JSON so you can see the underlying structure, which is useful when you do want to parse values programmatically (output=json). Sending an Accept: text/markdown header instead of the param works too: if output is absent we serve (or redirect to) markdown; an explicit output always wins.



Authentication

Two kinds of keys:

  • userkey - Authenticates the Account API and MCP server. Read-only. Outputs a list of all sites in a user account, including the site_id and sitekeys needed to query the Analytics API (see next item). The user finds or generates it at /user/edit.
  • site_id / sitekey - Authenticates the Analytics API. Get every site's id and sitekey from the Account API call below, so you only ever need the userkey to start.


Step 1: the site list

POST https://clicky.com/api/account/sites
Content-Type: application/x-www-form-urlencoded

userkey=USERKEY

Response (an array, one object per site; abridged):


[
  {
    "site_id":"123",
    "hostname":"example.com",
    "nickname":"My site",
    "sitekey":"a1b2c3d4e5f6a7b8",
    "timezone":"-8",
    "visitors_online":"3",
    "visitors_today":"412"
  }
]

The full response carries a couple more per-site fields (hash, sitekey_admin); the four above are the ones an agent needs. Note the site_id and sitekey of the site the user means. If the hostname they described isn't in the list, site registration is human-only, see the install procedure.



Step 2: a report

POST https://clicky.com/api/stats/4
Content-Type: application/x-www-form-urlencoded

site_id=123&sitekey=a1b2c3d4e5f6a7b8&type=visitors,actions-pageviews&date=last-7-days&output=json

Response (tallies carry a dates array even for a single range, summed):


[
  {
    "type": "visitors",
    "dates": [
      { "date": "2026-11-06,2026-11-12", "items": [ { "value": "1234" } ] }
    ]
  },
  {
    "type": "actions-pageviews",
    "dates": [
      { "date": "2026-11-06,2026-11-12", "items": [ { "value": "4567" } ] }
    ]
  }
]

List types (top pages, countries, referrers, ...) return the same skeleton with one object per item in items, each carrying value, value_percent, and whatever fields that type has (e.g. url and title for pages):


[
  {
    "type": "pages",
    "dates": [
      { "date": "2026-11-12", "items": [
        { "value":"431", "value_percent":"37.2", "title":"Homepage", "url":"https://example.com/" },
        { "value":"207", "value_percent":"17.9", "title":"Pricing",  "url":"https://example.com/pricing" }
      ]}
    ]
  }
]

The date parameter accepts today, yesterday, last-7-days, YYYY-MM-DD, YYYY-MM-DD,YYYY-MM-DD ranges, and more, the full format list is on /help/api. An invalid date is silently replaced with today rather than erroring, so sanity-check that the dates in the response match what you asked for.



Failure shapes

With output=json, errors come back as an array holding one error object (HTTP 200, so check the body, not the status):


[{"error":"Invalid API key."}]

With output=md the same errors are a single line of text, ERROR: Invalid API key.


  • Invalid API key. -- the userkey is wrong. Tell the user to regenerate it at /user/edit, don't retry with the same key.
  • Invalid sitekey. -- sitekey doesn't match that site_id. Re-run step 1, the site may have been recreated.
  • Invalid site_id. -- same drill.
  • Too many failed authorizations. Try again in 15 minutes. -- you tripped the brute-force protection. Back off the full 15 minutes, retrying sooner extends it.
  • Free accounts are limited to the last 31 days of history. -- ask the user about upgrading, don't just clamp the date range silently and call it a day.


Etiquette

  • POST preferred over GET (keeps keys out of server logs and proxy caches). GET works identically.
  • Cache timings are plan-based: 60 seconds on premium (incl. trial), 15 minutes on free. Don't poll faster than that; repeat requests inside the window can't return newer data, they just burn quota. Date ranges entirely in the past are cached for an hour, since that data can't change.
  • Page through big reports. limit caps results (default 50), page walks them. For visitors-list, actions-list, and segmentation: max 31-day range, max 1,000 items per request, one simultaneous request per IP per site.
  • Batch types into one request with commas (type=visitors,countries,searches) instead of one request per type.
  • Request output=md when you're going to read the results yourself rather than parse them. One table per type and date, cheapest option in tokens.
  • URL-encode every value. A href or search containing &, = or a space breaks the request body unless it arrives percent-encoded (href=%2Fpricing%3Fa%3Db). Over MCP most clients encode it for you; when you build the string yourself, encode it yourself.
  • Write operations don't exist. If the user asks you to change a setting, add a goal, or create a site via the API, see what agents cannot do.


If your client speaks MCP, prefer the hosted server at /help/agents/mcp, which wraps these same endpoints with the auth handled once.




📢 See exactly how your visitors interact with your site

Get started with Clicky today and take your analytics to the next level