REST API endpoint
GET /v1/ai-traffic/install — everything needed to send crawler hits
Returns the ingest endpoint, your workspace's HMAC signing secret, the signature header, the replay window, the daily cap and a copy-pasteable edge worker.
Karl-Gustav Kallasmaa, Founder & CEOLast updated The request
Paste this and change the key. Every endpoint takes a bearer key and none takes a workspace id — the key names the workspace.
curl https://api.attensira.com/v1/ai-traffic/install \
-H "Authorization: Bearer atn_live_<your key>"
The response (200)
Abbreviated, never invented — this is the shape the published reference documents.
{
"endpoint": "https://webapp.attensira.com/v1/visits",
"method": "POST",
"signature_header": "X-Attensira-Signature",
"signing_secret": "…",
"project_id": "prj_5b22",
"replay_window_seconds": 300,
"daily_visit_cap": 100000,
"worker": "export default { async fetch(request, env) { … } }",
"notes": ["Deploy in front of the tracked domain."]
}
What goes wrong, and what it means
The condition on the left, the correct reading of it on the right.
- You deployed a snippet found elsewhere and nothing arrives
- A snippet without your workspace's values sends data nowhere. The generated copy carries the ingest endpoint and the credentials tied to your workspace, which is why it is generated rather than published.
- Requests are rejected as replays
- The signature is only accepted inside the replay window this response reports. Clock skew on the edge is the usual cause, not a bad secret.
- Nothing appears after deploying correctly
- Nothing appears until a crawler actually fetches a page. On a low-traffic site that can take days, and it is not evidence that the install failed.
What this endpoint cannot tell you
The limits are part of the answer, not a disclaimer under it.
- It cannot verify who visited. User agents are self-reported and trivially spoofed, and Attensira does not publish a verified-bot claim it cannot stand behind, so this data is directional evidence about coverage rather than an audited log.
- It cannot make browser analytics see crawlers. AI crawlers do not execute JavaScript, so any client-side beacon has already missed them by the time it runs — which is why collection has to happen in edge middleware.
Most of this API reads data. This endpoint exists to help you produce some: it returns everything required to start sending AI-crawler hits from your own edge, in one call, already filled in for your workspace.
Why the values have to be generated
The response carries the ingest endpoint, the header the signature goes in, the signing secret for your workspace, your project id, the replay window, the daily cap, and a worker you can paste.
Every one of those except the header name is workspace-specific, which is the reason there is an endpoint rather than a documentation page with a snippet on it. A snippet copied from somewhere else — a blog post, an old ticket, another workspace — deploys cleanly and sends data nowhere, and the failure is completely silent. Fetch the values, deploy the values.
The signing secret is unusual among Attensira credentials in that it can be shown again. It is derived from the workspace id rather than randomly generated and hashed, so re-fetching it is normal. An API key is the opposite: displayed once, stored as a hash, replaced rather than recovered if lost.
The constraint that makes edge middleware necessary
There is a hard technical reason this is not a script you drop into a page. AI crawlers do not execute JavaScript. A beacon in the browser has, by definition, never recorded one and never will — by the time the script runs, the only visitors left are humans with browsers.
Edge middleware runs on every request, including the ones that never become a rendered page, and it is the only layer at which a crawler fetch exists to be counted at all. Any existing analytics that shows you zero AI crawler traffic is telling you about its own measurement method rather than about the crawlers.
What the data is worth, and what it is not
It tells you that requests arrived, when, and against which paths. That is a coverage signal, and it is genuinely useful: a page nothing has fetched cannot become a citation, and a whole section that crawlers never reach is worth checking for robots rules, auth walls or redirects.
What it is not is verified attribution. Attensira does not claim to prove that a given request came from a specific named crawler, because user agents are self-reported and trivially spoofed, and publishing a verified-bot claim it could not stand behind would be worse than publishing nothing. Read the data as directional evidence about coverage.
Nor is crawler activity evidence of visibility. Crawlers fetch; models answer. They run on different schedules through different pipelines, and a rise in one does not predict the other. Reconciling the two numbers is the mistake this whole area of the product is designed to stop you making.
After you deploy
Nothing appears until a crawler actually fetches a page, and on a low-traffic site that can take days. An empty view an hour after deploying is the expected outcome, not a broken install.
Once data does arrive, it surfaces in the bot area of the analytics endpoint, whose rows carry visits, pages reached, a purpose mix and a last-seen timestamp rather than the rate fields the other areas use. That area is the cross-check to run before rewriting any page that appears to underperform.
Its twin on the other surface
The get_ai_traffic_install MCP tool returns the same install details and takes no parameters. It is worth having enabled for the obvious reason: the moment somebody asks an assistant why AI traffic is empty, the answer is frequently that nothing has been installed yet, and the tool turns that from a support conversation into a paste.
Questions people ask
- Why is the signing secret safe to fetch more than once?
- Because it is derived from the workspace id, so it is stable and can be shown again. That is the opposite of an API key, which is displayed exactly once.
- Why does this have to run at the edge?
- Because AI crawlers do not run JavaScript. A browser beacon only ever sees humans, so the request has to be counted server-side, before anything renders.
- What is the replay window for?
- It bounds how long a signed request is accepted, which is what stops a captured request being replayed. The response tells you the window in seconds.
- How long before data appears?
- Until a crawler fetches a page. On a low-traffic site that can be days, and an empty view in the first hours is expected rather than a fault.
- Does crawler traffic tell me I am being cited?
- No. Crawlers fetch pages and models answer prompts; they are separate systems, and one does not predict the other.
Sources
Every factual statement above, with the page it came from and the date that page was read.
Attensira's AI traffic documentation states that AI crawlers do not execute JavaScript, so a client-side beacon has never seen one, and that edge middleware is the only layer where a crawler fetch exists to be counted.
docs.attensira.com · retrieved
“AI crawlers do not execute JavaScript. A client-side beacon, no matter how it is written, has never seen one and never will”
Attensira's documentation states that it does not claim to prove a request came from a specific named crawler, because user agents are self-reported and trivially spoofed.
docs.attensira.com · retrieved
“User agents are self-reported and trivially spoofed, and Attensira does not publish a verified-bot claim it cannot stand behind.”
The Attensira API reference states that the AI traffic signing secret is derived from the workspace id, so it is stable and can be shown again, unlike an API key.
docs.attensira.com · retrieved
“The signing secret is derived from the workspace id, so it is stable and can be shown again — unlike your API key, which is displayed exactly once.”