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. Keys created in Settings → API Keys carry read and tracker permissions, allowing you to query data and send events. Connector keys created in Settings → Integrations → AI Agents carry the agent-visits scope instead and work only with the agent-visits endpoint below.

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

Agent Visits API

Reports server-side requests so Clickport can identify and verify AI agents reading your site. This is the endpoint behind the AI Agents connectors; use it directly from any backend, edge function, or log pipeline.

Send newline-delimited JSON, one object per request your server saw, authenticated with a connector key in the Authorization header:

curl -X POST https://clickport.io/api/agent-visits \
  -H "Authorization: Bearer ck_your_connector_key" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary $'{"ts":"2026-07-13T09:00:00Z","path":"/blog/post","method":"GET","status":200,"duration_ms":42,"headers":{"User-Agent":"Mozilla/5.0 (compatible; GPTBot/1.2)","Remote-Addr":"203.0.113.7"},"connector":"rest"}\n'

Line fields

• ts - ISO 8601 timestamp of the request. Timestamps older than 35 days or in the future are clamped to arrival time.
• path - request path. Required. Query strings are stripped server-side.
• method - HTTP method.
• status - response status code.
• duration_ms - response time in milliseconds.
• headers - object with the original request's headers. Required. Include User-Agent and the requester's address as Remote-Addr (or X-Forwarded-For); without an address, hits verify as unverifiable.
• connector - rest, or one of the built-in connector identifiers.

Behavior and limits

• Send every content request: human hits are discarded server-side, agents are classified and verified against each operator's published IP ranges. The requester's address is used for that check and then discarded; it is never stored.
• Up to 5,000 lines per request, 5 MB body, Content-Encoding: gzip supported. A malformed line is skipped without failing the batch.
• Responds 204 No Content on success, with the accepted row count in the x-agent-visits-accepted response header.
• Agent visits never count as pageviews and do not consume your plan's quota.

Realtime API

Get the number of currently active visitors on your site, the same data behind the dashboard's realtime view.

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. /api/pages returns the top pages by pageviews and also accepts limit (default 100, max 1,000) and offset for paging. Its avg_duration is the engaged active time on each page, in seconds. Numeric fields are returned as JSON numbers.

• 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
• 403 - The API key is not permitted to use this endpoint. Keys work on the endpoints documented on this page: dashboard features require logging in to the dashboard.
• 404 - Endpoint not found
• 500 - Server error

Error responses include a JSON body:

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