Analytics API

Query click events, page views, and aggregate analytics programmatically. Filter by date range, group by dimensions, and export data for your own dashboards and reporting pipelines.

Query clicks

Retrieve click analytics for your workspace. Results can be filtered by link, date range, and grouped by time interval or dimension (country, device, browser, referrer).

GET/api/v1/analytics/clicks

Query parameters

Parameter	Type	Required	Description
interval	string	No	Time bucket: `1h`, `1d`, `7d`, `30d`, `90d`. Default: `1d`
start	string	No	Start date in ISO 8601 format. Default: 30 days ago.
end	string	No	End date in ISO 8601 format. Default: now.
linkId	string	No	Filter clicks to a specific link ID
groupBy	string	No	Group by dimension: `day`, `country`, `device`, `browser`, `referrer`
limit	integer	No	Max results to return (default: 100, max: 1000)

Request — clicks grouped by day

curl "https://mask.pk/api/v1/analytics/clicks?groupBy=day&start=2026-03-01&end=2026-03-15" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    { "date": "2026-03-01", "clicks": 1423 },
    { "date": "2026-03-02", "clicks": 1891 },
    { "date": "2026-03-03", "clicks": 2104 },
    { "date": "2026-03-04", "clicks": 1756 },
    { "date": "2026-03-05", "clicks": 1982 }
  ],
  "total": 9156,
  "start": "2026-03-01T00:00:00Z",
  "end": "2026-03-15T23:59:59Z"
}

Request — clicks for a specific link grouped by country

curl "https://mask.pk/api/v1/analytics/clicks?linkId=lnk_abc123&groupBy=country&limit=5" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    { "country": "US", "clicks": 4521 },
    { "country": "GB", "clicks": 1893 },
    { "country": "CA", "clicks": 1204 },
    { "country": "IN", "clicks": 987 },
    { "country": "DE", "clicks": 654 }
  ],
  "total": 9259,
  "start": "2026-02-22T00:00:00Z",
  "end": "2026-03-24T23:59:59Z"
}

Query views

Retrieve view analytics for bio pages. Supports the same filtering and grouping parameters as the clicks endpoint.

GET/api/v1/analytics/views

Query parameters

Parameter	Type	Required	Description
interval	string	No	Time bucket: `1h`, `1d`, `7d`, `30d`
start	string	No	Start date in ISO 8601 format
end	string	No	End date in ISO 8601 format
pageId	string	No	Filter views to a specific bio page ID
groupBy	string	No	Group by dimension: `day`, `referrer`, `country`, `device`

Request — page views grouped by day

curl "https://mask.pk/api/v1/analytics/views?pageId=bp_abc123&groupBy=day&start=2026-03-01" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    { "date": "2026-03-01", "views": 312 },
    { "date": "2026-03-02", "views": 458 },
    { "date": "2026-03-03", "views": 391 }
  ],
  "total": 1161,
  "start": "2026-03-01T00:00:00Z",
  "end": "2026-03-24T23:59:59Z"
}

Request — views grouped by referrer

curl "https://mask.pk/api/v1/analytics/views?groupBy=referrer&limit=5" \
  -H "Authorization: Bearer mk_live_abc123def456"

Response

{
  "data": [
    { "referrer": "instagram.com", "views": 2841 },
    { "referrer": "twitter.com", "views": 1923 },
    { "referrer": "direct", "views": 1456 },
    { "referrer": "tiktok.com", "views": 892 },
    { "referrer": "linkedin.com", "views": 534 }
  ],
  "total": 7646,
  "start": "2026-02-22T00:00:00Z",
  "end": "2026-03-24T23:59:59Z"
}

Date ranges

Both start and end accept ISO 8601 date strings. If only start is provided, end defaults to the current time. If neither is provided, the default range is the last 30 days. The maximum queryable range is 365 days.

Custom date range

curl "https://mask.pk/api/v1/analytics/clicks?start=2026-01-01T00:00:00Z&end=2026-03-31T23:59:59Z&groupBy=day" \
  -H "Authorization: Bearer mk_live_abc123def456"

Rate limiting

Analytics endpoints share the same 1,000 requests/minute rate limit as all other API endpoints. For high-volume reporting, use larger intervals (e.g. 7d or 30d) to reduce the number of requests needed. Analytics data is available within 60 seconds of the underlying event occurring.