API Reference
Read your data and drive exclusions over REST
Every number in the dashboard is available over a REST API: scored sessions, source
breakdowns, the conversion-scoring view, efficacy metrics, and disputes. The API is on the
Pro plan. The base URL is
https://app.clicklens.io/api/v1,
responses are JSON, and the full machine-readable definition lives at the
OpenAPI document linked below.
Three credentials, three jobs
ClickLens uses three separate secrets. Mixing them up is the most common integration mistake, so check this table before you start.
| Credential | Looks like | Where it goes | What it does |
|---|---|---|---|
| API key | cl_live_… | Authorization: Bearer header on /api/v1 requests | Reads your dashboard data (sessions, sources, efficacy, conversions). Pro plan. Treat it like a password. |
| Site key | data-site | In the install snippet, and the Bearer token on /sessions/convert | Identifies which site a beacon or server-side conversion belongs to. Public by design, grants no dashboard access. |
| Beacon token | data-cl-token | In the install snippet only | Signs each beacon (HMAC-SHA256) so a forged or replayed beacon is flagged. Never sent to the REST API. |
The rest of this guide covers the API key. The site key and beacon token are documented in the install guide and conversion tracking.
Create an API key
Generate keys under Settings → API Keys in the dashboard. A key is shown in full exactly once, at creation; ClickLens stores only a hash, so a lost key cannot be recovered and must be replaced. An account holds up to five active keys at a time. Revoke a key from the same screen and it stops authenticating immediately.
Keys carry the cl_live_
prefix and authenticate as the account that created them, with the same site access. They
are created and revoked from the dashboard only, not over the API.
Make a request
Send the key as a bearer token. Most read endpoints take a
siteId query parameter
and an optional startDate/endDate range.
curl https://app.clicklens.io/api/v1/sessions?siteId=YOUR_SITE_ID \
-H "Authorization: Bearer cl_live_your_key_here"
A request without a valid key returns
401. A key whose account
is below the Pro plan returns
403 with the required
plan in the body. Requesting a site the account cannot access returns
403.
Rate limits
The authenticated API allows 60 requests per minute, counted per API key. The public beacon endpoint is limited separately to 100 requests per IP per minute, which the tracking tag stays well under on its own.
Over the limit, the API returns
429 with a JSON body:
{ "error": "Rate limit exceeded. Maximum 60 requests per 1 minutes." }.
Space out polling and cache responses where you can; the dashboard data behind these
endpoints updates on the order of seconds, not milliseconds.
Endpoint groups
The endpoints fall into these groups. The OpenAPI document has the exact parameters and response shape for each.
| Group | Endpoints | Use |
|---|---|---|
| Sites | GET/POST /sites, GET /sites/:id/tag | List and register sites, fetch a tag snippet. |
| Sessions | GET /sessions, GET /sessions/:id | List scored sessions with filters; read one session with all signals and flags. |
| Dashboard | GET /dashboard, GET /sources, GET /reports/waste | Aggregated KPIs, traffic-source breakdown, and the wasted-spend estimate. |
| Conversions | GET /conversions | The conversion-scoring view: graded verdicts, would-be write-back, per-platform sync health, holdout divergence. |
| Efficacy | GET /efficacy, GET /efficacy/flags | Confusion matrix with per-class precision, recall and F1, plus per-flag bot precision. |
| Disputes | GET/POST /disputes, PATCH/DELETE /disputes/:id, POST /disputes/batch | File, list and resolve verdict disputes; an accepted dispute becomes verified ground truth. |
| Exclusions | GET/POST/DELETE /exclusions, POST /exclusions/sync* | Manage exclusion rules and sync them to a connected ad platform. Sync is Growth plan or higher. |
| API keys | GET/POST /api-keys, DELETE /api-keys/:id | Create and revoke API keys. Dashboard (session) authentication only. |
The disputes and efficacy groups are explained end to end in disputes and efficacy; the conversions group in conversion protection; and exclusion sync, with its per-platform limits, in exclusions and platform sync.
Full reference
The complete, machine-readable definition is served as an OpenAPI 3.0 document. Import it into Postman, Insomnia, or a client generator.
https://app.clicklens.io/api/v1/docsIt covers every endpoint above, the public beacon and audit endpoints, the Stripe and CRM webhooks, and the cron jobs, each with its security scheme and response codes.