ClickGuardian API

Send your key in the Authorization header on every request:

Authorization: Bearer cg_live_Tz41mQe8hV2kPn7RbX0cLw9sYd3FaJ6u

• Keys start cg_live_ and are 40 characters long.
• Send requests to app.clickguardian.ai, whichever address you use to sign in to the app.
• A request without a valid key gets 401 invalid_key.
• Partner agencies can read every client with one agency key: see Agency keys.

What a key can do

Every key is Read only: it can read reports and the status of your projects, and nothing else. (Keys that can also block and unblock visitors are coming soon.)

Which projects a key can see

When you create a key you choose:

• All projects. Every project on your account, including ones you add later.
• Selected projects. Only the projects you tick. Projects you add later are not included.

A key can never see another account's projects. If you ask a key for a project it can't see, the answer is 404 not_found, the same answer as for a project that doesn't exist. You can't change a key's projects after you create it: replace the key instead.

Expiry

When you create a key, choose when it expires: after 30 days, 90 days or 1 year, or never. A week before a key expires, we email the account's owners, and the person who made the key if they're still an owner or admin. An expired key gets 401 invalid_key with the message "This API key has expired".

Revoking and replacing

• Revoke a key from its menu in the API keys card. Anything using it stops working within a minute.
• Replace with a new key opens the create form, filled in with the old key's name and projects. Choose an expiry and create the new key. The old key stops working when you click Done on the dialog that shows the new one, so put the new key in place first.

A key is also revoked automatically when every project it could read has been deleted. When someone is removed from your account, the person removing them can choose to revoke the keys they made.

Keeping keys safe

• Treat a key like a password. Anyone who has it can read your figures.
• Use keys on a server, in a script or in a tool such as Zapier. Don't put a key in a web page, a mobile app or a public code repository. (The API doesn't accept requests from web pages.)
• Give each tool its own key, so you can revoke one without breaking the others.
• If a key might have leaked, revoke it and make a new one.

After you create a key, we only ever show its first few characters again. We store a one-way fingerprint of the key rather than the key itself, so nobody, including us, can show it to you again.

Projects

Each website you protect is a project in ClickGuardian. Each project has an id like proj_8kq2m4x7r1ab. List yours with GET /projects.

Most endpoints take an optional project_id:

• Without it, you get every project the key can see, added together, the same as "All projects" in the app.
• With it, you get that one project.

Dates

• Dates are YYYY-MM-DD, and both ends are included: start_date=2026-09-01&end_date=2026-09-28 is 28 days.
• Days run from midnight to midnight UTC.
• Timestamps in responses are ISO 8601, in UTC.

Your plan's history

Each plan keeps a set amount of history: 6 months on Professional, 12 months on Growth, 24 months on Scale and Custom.

If you ask for dates before that, we return what your plan keeps and set meta.clamped to true. We do the same if end_date is after today: the range stops at today. If the whole range is older than your plan keeps, data is empty, meta.start_date and meta.end_date are null, and meta.clamped is true.

The response shape

Report endpoints return:

{
  "data": [ ... ],
  "meta": {
    "start_date": "2026-09-01",
    "end_date": "2026-09-28",
    "retention_months": 12,
    "clamped": false
  }
}

• meta.start_date and meta.end_date are the dates actually used, after your plan's history is applied.
• meta.retention_months is how much history your plan keeps.
• meta.clamped is true when we shortened the range you asked for.

Caching

We keep a copy of each answer for up to 10 minutes (project status: 1 minute). Asking the same question again within that time gets the same answer, quickly. New data arrives in ClickGuardian every few minutes, so this rarely matters, but don't expect a figure to change from one second to the next.

Field stability

Within v1 we only ever add fields and options. We never rename or remove a field, or change what it means. Build your integration to ignore fields it doesn't know.

Missing values

A figure is null when we can't work it out honestly, rather than showing a made-up number:

• Money figures are null when we don't know your cost per click. Connect your ad account, or set your typical cost per click in Settings → Your business.
• Percentages and scores are null when there's nothing to work them out from (for example, no ad clicks that day).
• "Previous period" figures are null when the whole previous period is older than your plan keeps. If only part of it is, they cover the part your plan keeps.

