Crawler hits
POST https://api.snowanalytics.app/api/beacon/hitsAI crawlers never run JavaScript, so the browser snippet can't see them. Your
server does, and it reports each request here. The
crawler install sets this up with the @snowseo/beacon
package. Use this page when you write your own reporter.
Authentication
Send a server key in either header:
Authorization: Bearer snw_live_your_key
X-Beacon-Key: snw_live_your_keyThe key must carry bots:write, which every server key does. It names the site,
so there is no site parameter. A missing key, an invalid key and a key without the
scope all get 401.
Request body
Send JSON, up to 4 MB, with 1 to 500 hits:
curl -X POST https://api.snowanalytics.app/api/beacon/hits \
-H "X-Beacon-Key: snw_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"host": "example.com",
"hits": [
{
"path": "/pricing",
"userAgent": "Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; GPTBot/1.1; +https://openai.com/gptbot)",
"ip": "203.0.113.7",
"format": "html",
"statusCode": 200,
"occurredAt": "2026-10-28T09:41:00.000Z"
}
]
}'host is optional because the key already names the site. When you send it, it
must be the site's domain or one of its aliases,
without a scheme or port. A leading www. is ignored.
Each hit describes one request. Send the raw facts and don't label them: SnowAnalytics recognises the crawler, names its operator and checks who it really is.
| Field | Type | Notes |
|---|---|---|
path | string | Required. The request path, cut at 2,048 characters. |
userAgent | string | Required. The raw User-Agent header, cut at 512 characters. |
ip | string | The client's IPv4 or IPv6 address. Without it every hit stays unverified. SnowAnalytics keeps only a keyed hash of it. |
format | markdown | html | What your server sent back. |
statusCode | number | The response status. |
referrer | string | The Referer header, if any. |
occurredAt | string | ISO 8601 time. A time more than 24 hours away from SnowAnalytics' clock is replaced by the time SnowAnalytics receives the hit. |
askedForMarkdown | boolean | The client asked for Markdown, by Accept header or a .md URL. |
fromBrowser | boolean | The request carried a Sec-Fetch-* header. |
method, rawPath, signature, signatureInput, signatureAgent | string | Only for requests that carry Web Bot Auth headers: the HTTP method, the path with its query string, and the Signature, Signature-Input and Signature-Agent headers, verbatim. |
headers | object | Optional lowercase request headers, as strings. |
Response
{ "accepted": 1, "skipped": 0, "reasons": { "malformed": 0, "unrecognized": 0 } }accepted counts the hits recorded, and accepted plus skipped always equals
the number you sent. A hit without a path or userAgent is malformed. One
that matches no known crawler and didn't ask for Markdown is unrecognized, which
is normal and usually the largest number. A bad hit never rejects the rest of the
batch.
SnowAnalytics answers once it has classified the batch. Checking who sent each hit and storing it follow, so a hit appears in reports within a minute. Hits are not idempotent: a retry after a timeout can count a hit twice.
Errors
Errors carry { "error": "…", "code": "…" }:
| Status | code | Meaning |
|---|---|---|
400 | BAD_REQUEST | The body isn't JSON, hits is empty or over 500, or host is empty or too long. Don't retry the batch as it is. |
401 | UNAUTHORIZED | The key is missing, invalid, or lacks bots:write. |
403 | BEACON_HOST_NOT_ALLOWED | host isn't the site's domain or an alias. |
413 | PAYLOAD_TOO_LARGE | The body is over 4 MB. |
429 | RATE_LIMITED | More than 120 batches a minute for this key. See Rate limits. |
500 | INTERNAL_ERROR | Something went wrong on SnowAnalytics' side. Retry with a growing delay. |
The first accepted batch marks crawler tracking as installed, even if it holds no crawler. From then on, AI traffic counts the crawlers it reports.
To check the endpoint is reachable, GET /api/beacon/hits needs no key and
answers { "status": "ok", "protocol": 1, "maxHitsPerRequest": 500 }.