Open in ChatGPT Claude Perplexity

Reporting paths

A content_retrieved event can reach OpenAttribution from three directions. Each path has different trade-offs, and they're designed to work together.

Just want AI bot visibility for your site? The quickstart gets you there in about five minutes - register your domain, deploy the Cloudflare Worker. This page is the wider picture: how edge, marketplace, and agent-side reporting fit together.

Which integration is right for you?

I run a site on Cloudflare → Quickstart - register your domain and deploy the open source Worker. Full reference: Cloudflare integration.

I run a site on another CDN or stack → The Cloudflare and Fastly edge workers work today. WordPress, Vercel, Netlify, Akamai and CloudFront integrations are in progress - see the integrations status page, or get in touch for early access.

I'm building an AI agent → Request agent access for an API key, then follow agent integration against the telemetry spec and JSON Schemas.

I run a platform → Content marketplace, affiliate or ad network, attribution vendor, analytics or monetisation tool. Start with platform setup - one sign-up and approval, one API key - then pick your integration: reporting events, Measurement partners (delegated read), or the affiliate and ad networks guide.

The model: OpenAttribution is a three-sided open standard with telemetry as the joint product.

Content owners register a verified domain and read telemetry for their content.
Platforms (marketplaces, networks, attribution vendors) emit retrieval events and ctx-bound engagement events, and may hold delegated read access.
Agents own the session lifecycle, emit grounded and cited events, and issue ctx tokens for outbound clicks.

The specs are open and Apache 2.0. api.openattribution.org is operated by NarrativAI Ltd as the contracted production implementation; a competing implementation can be built from the same spec.

Your infrastructure reports

Your infrastructure detects AI bot requests and reports them directly. No cooperation from the agent required. Whether you run a news site, a product catalogue, or a brand portal - you control the data at source.

flow

AI Agent ──GET──> Your CDN / CMS / Origin Server
                          │
                          ├── Detect AI user agent
                          ├── Read Content-Telemetry-ID header (if present)
                          └── POST content_retrieved event to OA telemetry endpoint

The telemetry spec calls this source_role: "origin" or source_role: "edge" depending on whether the event is reported from the origin server or an edge network (CDN).

When the requesting agent includes an Content-Telemetry-ID header, that ID correlates your event with the agent's own event - two independent observations of the same retrieval. When the agent doesn't include the header, you still get the event. It's just one-sided.

Integrations

Cloudflare Worker at the edge

WordPress, Vercel, Netlify, Akamai and CloudFront integrations are in progress - see the integrations status page.

Content marketplace reporting

Content marketplaces and licensed content repositories act as intermediaries. When an agent retrieves content through a marketplace, the marketplace can report the retrieval event on behalf of the content owner.

flow

AI Agent ──GET──> Content Marketplace (Microsoft, Amazon, etc.)
                          │
                          ├── Serves licensed content to agent
                          └── POST content_retrieved event (source_role: "index")

The telemetry spec calls this source_role: "index". The marketplace has visibility into which content was served and can report events with full metadata - content URL, licensing terms, and the telemetry ID for correlation.

See the marketplaces and networks guide for the full retrieval and engagement flow, including ctx-bound clickthrough reporting.

Agent-side reporting

The AI agent itself reports what content it retrieved. This is the most complete path - the agent has full visibility into what it fetched, how it used the content, and what the user did with the response.

flow

AI Agent (Google, OpenAI, Perplexity, etc.)
    │
    ├── Retrieves content from web / index / RAG  → POST content_retrieved (source_role: "agent")
    ├── Loads it into the generation context      → POST content_grounded
    ├── Cites it in the response                  → POST content_cited
    ├── Shows the source to the user              → POST content_displayed
    └── User clicks through                       → POST content_engaged

Agent-side reporting covers the full event lifecycle - retrieval, grounding, citation, display, and engagement. When combined with server-side reporting on the same retrieval, the Content-Telemetry-ID header correlates both observations into a single, corroborated event.

Request agent access to get an API key, then see the agent integration guide and the full specification.

Cross-observer correlation

The three paths aren't alternatives - they're designed to overlap. When multiple observers report the same retrieval, the events are correlated using the Content-Telemetry-ID header.

correlation

Agent includes header:  Content-Telemetry-ID: 550e8400-e29b-41d4-a716-446655440000

Your server reports:     { "type": "content_retrieved", "content_telemetry_id": "550e8400-..." }
Agent reports:         { "type": "content_retrieved", "content_telemetry_id": "550e8400-..." }

Same content_telemetry_id + same content_url = one retrieval, two independent witnesses.

Server-side reporting works without the header - you still see the retrieval. But with the header, you get corroboration. Two observations are stronger than one.