API Reference

The Clickport API lets you query your analytics data programmatically, send events from your server, and access realtime visitor counts. All endpoints require authentication via API key.

Authentication

Every API request must include your site's API key. You can find and manage your API keys in Settings → API Keys in your dashboard.

Pass the key in the x-api-key HTTP header:

curl https://clickport.io/api/query \
  -H "x-api-key: ck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"metrics": ["visitors"], "period": "30d"}'

API keys start with ck_ and are scoped to a single site. Each key has read and tracker permissions, allowing you to query data and send events.

Base URL

All API endpoints use the base URL:

https://clickport.io/api

Rate limits

The event ingestion endpoint (/api/event) is rate-limited to 60 requests per minute per IP address. When the limit is exceeded, events are silently dropped (the response still returns 200). Query endpoints do not have a per-request rate limit but are subject to fair use.

Stats API

Query your analytics data with flexible metrics, dimensions, filters, and date ranges.

Request body

Available metrics

• visitors - Unique visitors
• sessions - Total sessions
• pageviews - Total pageviews
• views_per_visit - Average pageviews per session
• bounce_rate - Percentage of single-page sessions (0-100)
• avg_duration - Average session duration in seconds
• avg_scroll - Average scroll depth (0-100)
• clickers - Sessions with at least one click event

Available dimensions

• URL: page, entry_page, exit_page, outbound
• Acquisition: source, channel, campaign, utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer_url
• Location: continent, country, region, city
• Device: browser, browser_version, os, os_version, device, screen
• Time (grouping only): hour, date, week, month

Periods

• realtime - Last 30 minutes
• today, yesterday
• 7d, 14d, 30d, 90d - Last N days
• 12m - Last 12 months
• all - All time
• Or use date_range for custom ranges

Filter operators

• is (alias "is") - Exact match, case-sensitive. Multi-value emits IN (...).
• is_not (alias "is not") - Excludes exact matches, case-sensitive. Multi-value emits NOT IN (...).
• contains - Substring match, case-insensitive (uses ClickHouse ILIKE). Multi-value combines with OR.
• not_contains (alias "does not contain") - Excludes substring matches, case-insensitive. Multi-value combines with AND-of-NOT.
• starts_with - Starts with value, case-sensitive. API only, not exposed in the dashboard UI.
• ends_with - Ends with value, case-sensitive. API only, not exposed in the dashboard UI.

The dashboard UI exposes is, is_not, contains, and not_contains. The API additionally accepts starts_with and ends_with for direct integrations.

Example: Aggregate query

Get total visitors, pageviews, and bounce rate for the last 30 days:

curl -X POST https://clickport.io/api/query \
  -H "x-api-key: ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["visitors", "pageviews", "bounce_rate"],
    "period": "30d"
  }'

Response:

{
  "results": {
    "visitors": 4821,
    "pageviews": 12493,
    "bounce_rate": 42
  }
}

Example: Breakdown query

Get top pages by visitors for a custom date range, filtered to Germany:

curl -X POST https://clickport.io/api/query \
  -H "x-api-key: ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["visitors", "pageviews", "avg_scroll"],
    "dimensions": ["page"],
    "date_range": {"start": "2026-03-01", "end": "2026-03-31"},
    "filters": [{"dimension": "country", "operator": "is", "value": "DE"}],
    "limit": 10,
    "timezone": "Europe/Berlin"
  }'

Response:

{
  "results": [
    { "page": "/", "visitors": 312, "pageviews": 487, "avg_scroll": 65 },
    { "page": "/pricing", "visitors": 198, "pageviews": 214, "avg_scroll": 78 },
    { "page": "/blog/privacy", "visitors": 145, "pageviews": 152, "avg_scroll": 82 }
  ]
}

Example: Time series

Get daily visitor counts for the last 7 days:

curl -X POST https://clickport.io/api/query \
  -H "x-api-key: ck_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["visitors", "pageviews"],
    "dimensions": ["date"],
    "period": "7d"
  }'

Response:

