Crawler hits

POST https://api.snowanalytics.app/api/beacon/hits

AI 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_key

The 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.

FieldTypeNotes
pathstringRequired. The request path, cut at 2,048 characters.
userAgentstringRequired. The raw User-Agent header, cut at 512 characters.
ipstringThe client's IPv4 or IPv6 address. Without it every hit stays unverified. SnowAnalytics keeps only a keyed hash of it.
formatmarkdown | htmlWhat your server sent back.
statusCodenumberThe response status.
referrerstringThe Referer header, if any.
occurredAtstringISO 8601 time. A time more than 24 hours away from SnowAnalytics' clock is replaced by the time SnowAnalytics receives the hit.
askedForMarkdownbooleanThe client asked for Markdown, by Accept header or a .md URL.
fromBrowserbooleanThe request carried a Sec-Fetch-* header.
method, rawPath, signature, signatureInput, signatureAgentstringOnly 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.
headersobjectOptional 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": "…" }:

StatuscodeMeaning
400BAD_REQUESTThe 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.
401UNAUTHORIZEDThe key is missing, invalid, or lacks bots:write.
403BEACON_HOST_NOT_ALLOWEDhost isn't the site's domain or an alias.
413PAYLOAD_TOO_LARGEThe body is over 4 MB.
429RATE_LIMITEDMore than 120 batches a minute for this key. See Rate limits.
500INTERNAL_ERRORSomething 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 }.

On this page