How to use the ClickPatrol Public API

Use the ClickPatrol Public API for read-only access to your click and fraud data.

Generate the key from the API Integrations page in your dashboard. Do not use the API Exclusion token for this: that token scores a single IP from your own systems. See How to use ClickPatrol API tokens for that flow.

Two endpoints are currently available through the Public API:

GET /api/v1/clicks
GET /api/v1/report

An API key applies to one website. You do not need to include an account identifier in the request.

Step 1: Open API Integrations#

Sign in to your ClickPatrol dashboard.

Click API Integrations in the sidebar.

This page contains the available endpoints, the API key section and the API documentation.

Step 2: Note the base URL#

Every Public API request starts with this base URL:

https://dashboard.clickpatrol.com/api/v1

Add the endpoint path to the base URL.

URL for click data:

https://dashboard.clickpatrol.com/api/v1/clicks

URL for monthly report data:

https://dashboard.clickpatrol.com/api/v1/report

Step 3: Generate your API key#

Click Generate API Key.

Authenticate every request with the generated API key.

Pass the key in the X-API-Key header.

Example header:

--header 'X-API-Key: YOUR_API_KEY'

Endpoint 1: Get click data#

Use this endpoint:

GET /api/v1/clicks

This endpoint returns clicks for the website linked to the API key, with the newest click first.

Full URL:

https://dashboard.clickpatrol.com/api/v1/clicks

Make a request#

curl --request GET \
  --url 'https://dashboard.clickpatrol.com/api/v1/clicks' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Replace YOUR_API_KEY with the key you generated in the dashboard.

Filter click data#

Add query parameters to narrow the results.

ip

Returns clicks that match an exact IP address.

Example:

https://dashboard.clickpatrol.com/api/v1/clicks?ip=203.0.113.42

user_agent

Returns clicks whose User Agent contains the text you provide.

Matching is case-insensitive.

You can enter a fragment such as Android or Chrome/139.

Maximum length: 1024 characters.

start_date

Returns clicks on or after this date.

Use:

YYYY-MM-DD

This date is inclusive. It represents a full calendar day in the Google sub-account timezone.

end_date

Returns clicks on or before this date.

Use:

YYYY-MM-DD

This date is inclusive. It represents a full calendar day in the Google sub-account timezone.

The end_date cannot be earlier than the start_date.

page

Sets the page number.

The first page is 1.

per_page

Sets how many records each page returns.

Each page can contain between 1 and 1,000 records.

Only the 1,000 most recent matching clicks are available.

If a page extends beyond the 1,000-record limit, the response includes only records that fall within that limit.

When no clicks match a filter, the API returns an empty clicks array.

What the response contains#

A successful response can include these click fields:

• Timestamp
• IP address
• GCLID
• Source
• Campaign ID
• Campaign name
• Ad group ID
• Ad group name
• Keyword
• Device
• Browser
• Operating system
• Country
• Traffic (how ClickPatrol classifies the click)
• VPN status
• Proxy status

Pagination details in the response include:

• Current page
• First page URL
• Previous page URL
• Next page URL
• Last page URL
• Last page
• Records per page
• Total entries

Endpoint 2: Get the monthly savings report#

Use this endpoint:

GET /api/v1/report

This endpoint groups click fraud savings data by calendar month.

Full URL:

https://dashboard.clickpatrol.com/api/v1/report

Make a request#

curl --request GET \
  --url 'https://dashboard.clickpatrol.com/api/v1/report' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Accept: application/json'

Report query parameters#

page

Sets the page number.

The first page is 1.

per_page

Sets the number of months returned on each page.

Each page can return between 1 and 100 months.

expression

Sets the column used to sort the report.

Choose from these values:

• month
• total_clicks
• safe_clicks
• suspicious_clicks
• total_click_saved
• avg_ecpc_percentage
• total_amount_saved
• suspicious_clicks_percentage

Use the total_click_saved sort key for the Total clicks saved column in the response.

The default is:

month

order

Sets the sorting direction.

Choose one of these values:

• asc
• desc

The default is:

desc

Example:

https://dashboard.clickpatrol.com/api/v1/report?expression=total_amount_saved&order=desc

What the report response contains#

The monthly report can include these fields:

• Month
• Total clicks
• Safe clicks
• Suspicious clicks
• Total clicks saved
• Total amount saved
• Suspicious clicks percentage
• Average eCPC percentage
• Total cost
• Total cost percentage
• Future saving
• Future saving percentage

Figures in the response are display-formatted.

A dot separates thousands.

A comma marks decimal places.

Each monetary value includes the currency symbol of the sub-account.

Pagination details are also part of the response.

Successful responses#

A successful request returns response code 200.

It contains:

• status
• message
• data

On the clicks endpoint, data holds the click records.

On the report endpoint, data holds the monthly report data.

Other response codes#

• 401 Authentication fails when the X-API-Key header is missing, invalid, or revoked.
• 422 The API rejected one or more query parameters. data.errors maps each parameter to its messages.
• 429 Your request budget has been used up. This budget is set at account level rather than per API key or website, so every website you own and every Public API endpoint uses the same allowance. Its rolling 24-hour window starts with the first request in that window; it does not reset at midnight. The Retry-After header and data.retry_after_seconds show the same number of seconds.
• 500 The request could not be processed because of an unexpected error. Try again later.