{
  "results": [
    { "date": "2026-03-25", "visitors": 183, "pageviews": 421 },
    { "date": "2026-03-26", "visitors": 201, "pageviews": 467 },
    { "date": "2026-03-27", "visitors": 195, "pageviews": 442 }
  ]
}

Events API

Send events from your server. Use this for server-side tracking, mobile apps, or any environment where the JavaScript tracker is not available.

Request body

Example: Track a pageview

curl -X POST https://clickport.io/api/event \
  -H "x-api-key: ck_your_key" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 ..." \
  -d '{
    "type": "pageview",
    "url": "https://yoursite.com/pricing",
    "referrer": "https://google.com/"
  }'

Response:

{
  "success": true,
  "session_id": 48291,
  "page_visit_id": "a1b2c3d4"
}

Example: Track a custom event with revenue

curl -X POST https://clickport.io/api/event \
  -H "x-api-key: ck_your_key" \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0 ..." \
  -d '{
    "type": "custom",
    "name": "Purchase",
    "url": "https://yoursite.com/checkout/complete",
    "revenue_amount": 49.99,
    "revenue_currency": "USD",
    "meta_keys": ["plan", "interval"],
    "meta_values": ["pro", "annual"]
  }'

Privacy and processing

• Tracking parameters (gclid, fbclid, msclkid, etc.) are automatically stripped from stored URLs
• Query parameters are stripped from referrer URLs
• UTM parameters are extracted and stored separately from the page URL
• IP addresses are used for geolocation but never stored
• If your site has Do Not Track respect enabled, requests with DNT: 1 headers are excluded

Realtime API

Get the number of currently active visitors on your site.

curl https://clickport.io/api/realtime \
  -H "x-api-key: ck_your_key"

Response:

{
  "count": 7,
  "visitors": [
    {
      "session_id": 91823,
      "entry_page": "/",
      "exit_page": "/pricing",
      "pageviews": 3,
      "duration": 124,
      "source": "google",
      "country": "DE",
      "city": "Berlin",
      "device": "Desktop",
      "browser": "Chrome",
      "os": "macOS",
      "scroll": 72
    }
  ]
}

Returns up to 20 currently active visitors (active within the last 5 minutes). Each visitor includes their session details, current page, traffic source, location, and engagement data.

Goals API

Retrieve goal conversion data for your site.

curl "https://clickport.io/api/goals?start_date=2026-03-01&end_date=2026-03-31" \
  -H "x-api-key: ck_your_key"

Response:

{
  "goals": [
    {
      "id": 1,
      "name": "Contact Form",
      "type": "form",
      "visitors": 84,
      "submissions": 91
    },
    {
      "id": 2,
      "name": "Purchase",
      "type": "custom",
      "visitors": 37,
      "events": 42,
      "total_revenue": 1849.50
    }
  ]
}

Convenience endpoints

These GET endpoints return pre-formatted breakdowns for common dimensions. All accept start_date and end_date as query parameters.

• GET /api/pages - Top pages with visitors, pageviews, scroll depth, duration
• GET /api/sources - Traffic sources with visitors, bounce rate, engagement
• GET /api/referrers - Full referrer URLs with visitors and bounce rate
• GET /api/countries - Country breakdown with visitor counts
• GET /api/campaigns - Campaign data (campaign, source, medium)
• GET /api/utm-sources - UTM source breakdown
• GET /api/utm-mediums - UTM medium breakdown
• GET /api/utm-content - UTM content breakdown
• GET /api/utm-term - UTM term breakdown
• GET /api/entry-pages - Entry pages with session counts
• GET /api/exit-pages - Exit pages with session counts
• GET /api/tech?type=device - Device type breakdown
• GET /api/tech?type=browser - Browser breakdown
• GET /api/tech?type=os - Operating system breakdown

Example

curl "https://clickport.io/api/pages?start_date=2026-03-01&end_date=2026-03-31" \
  -H "x-api-key: ck_your_key"

Error responses

The API returns standard HTTP status codes:

• 200 - Success
• 401 - Invalid or missing API key
• 404 - Endpoint not found
• 500 - Server error

Error responses include a JSON body:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}