Checks your key works. Returns your account.

curl https://app.clickguardian.ai/api/v1/ping \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const res = await fetch('https://app.clickguardian.ai/api/v1/ping', {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/ping",
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{ "org_id": "6f1c2a90-4b7e-4c1d-9a55-2e8f0b3d7c11", "org_name": "Avroom Ltd", "plan": "growth" }

The projects your key can see. Returns a list (not wrapped in data).

curl https://app.clickguardian.ai/api/v1/projects \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const res = await fetch('https://app.clickguardian.ai/api/v1/projects', {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/projects",
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

[
  { "project_id": "proj_8kq2m4x7r1ab", "name": "Avroom", "domain": "avroom.co.uk" },
  { "project_id": "proj_3fz9w2p6c0de", "name": "Brightside Dental", "domain": "brightsidedental.co.uk" }
]

The status of every project your key can see: is the tracking code installed, are your ad accounts connected and syncing, how much is being blocked, and anything that needs your attention.

curl https://app.clickguardian.ai/api/v1/status \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const res = await fetch('https://app.clickguardian.ai/api/v1/status', {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/status",
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    {
      "project_id": "proj_8kq2m4x7r1ab",
      "name": "Avroom",
      "domain": "avroom.co.uk",
      "state": "7% of ad clicks blocked",
      "tone": "ok",
      "needs_attention": false,
      "issues": [],
      "tracking": {
        "installed": true,
        "evidence": "data",
        "old_tracker_only": false,
        "has_received_data": true,
        "receiving_data": true,
        "first_event_at": "2026-03-30T00:00:00.000Z",
        "last_event_at": "2026-09-28T16:00:00.000Z"
      },
      "ad_accounts": {
        "google_ads": {
          "connected": true,
          "account_id": "1234567890",
          "account_name": "Avroom Ads",
          "sync": "completed",
          "last_synced_at": "2026-09-28T06:00:16.561Z",
          "problem": null,
          "reconnect_needed": false
        },
        "microsoft_ads": null
      },
      "traffic": {
        "start_date": "2026-09-01",
        "end_date": "2026-09-28",
        "paid_clicks": 5890,
        "blocked_clicks": 412,
        "blocked_pct_of_ad_clicks": 6.99
      },
      "checks": {
        "overall": "healthy",
        "checked_at": "2026-09-28T07:01:12.000Z",
        "items": [
          { "check": "recent_data_seen", "label": "Recent visits received", "status": "pass", "checked_at": "2026-09-28T07:01:12.000Z" },
          { "check": "tracking_installed", "label": "Tracking code found on the homepage", "status": "pass", "checked_at": "2026-09-28T07:01:12.000Z" }
        ]
      }
    }
  ],
  "meta": {
    "start_date": "2026-09-01",
    "end_date": "2026-09-28",
    "retention_months": 12,
    "clamped": false,
    "websites": 1,
    "needing_attention": 0
  }
}

The same as /status, for one project. Takes the same parameters. data is a list with one item (or none, if you ask for needs_attention=true and the project is fine).

curl https://app.clickguardian.ai/api/v1/projects/proj_8kq2m4x7r1ab/status \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const res = await fetch('https://app.clickguardian.ai/api/v1/projects/proj_8kq2m4x7r1ab/status', {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/projects/proj_8kq2m4x7r1ab/status",
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

The headline figures from the Overview screen, for a date range, with the same-length period before it for comparison.

curl "https://app.clickguardian.ai/api/v1/reporting/overview?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/overview')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/overview",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    {
      "start_date": "2026-09-01",
      "end_date": "2026-09-28",
      "previous_start_date": "2026-08-04",
      "previous_end_date": "2026-08-31",
      "clicks_checked": 18420,
      "paid_clicks": 6312,
      "organic_clicks": 12108,
      "genuine_clicks": 14736,
      "suspicious_clicks": 2210,
      "highly_suspicious_clicks": 1474,
      "genuine_pct": 80,
      "suspicious_pct": 12,
      "highly_suspicious_pct": 8,
      "quality_score": 74,
      "blocked_clicks": 412,
      "blocked_clicks_previous": 389,
      "spend_stopped": 1174.2,
      "spend_stopped_previous": 1108.65,
      "spend_flagged": 273.6,
      "currency": "GBP",
      "cost_per_click": 2.85,
      "cost_per_click_source": "campaigns",
      "fake_leads": 14,
      "fake_leads_previous": 11
    }
  ],
  "meta": { "start_date": "2026-09-01", "end_date": "2026-09-28", "retention_months": 12, "clamped": false }
}

