Open in ChatGPT Claude Perplexity

Troubleshooting

The problems people hit most often, what causes them, and how to fix them. If something here does not match what you are seeing, get in touch via the contact form.

Domain not verifying

A domain stays unverified until OpenAttribution can confirm you control it. Verification runs from OA's side, so the check has to be able to reach your site or your DNS.

.well-known file not reachable

If you are verifying with the manifest at /.well-known/openattribution.json, check it actually responds:

bash

curl -sS -i https://example.com/.well-known/openattribution.json

You want a 200 with Content-Type: application/json and a body that parses as JSON. Common causes of failure: the file is served over HTTP not HTTPS, the path is wrong (it must be exactly /.well-known/openattribution.json at the apex), a redirect to a login wall or CDN challenge page, a 404 from a static-site host that does not serve dot-prefixed paths, or invalid JSON. Fix the file, then re-run verification from the domains page in the dashboard.

DNS TXT record not propagated

If you are verifying with a DNS TXT record, check it has propagated:

bash

dig +short TXT example.com

The record you were given should appear in the output. DNS changes can take anywhere from a few minutes to a few hours depending on your provider's TTL - if you just added it, give it time and check again. Watch out for: editing the wrong zone, a stray quote or trailing space in the record value, or a record added to www.example.com instead of the apex.

Three verification methods

The domains page in the dashboard shows which methods are available for your domain - the .well-known manifest, a DNS TXT record, or an HTML meta tag. Any one of them is enough. Pick whichever you can change fastest.

API key errors

Authenticated endpoints want an API key in the X-API-Key header. Two failure modes, two status codes:

Status	Meaning	Fix
`401`	Missing, malformed, revoked, or unrecognised key	Check the `X-API-Key` header is present and is the full key (including the `oat_pub_` or `oat_pk_` prefix). Mint a fresh one from `/api-keys` in the dashboard if you have lost it - the raw value is shown once.
`403`	Key is valid but lacks the right scope, or you are asking for data it is not bound to	A write call needs `telemetry:write`; a read call needs `telemetry:read`. Content-owner keys (`oat_pub_`) only see their own verified domains. Delegated reads also need a valid delegation - see below.

Wrong key type is a common one: agents, marketplaces, and networks use a platform key (oat_pk_); content owners reading their own data use a content-owner key (oat_pub_). See Authentication for the full picture.

Org creation never uses an API key

Creating an organisation needs a logged-in user session, not an API key - org-scoped keys cannot create new principals. If a POST /api/v1/identity/organizations call fails, you are probably authenticating with a key instead of a session token.

Events not appearing in the dashboard

Almost always one of these:

Give it days, not minutes

The dashboard is built for the cadence of AI crawling, which is bursty and sparse. A site with modest traffic might see a handful of content_retrieved events a day, not a steady stream. If you deployed an hour ago and the dashboard is empty, that is normal - check back tomorrow. There is also a short ingest-to-display lag (seconds to a minute or so), so even a test request will not show up instantly.

Wrong host

Events go to the ingest host, not the read/control host:

Purpose	Host
Reporting events and sessions	`https://telemetry.openattribution.org/events`, `/sessions/*`
Reading your data, identity, delegations, click tokens	`https://api.openattribution.org`

Posting events to api.openattribution.org will not land them where the dashboard reads from.

Cloudflare Worker not on the right route

If you deployed the open source Worker but see nothing: confirm it is bound to a route that actually matches your traffic (typically example.com/* and *.example.com/*) and that the route is on the zone serving the pages AI bots fetch. Check the API key secret is set on the Worker (an unset secret means every telemetry call silently 401s and the Worker drops it so it never affects your page). The Worker logs in the Cloudflare dashboard will show whether it is running and whether the upstream call succeeded. See the Cloudflare integration page and the quickstart.

No AI traffic yet

The Worker only emits an event when it sees a recognised AI crawler or assistant fetch a page. If nothing has crawled you since you deployed, there is nothing to report. PolicyCheck will tell you which bots your robots.txt and firewall currently allow.

GET /ctx/{token} returns 404

Click-token lookup is two-sided opt-in. The endpoint returns 404 unless both of these are true:

The agent that issued the token has share_sessions_via_click_tokens enabled.
The content owner whose URLs were cited has visible_in_click_token_lookups enabled.

Both default to false. A 404 here usually means one side has not opted in - not that the token is invalid. Each party can toggle their flag in the dashboard settings page or via PATCH /api/v1/identity/settings. Also check the token has not expired (click tokens last 90 days) and that you are using a platform API key with telemetry:read.

Delegated access not working

A measurement partner reads a content owner's data by adding delegated_from={grantor_org_id} to a content-owner GET endpoint and authenticating with its own platform key. If that returns 403:

Wrong org id. delegated_from must be the content owner's organisation ID, not yours, not a domain, not the delegation record's ID.
Missing scope. The querying key needs telemetry:read.
No active delegation. The content owner has to have granted access to your org (POST /api/v1/identity/delegations on their side, or the Measurement partners page in their dashboard). Until they do, every delegated read 403s.
Revoked. Only the grantor can revoke, and once they do the access disappears immediately. Confirm with them, or check GET /api/v1/identity/delegations.

More detail on the delegation endpoints is in the API reference and the Measurement partners page.