REST API
Read your clicks and manage your exclusion list from your own code, and send server hits and conversions from your own integrations.
Overview#
The API has two parts. The REST API reads clicks and manages exclusions. The ingest endpoints are what the tag, the plugins and the Next.js package call; you only call them yourself if you are building your own integration.
| Endpoint | Key | Plans |
|---|---|---|
GET /clicks | Secret | Pro, Agency, and AppSumo Studio tier and up |
GET /exclusions | Secret | Pro, Agency, and AppSumo Studio tier and up |
POST /exclusions | Secret | Pro, Agency, and AppSumo Studio tier and up |
DELETE /exclusions/{id} | Secret | Pro, Agency, and AppSumo Studio tier and up |
POST /collect | Public | All plans |
POST /hit | Secret | All plans |
POST /conversion | Secret | All plans |
Base URL:
https://spurn.io/api/v1
Requests and responses are JSON over HTTPS.
Authentication#
Keys belong to a site. A key only ever reads and writes the data of the site it belongs to, and there is no key that spans sites.
Send the secret key as a bearer token:
GET /api/v1/clicks HTTP/1.1
Host: spurn.io
Authorization: Bearer sp_sec_XXXXXXXX
Create and revoke keys in Sites, then your site, then the Keys tab. Spurn shows a secret key once, when you create it, and stores only a hash of it; the dashboard lists the first characters so you can tell keys apart. If a key leaks, revoke it and create a new one.
A secret key belongs on a server. Never put it in a page, an app bundle or a public repository. The public key (sp_pub_XXXXXXXX) is the one that goes in pages, and it can only report landings, engagement and conversions through /collect.
Errors#
| Status | Meaning |
|---|---|
400 | The body or a parameter is malformed: invalid JSON, a CIDR that does not parse, an unknown verdict or platform value, a date that does not parse. |
401 | The key is missing, unknown or revoked, or it is the wrong kind of key for the endpoint. |
403 | The key is valid but your plan does not include the REST API. |
404 | No such resource for this key's site, for example an exclusion id from another site. |
429 | Too many requests. Wait for the number of seconds in the Retry-After header, then retry. |
Example error body. The field shown is an example:
{ "error": "Unknown verdict \"bad\". Use valid, suspicious, invalid or pending." }
Rate limits#
Requests are rate limited. When you go over, Spurn answers 429 Too Many Requests with a Retry-After header giving the seconds to wait. Back off for at least that long before you retry.
Pagination#
GET /clicks returns results a page at a time. Each response carries a cursor for the next page. Pass it back as the cursor parameter, with the same filters, to get the next page. When there is no next cursor, you have everything.
Clicks#
GET /clicks#
Lists paid clicks for the key's site.
| Parameter | Description |
|---|---|
from | Start of the range, as an ISO 8601 date or date-time. |
to | End of the range, as an ISO 8601 date or date-time. |
verdict | valid, suspicious, invalid or pending. |
platform | google, microsoft, meta, tiktok, linkedin, x, pinterest, snapchat, reddit or other. |
cursor | The cursor from the previous page. |
curl "https://spurn.io/api/v1/clicks?from=2026-11-01&to=2026-11-14&verdict=invalid&platform=google" \
-H "Authorization: Bearer sp_sec_XXXXXXXX"
Example response. The field names and values below are examples, not the full schema:
{
"data": [
{
"id": "cm3k2x9q80001",
"createdAt": "2026-11-14T09:12:44.120Z",
"platform": "google",
"clickId": "Cj0KCQiAexample",
"clickIdType": "gclid",
"ip": "203.0.113.7",
"country": "US",
"networkType": "datacenter",
"asOrg": "Example Hosting Ltd",
"deviceType": "desktop",
"landingUrl": "https://shop.example.com/products/linen-sheets?gclid=Cj0KCQiAexample",
"campaignId": "21012345678",
"keyword": "linen sheets",
"verdict": "invalid",
"score": 81,
"reasons": ["DATACENTER", "NO_ENGAGEMENT"],
"analyzed": true,
"finalized": true,
"seenByTag": true,
"seenByServer": true,
"seenByPlatform": true,
"converted": false
}
],
"nextCursor": "eyJpZCI6ImNtM2sy"
}
What the main fields mean:
verdictandscorefollow the rules in How detection works. A click ispendinguntil its verdict is final, at most a few minutes after landing.reasonsholds reason codes, worst first. The full list of codes is in How detection works.analyzedisfalsefor clicks recorded after your monthly clicks and click packs ran out. They have no score and no reasons.seenByTag,seenByServerandseenByPlatformsay which witnesses reported the click: the tag, a server hit or tracking template, and Google's own click record.
Exclusions#
An exclusion is one network Spurn keeps away from your ads: a single IP address, or a /24 (IPv4) or /48 (IPv6) block. See Google Ads exclusion lists for how they reach Google Ads.
GET /exclusions#
Lists the exclusions for the key's site, both the ones Spurn added and the ones people added.
curl https://spurn.io/api/v1/exclusions \
-H "Authorization: Bearer sp_sec_XXXXXXXX"
Example response. The field names and values below are examples, not the full schema:
{
"data": [
{
"id": "cm3k3a1b20007",
"cidr": "198.51.100.0/24",
"kind": "subnet",
"source": "auto",
"state": "active",
"reasons": ["DATACENTER", "REPEAT_IP"],
"clickCount": 14,
"note": null,
"firstSeenAt": "2026-11-12T16:03:10.000Z",
"lastSeenAt": "2026-11-14T08:41:52.000Z",
"expiresAt": "2026-12-14T08:41:52.000Z"
},
{
"id": "cm3k3a1b20009",
"cidr": "203.0.113.24/32",
"kind": "ip",
"source": "manual",
"state": "active",
"reasons": [],
"clickCount": 0,
"note": "Competitor office",
"firstSeenAt": "2026-11-10T11:20:00.000Z",
"lastSeenAt": "2026-11-10T11:20:00.000Z",
"expiresAt": null
}
]
}
state is active, expired or removed. expiresAt is null for an exclusion that lasts until someone removes it.
POST /exclusions#
Adds a network to the site's exclusion list. Spurn delivers it to your linked ad accounts the same way as one you add in the dashboard, and records it in the change log.
| Field | Description |
|---|---|
cidr | An IPv4 or IPv6 address, or a /24 (IPv4) or /48 (IPv6) block. A single address is stored as /32 or /128. |
note | Optional. Up to 500 characters, shown next to the entry in the dashboard. |
curl -X POST https://spurn.io/api/v1/exclusions \
-H "Authorization: Bearer sp_sec_XXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "cidr": "203.0.113.24", "note": "Competitor office" }'
The response is the new exclusion, in the same shape as an item from GET /exclusions.
DELETE /exclusions/{id}#
Removes an exclusion. Spurn takes its entries off every linked ad account and records the removal in the change log. A removed exclusion can be restored from the dashboard.
curl -X DELETE https://spurn.io/api/v1/exclusions/cm3k3a1b20009 \
-H "Authorization: Bearer sp_sec_XXXXXXXX"
Success returns 204 No Content.
Ingest endpoints#
These are the endpoints Spurn's own integrations call. Use them when you build an integration Spurn does not ship. Only paid landings are recorded; anything else is ignored.
POST /collect#
What the tag in the browser calls, with the site's public key. The body is JSON sent as text/plain, so the browser sends it without a CORS preflight; send it with fetch and keepalive: true, or with navigator.sendBeacon. Any origin may call it, and Spurn checks the request's origin and the landing host against the site's domain and extra hosts.
Every event has these fields:
{ "v": 1, "k": "sp_pub_XXXXXXXX", "t": "land", "pv": "<pageview uuid>", "vid": "<visitor id>" }
t is the event type: land, eng or conv. Each type adds its own fields.
A landing (land), sent once per page view:
{
"v": 1, "k": "sp_pub_XXXXXXXX", "t": "land",
"pv": "<pageview uuid>", "vid": "<visitor id>",
"url": "https://shop.example.com/?gclid=Cj0KCQiAexample",
"ref": "https://www.google.com/",
"fp": "<fingerprint>",
"tz": "Europe/London",
"lang": "en-GB",
"fbp": "fb.1.1794690000000.123",
"fbc": "fb.1.1794690000000.IwARexample",
"sig": {}
}
url is the full landing URL and ref the referrer. fp is a hash of stable device signals. tz is the browser's IANA timezone and lang its language. fbp and fbc are Meta's browser ids, sent when the Meta pixel has set them. sig carries browser signals; its contents are internal to Spurn's tag and can change between tag versions.
Engagement (eng), sent at 10 seconds, at 30 seconds and when the page is hidden or closed:
{
"v": 1, "k": "sp_pub_XXXXXXXX", "t": "eng",
"pv": "<pageview uuid>", "vid": "<visitor id>",
"dwell": 12000, "scroll": 64, "moves": 31, "acts": 2, "pages": 1
}
dwell is milliseconds on the page, scroll the furthest scroll as a percentage, moves pointer movements, acts interactions and pages pages viewed.
A conversion (conv):
{
"v": 1, "k": "sp_pub_XXXXXXXX", "t": "conv",
"pv": "<pageview uuid>", "vid": "<visitor id>",
"value": 49.9, "cur": "USD", "oid": "1001", "cid": "<click id from the _spc cookie, optional>"
}
The response to land:
{ "ok": true, "verdict": "pending", "score": 0, "meta": false, "uet": false }
verdict is valid, suspicious, invalid or pending, and score runs from 0 to 100. meta and uet tell the tag whether to fire its Meta and Microsoft UET events for this visitor (see GTM and pixel events). eng and conv return 204 No Content.
curl -X POST https://spurn.io/api/v1/collect \
-H "Content-Type: text/plain" \
-H "Origin: https://shop.example.com" \
-d '{"v":1,"k":"sp_pub_XXXXXXXX","t":"land","pv":"6f1c2e1a-1b7d-4c8e-9a51-2f0d3c4b5a69","vid":"v_8d2f","url":"https://shop.example.com/?gclid=test-123","ref":"","fp":"a1b2c3d4","tz":"Europe/London","lang":"en-GB","sig":{}}'
POST /hit#
A server hit: the visitor's IP address and user agent, sent from your server when a paid landing arrives. It lets Spurn see clicks whose page JavaScript never runs.
| Field | Description |
|---|---|
url | The full landing URL, query string included. |
ip | The visitor's IP address. Behind a proxy or CDN, take it from the header your proxy sets, not from the socket. |
ua | The visitor's user agent. |
ref | Optional. The referrer. |
ts | Optional. When the landing happened. |
lang | Optional. The Accept-Language value. |
source | woocommerce, wordpress, nextjs, cloudflare, node or custom. Use custom for your own integration. |
curl -X POST https://spurn.io/api/v1/hit \
-H "Authorization: Bearer sp_sec_XXXXXXXX" \
-H "Content-Type: application/json" \
-d '{
"url": "https://shop.example.com/products/linen-sheets?gclid=Cj0KCQiAexample",
"ip": "203.0.113.7",
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
"ref": "https://www.google.com/",
"lang": "en-GB",
"source": "custom"
}'
If url is not a paid landing, Spurn ignores the hit and returns 204. Otherwise it merges the hit into a click the tag reported with the same click id in the last 10 minutes, or creates a server-only click. Any 2xx means the hit was accepted.
Send hits without making the visitor wait: fire and forget, as the WordPress plugin (non-blocking request) and the Next.js package (waitUntil) do.
POST /conversion#
Records an order or lead against the click that brought it, from your server. A purchase lowers a click's score; see Mitigation in How detection works.
| Field | Description |
|---|---|
orderId | Your order or lead id. |
value | The order value, in major units (49.9 for $49.90). |
currency | ISO 4217 code, such as USD. |
clickId | Optional. The click id, from the _spc cookie or your own records. |
pageviewId | Optional. The page view id, from the _spc cookie. |
visitorId | Optional. The tag's visitor id. |
ts | Optional. When the conversion happened. |
curl -X POST https://spurn.io/api/v1/conversion \
-H "Authorization: Bearer sp_sec_XXXXXXXX" \
-H "Content-Type: application/json" \
-d '{ "orderId": "1001", "value": 49.9, "currency": "USD", "clickId": "Cj0KCQiAexample" }'
Spurn matches the conversion to the most recent click from the last 30 days with the same page view, click id or visitor. Send at least one of the three. The _spc cookie the tag sets holds {pageviewId}.{clickId}, with - in place of a missing click id, so a server that can read the shopper's cookies can pass both.