The Overview chart: one row per day. Takes start_date, end_date and project_id, as overview.

curl "https://app.clickguardian.ai/api/v1/reporting/overview_daily?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/overview_daily')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/overview_daily",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "date": "2026-09-01", "clicks_checked": 652, "paid_clicks": 221, "organic_clicks": 431, "genuine_clicks": 529, "suspicious_clicks": 74, "highly_suspicious_clicks": 49, "blocked_clicks": 15, "blocked_pct_of_ad_clicks": 6.47, "spend_stopped": 42.75, "currency": "GBP" },
    { "date": "2026-09-02", "clicks_checked": 698, "paid_clicks": 240, "organic_clicks": 458, "genuine_clicks": 561, "suspicious_clicks": 81, "highly_suspicious_clicks": 56, "blocked_clicks": 17, "blocked_pct_of_ad_clicks": 6.77, "spend_stopped": 48.45, "currency": "GBP" }
  ],
  "meta": { "start_date": "2026-09-01", "end_date": "2026-09-28", "retention_months": 12, "clamped": false }
}

Your campaigns, as the Campaigns screen shows them: figures from your ad platform alongside the clicks we tracked and flagged. You get every campaign, up to 5,000, unless you ask for a page with limit.

curl "https://app.clickguardian.ai/api/v1/reporting/campaigns?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/campaigns')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/campaigns",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    {
      "campaign_id": "21458710233",
      "campaign_name": "Emergency plumber - Search",
      "ad_platform": "google",
      "campaign_status": "ENABLED",
      "channel_type": "SEARCH",
      "currency": "GBP",
      "impressions": 18240,
      "clicks": 1406,
      "spend": 3982.1,
      "conversions": 96,
      "all_conversions": 104,
      "ctr_pct": 7.71,
      "avg_cpc": 2.83,
      "tracked_clicks": 1512,
      "paid_clicks": 1389,
      "suspicious_clicks": 171,
      "suspicious_pct": 12.31,
      "blocked_clicks": 98,
      "wasted_spend": 277.56,
      "health": "Worth watching"
    }
  ],
  "meta": {
    "start_date": "2026-09-01",
    "end_date": "2026-09-28",
    "retention_months": 12,
    "clamped": false,
    "page": { "limit": 5000, "total_rows": 1, "next_cursor": null },
    "totals": {
      "impressions": 18240,
      "clicks": 1406,
      "tracked_clicks": 1512,
      "paid_clicks": 1389,
      "suspicious_clicks": 171,
      "blocked_clicks": 98,
      "spend": [{ "currency": "GBP", "amount": 3982.1 }],
      "wasted_spend": [{ "currency": "GBP", "amount": 277.56 }]
    }
  }
}

Campaigns come most suspicious clicks first, then highest spend. meta adds:

Tracked and suspicious clicks per campaign per day: the small charts on the Campaigns screen.

curl "https://app.clickguardian.ai/api/v1/reporting/campaigns_daily?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/campaigns_daily')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/campaigns_daily",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "date": "2026-09-01", "campaign_id": "21458710233", "campaign_name": "Emergency plumber - Search", "tracked_clicks": 54, "suspicious_clicks": 6 },
    { "date": "2026-09-02", "campaign_id": "21458710233", "campaign_name": "Emergency plumber - Search", "tracked_clicks": 61, "suspicious_clicks": 9 }
  ],
  "meta": { "start_date": "2026-09-01", "end_date": "2026-09-28", "retention_months": 12, "clamped": false }
}

Very large accounts asking for a long range may get 400 bad_params: "Too many campaign rows between … for one request; ask for fewer days, or narrow the request with campaign_ids".

Why we blocked ad clicks, per day, grouped as on the Blocked threats screen. Each blocked click is counted once, under the check that decided it. Takes start_date, end_date and project_id.

curl "https://app.clickguardian.ai/api/v1/reporting/rules_daily?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/rules_daily')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/rules_daily",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "date": "2026-09-07", "rule_id": "datacenter_ip_detection", "reason": "Coming from a data centre, not a home or office", "reason_group_id": "vpn", "reason_group": "Hiding where they were", "blocked_clicks": 6 },
    { "date": "2026-09-07", "rule_id": "headless_automation_detection", "reason": "Browser running without a screen", "reason_group_id": "bots", "reason_group": "Automated software, not people", "blocked_clicks": 2 }
  ],
  "meta": { "start_date": "2026-09-01", "end_date": "2026-09-28", "retention_months": 12, "clamped": false }
}

Blocked ad clicks by country. The countries add up to overview.blocked_clicks. Takes start_date, end_date and project_id.

curl "https://app.clickguardian.ai/api/v1/reporting/geo?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/geo')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/geo",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "country_code": "GB", "blocked_clicks": 288 },
    { "country_code": "US", "blocked_clicks": 61 },
    { "country_code": "", "blocked_clicks": 9 }
  ],
  "meta": { "start_date": "2026-09-01", "end_date": "2026-09-28", "retention_months": 12, "clamped": false }
}

The Campaigns screen's drill-down: suspicious clicks by ad group, by ad and by keyword. These lists can be long, so they come in pages.

These need tracking parameters on your ad clicks. For Google Ads, switch on Enriched campaign tracking in Settings → Connections (it appears once Google Ads is connected).

Until you choose a campaign (or, for ads, a campaign or ad group), only ad groups and ads with clicks are listed, as in the app. Keywords are always listed only when they have clicks.

curl "https://app.clickguardian.ai/api/v1/reporting/keywords?start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const url = new URL('https://app.clickguardian.ai/api/v1/reporting/keywords')
url.search = new URLSearchParams({ start_date: '2026-09-01', end_date: '2026-09-28' })

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/keywords",
    params={"start_date": "2026-09-01", "end_date": "2026-09-28"},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "keyword": "emergency plumber near me", "match_type": "p", "ad_platform": "google", "tracked_clicks": 412, "paid_clicks": 398, "suspicious_clicks": 61, "suspicious_pct": 14.81, "blocked_clicks": 37, "health": "Worth watching" }
  ],
  "meta": {
    "start_date": "2026-09-01",
    "end_date": "2026-09-28",
    "retention_months": 12,
    "clamped": false,
    "page": { "limit": 100, "total_rows": 238, "next_cursor": "eyJvIjoxMDB9" },
    "totals": { "tracked_clicks": 5120, "paid_clicks": 4876, "suspicious_clicks": 611, "blocked_clicks": 402 },
    "notice": null
  }
}

Fields:

meta adds:

If you run ClickGuardian for your clients as a partner agency, one agency key reads any of your clients. You don't need a key inside each client.

Make an agency key

In your agency area, open API keys. Give the key a name, choose when it expires (after 30 days, 90 days or 1 year, or never) and choose Create key. Agency owners and admins can make them. We only show the full key once, so keep it somewhere safe.

• Anyone holding an agency key can read every one of your clients. Treat it like a password.
• Agency keys are switched on agency by agency. If you don't see API keys in your agency area, ask us to switch them on.
• Like every key, an agency key is Read only.

Name the client on every call

An agency key reads nothing until you say which client. Send client_id on every request:

curl "https://app.clickguardian.ai/api/v1/reporting/overview?client_id=8d3f0c2a-5b71-4e9a-a0c4-2f6e9b1d7a35&start_date=2026-09-01&end_date=2026-09-28" \
  -H "Authorization: Bearer cg_live_YOUR_AGENCY_KEY"

• Get each client's id from GET /clients.
• Every endpoint above takes it: /projects, /status, /projects/{project_id}/status and every /reporting/ endpoint. You get exactly what that client's own key would get, for every website the client has.
• Without client_id you get 400 bad_params. A client that isn't yours, or doesn't exist, gets 404 not_found, the same answer either way.
• Each client keeps the history its own account keeps. meta.retention_months says how much.
• Send requests to app.clickguardian.ai, not your own domain.

GET /ping with an agency key answers with your agency rather than an account:

{ "key_kind": "agency", "tenant_id": "42", "tenant_name": "Northpoint Digital", "client_count": 120 }

Your clients, oldest first, with the client_id every other call needs. Only agency keys can list clients: an account's own key gets 403 forbidden.

curl https://app.clickguardian.ai/api/v1/clients \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

const res = await fetch('https://app.clickguardian.ai/api/v1/clients', {
  headers: { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` },
})
console.log(await res.json())

import os, requests

res = requests.get(
    "https://app.clickguardian.ai/api/v1/clients",
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
print(res.json())

{
  "data": [
    { "client_id": "8d3f0c2a-5b71-4e9a-a0c4-2f6e9b1d7a35", "client_name": "Brightside Dental", "api_access": true, "created_at": "2026-11-03T11:17:52.596837+00:00" },
    { "client_id": "1b7e4d90-3c2f-4a6b-8e15-9f0a2c6d4b71", "client_name": "Avroom", "api_access": true, "created_at": "2026-11-04T09:41:07.112093+00:00" }
  ],
  "meta": { "total": 120, "limit": 100, "next_cursor": "eyJvIjoxMDB9" }
}

Status across all your clients

GET /status with an agency key and no client_id reads your clients a page at a time and lists every website of each one. Every row carries client_id and client_name. It takes start_date, end_date and needs_attention, as GET /status does, and:

meta has start_date, end_date, clamped, websites and needing_attention, as for one client, plus:

A page counts as one request, plus one for each client it reads.

Agency key limits

• Agency key requests don't count against a client's own daily request limit.
• New report queries cost the same units as for any key (see Limits). An answer from our 10-minute copy costs no units, though it still counts as a request.
• Days reset at midnight UTC.

Agency keys and AI assistants

Agency keys work with the REST API only for now. The MCP server answers an agency key with 403.

• Days reset at midnight UTC.
• New report queries. A request we answer from our 10-minute copy costs nothing here (it still counts as a request). A request that needs fresh figures costs units: 5 for overview, overview_daily, geo and campaigns_daily; 1 for everything else. That's about 12 fresh overview requests a minute, or 60 of the others.
• Keys. Revoked and expired keys don't count towards the 10.
• Per connection. Each IP address can make up to 300 requests a minute, and can try up to 20 keys a minute that we don't recognise.
• Page sizes. campaigns: every campaign by default, or up to 5,000 per page. adgroups, ads, keywords: up to 500 rows per page.
• Agency keys have limits of their own: see Agency keys.

When you go over a limit, you get 429 rate_limited with a Retry-After header saying how many seconds to wait. Wait that long, then try again. Asking for the same thing again straight away won't help. (Going over the 300-a-minute connection limit also gets a 429, but that response may not be JSON or include Retry-After: wait a minute.)

Errors look like this, with a matching HTTP status:

{ "error": { "code": "bad_params", "message": "start_date and end_date (YYYY-MM-DD) are required" } }

Retry 429, 502 and 500, waiting longer each time. Don't retry 400, 401, 403 or 404 without changing something.

AI assistants such as Claude Code, Cursor and your own agents can ask ClickGuardian for your figures through the Model Context Protocol (MCP), using an API key you already have. Every tool runs the same code as the endpoints above, so an assistant's numbers match the API and the app.

• Read only. Like the API, the MCP server can read your figures and nothing else.
• Same keys, same limits. It uses your API keys, sees the same projects, and counts against the same limits.
• Same plans. Included with Professional, Growth, Scale and Custom.
• Not agency keys, yet. The MCP server works with a key made inside an account. An agency key gets 403.

Connect

Server address:

https://mcp.clickguardian.ai/mcp

Add it to your assistant with your key in the Authorization header:

claude mcp add --transport http clickguardian https://mcp.clickguardian.ai/mcp --header "Authorization: Bearer cg_live_YOUR_KEY"

{
  "mcpServers": {
    "clickguardian": {
      "url": "https://mcp.clickguardian.ai/mcp",
      "headers": { "Authorization": "Bearer cg_live_YOUR_KEY" }
    }
  }
}

Then ask a question, for example "How many ad clicks did we block last week, and why?"

How it works

• Address. https://mcp.clickguardian.ai/mcp, also at https://app.clickguardian.ai/api/mcp. Streamable HTTP, POST only. Works with clients on the 2025 protocol and the 2026-07-28 revision.
• Projects. A key sees the same projects through MCP as through the API: all of them, or the ones you chose. Name a project by its id or its domain, for example avroom.co.uk.
• Limits. Each tool call counts as one API request against your key and account limits. Connecting and listing tools cost nothing.
• Partner accounts. The server only answers at the addresses above, not on a partner's own domain.

Tools

Ten tools, all read only. Each one is an API endpoint, shaped for an assistant.

get_project_status needs a key with the projects:read scope. Keys made before project status existed don't have it: make a new key.

Inputs

Periods are worked out in UTC days and include today, as the app's date picker does. Other inputs, such as ad_platform, campaign_ids, sort and cursor, are the API's own parameters.

What an answer looks like

Each answer has two parts: a one-paragraph summary made only of numbers, dates, project ids and our own words, and the API's own data and meta. Campaign, ad group, ad and keyword names appear only in the data, never in the summary.

tools/call get_overview { "project": "avroom.co.uk", "start_date": "2026-10-01", "end_date": "2026-10-07" }

{
  "data": [ ... the overview row ... ],
  "meta": {
    "start_date": "2026-10-01",
    "end_date": "2026-10-07",
    "retention_months": 6,
    "clamped": false,
    "period": "custom",
    "summary": "1 to 7 Oct 2026, website proj_8kq2m4x7r1ab: ..."
  }
}

The summary is in meta too, because some assistants, Claude Code included, only show the model the data part of an answer.

Prompts

Ready-made prompts your assistant can offer:

• fraud_report A client-ready summary of what was blocked and saved over a period, starting from protection status.
• investigate_spike Whether a jump on a given day was an attack, a change in traffic or a tracking problem.
• check_setup What is and isn't working, in plain English, and what to fix first.

MCP errors

Only sign-in problems come back as HTTP errors, so your assistant knows to ask you to reconnect. Everything else comes back as a tool answer marked as an error, which the assistant can explain.

Yesterday's figures every morning

import os, datetime, requests

yesterday = (datetime.datetime.now(datetime.timezone.utc).date() - datetime.timedelta(days=1)).isoformat()
res = requests.get(
    "https://app.clickguardian.ai/api/v1/reporting/overview",
    params={"start_date": yesterday, "end_date": yesterday},
    headers={"Authorization": f"Bearer {os.environ['CLICKGUARDIAN_API_KEY']}"},
)
row = res.json()["data"][0]
print(f"{row['blocked_clicks']} ad clicks blocked, {row['currency']} {row['spend_stopped']} stopped")

Every keyword, all pages

const base = 'https://app.clickguardian.ai/api/v1/reporting/keywords'
const headers = { Authorization: `Bearer ${process.env.CLICKGUARDIAN_API_KEY}` }
let cursor = null
const rows = []
do {
  const url = new URL(base)
  url.search = new URLSearchParams({
    start_date: '2026-09-01',
    end_date: '2026-09-28',
    limit: '500',
    ...(cursor ? { cursor } : {}),
  })
  const body = await (await fetch(url, { headers })).json()
  rows.push(...body.data)
  cursor = body.meta.page.next_cursor
} while (cursor)

In Zapier

Use Webhooks by Zapier → GET. Set the URL to an endpoint, for example https://app.clickguardian.ai/api/v1/reporting/overview, add start_date and end_date as query string parameters, and add a header Authorization with the value Bearer cg_live_YOUR_KEY.

Which projects need attention

curl "https://app.clickguardian.ai/api/v1/status?needs_attention=true" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"